Extracts a private function | expression | variable for BDD unit testing
[
Note currently breaks after Node v4.2.2 due to require code changes.
Some Node versions work, but most do not.
describeIt(sourceFilename, functionSignature, useBeforeEach, testCallbacks);
// sourceFilename - full CommonJS filename
// functionSignature - foo(), add(a, b), etc to find the function | var name = ...
// useBeforeEach - optional, boolean - use beforeEach when setting up (otherwise by default using before)
// testCallbacks - BDD test callback, like in "describe"
Imagine you want to unit test function getFoo from file get-foo.js
// get-foo.js
(function reallyPrivate() {
function getFoo() {
return 'foo';
}
}());How would you do this? The function getFoo is private to the closure, not exported. Impossible
without extra processing step, like this one? Nope. Simple to do via describe-it, built
on top of really-need.
npm install --save-dev describe-it
// get-foo-spec.js
// assumes BDD like Mocha
var describeIt = require('describe-it');
describeIt(__dirname + '/get-foo.js', 'getFoo()', function (getFn) {
it('returns "foo"', function () {
var getFoo = getFn();
console.assert(getFoo() === 'foo');
});
});If you have several unit tests, just grab the function before each
// get-foo-spec.js
var describeIt = require('describe-it');
describeIt(__dirname + '/get-foo.js', 'getFoo()', function (getFn) {
var getFoo;
beforeEach(function () {
getFoo = getFn();
});
it('is a function', function () {
console.assert(typeof getFoo === 'function');
});
it('returns "foo"', function () {
console.assert(getFoo() === 'foo');
});
});How does it work? Read this section of the blog post Bending JavaScript rules. In short, it installs a Node hook using really-need that extracts a reference to the desired code using code rewrite on load.
You can extract and unit test even named functional expressions, commonly used as callbacks.
For example, we can unit test the function double used as an iterator callback in the code below
// double-numbers.js
function doubleNumbers(numbers) {
return numbers.map(function double(x) {
return x * 2;
});
}// double-numbers-spec.js
describeIt(__dirname + '/double-numbers', 'double(x)', function (getDouble) {
before('it is executed at least once', function () {
var doubleThem = require('./double-numbers');
doubleThem([1, 2]);
});
it('doubles numbers', function () {
var double = getDouble();
la(double(5) === 10);
});
});Note that because our functional expression is deep inside the code, we must execute the code at least once
before the function double gets assigned.
Often I create code or values instead of having functional expressions (imperative style). For example, instead of writing a function myself, I would create a function using composition. Using this library we can extract variables too.
// variable-foo.js
var foo = 'foo';
// variable-foo-spec.js
var describe = require('describe-it');
describe(__dirname + '/variable-foo', 'var foo', function (getFoo) {
it('has value "foo"', function () {
la(getFoo() === "foo");
});
});Nice!
You can see this in action in the following unit test ggit/changed-files-spec.js that
tests pipeline of functions stdoutToGrouped in the file ggit/changed-files.js.
You don't have to call a function to extract the value from the code. If you do not list any arguments in the callback function, then the value will automatically be placed onto the context object (under the extracted name). For example,
describeIt(fooFilename, 'getFoo()', function () {
it('returns "foo"', function () {
la(this.getFoo() === 'foo');
});
});I am testing this library using Mocha, which I find much nicer to work with.
Jasmine has a broken afterEach order, see the open pull request to fix it.
Because describe-it tries to behave nicely and clean up after itself, you might NOT
have the function inside your own afterEach blocks.
describeIt(..., function (getFn) {
it(...);
afterEach(function () {
var fn = getFn();
// Nope, fn is undefined by this time
});
});As a work around, keep the reference to the function around
describeIt(..., function (getFn) {
var fn;
beforeEach(function () {
fn = getFn();
});
it(...);
afterEach(function () {
// use fn
});
});We follow the convention and preserve the original context inside the describeIt callback, thus
you can assign the extracted value to a property
desribeFunction(fooFilename, 'getFoo()', function (getFn) {
beforeEach(function () {
this.getFoo = getFn();
});
it('returns "foo"', function () {
la(this.getFoo() === 'foo');
});
});If something is not working, you can see verbose output using an environment variable. For example
if you run unit tests that use describe-it via npm test, you can see the log messages by running
DEBUG=describe npm test
Author: Gleb Bahmutov © 2015
License: MIT - do anything with the code, but don't blame me if it does not work.
Spread the word: tweet, star on github, etc.
Support: if you find any problems with this module, email / tweet / open issue on Github
Copyright (c) 2015 Gleb Bahmutov
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.