Awesome
describe-it
Extracts a private function | expression | variable for BDD unit testing
[ describe-it-icon]describe-it-icon
Engine
Note currently breaks after Node v4.2.2 due to require
code changes.
Some Node versions work, but most do not.
Api
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"
Example
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.
Unit test any named function
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.
Unit test any assigned variable
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.
Assignment shortcut
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');
});
});
Note for Jasmine users
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
});
});
Context is preserved
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');
});
});
For devs
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
Small print
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
MIT License
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.