Extracts a private function / variable for BDD unit testing
npm install describe-it> Extracts a private function | expression | variable for BDD unit testing
[![describe-it-icon] [describe-it-icon]][describe-it-icon]
[![Build status][describe-it-ci-image] ][describe-it-ci-url]
[![dependencies][describe-it-dependencies-image] ][describe-it-dependencies-url]
[![devdependencies][describe-it-devdependencies-image] ][describe-it-devdependencies-url]
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
``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][1]? Nope. Simple to do via describe-it, built
on top of really-need.
npm install --save-dev describe-it
`js`
// 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
`js`
// 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][how] of the blog post [Bending JavaScript rules][bending].
In short, it installs a Node hook using really-need
that extracts a reference to the desired code using code rewrite on load.
[how]: http://glebbahmutov.com/blog/bending-javascript-rules/#why-nodejs-require-matters-step-7
[bending]: http://glebbahmutov.com/blog/bending-javascript-rules/
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
`js`
// double-numbers.js
function doubleNumbers(numbers) {
return numbers.map(function double(x) {
return x * 2;
});
}
`js`
// 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][4].
Using this library we can extract variables too.
`js`
// 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][5] that
tests pipeline of functions stdoutToGrouped in the file [ggit/changed-files.js][6].
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,
`js`
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][2] 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.
`js`
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
`js`
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
`js
desribeFunction(fooFilename, 'getFoo()', function (getFn) {
beforeEach(function () {
this.getFoo = getFn();
});
it('returns "foo"', function () {
la(this.getFoo() === 'foo');
});
});
`
[1]: http://philipwalton.com/articles/how-to-unit-test-private-functions-in-javascript/
[2]: https://github.com/jasmine/jasmine/pull/908
[3]: http://glebbahmutov.com/blog/picking-javascript-testing-framework/
[4]: http://glebbahmutov.com/blog/imperative-to-compose-example/
[5]: https://github.com/bahmutov/ggit/blob/master/spec/changed-files-spec.js
[6]: https://github.com/bahmutov/ggit/blob/master/src/changed-files.js
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
* @bahmutov
* glebbahmutov.com
* blog
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.
[describe-it-icon]: https://nodei.co/npm/describe-it.png?downloads=true
[describe-it-url]: https://npmjs.org/package/describe-it
[describe-it-ci-image]: https://travis-ci.org/bahmutov/describe-it.svg?branch=master
[describe-it-ci-url]: https://travis-ci.org/bahmutov/describe-it
[describe-it-dependencies-image]: https://david-dm.org/bahmutov/describe-it.svg
[describe-it-dependencies-url]: https://david-dm.org/bahmutov/describe-it
[describe-it-devdependencies-image]: https://david-dm.org/bahmutov/describe-it/dev-status.svg
[describe-it-devdependencies-url]: https://david-dm.org/bahmutov/describe-it#info=devDependencies