describe-it

Extracts a private function | expression | variable for BDD unit testing

[ describe-it-icon]describe-it-icon

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

• @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

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.