Package Exports

unit.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (unit.js) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Unit.js

Simple, intuitive and flexible unit testing framework for javascript.

+ Must.js
+ Should.js
+ Assert of Node.js
+ Sinon.js
+ fluent style like Atoum
+ other friendly features.

Unit.js is test runner and framework agnostic, by default Unit.js run with Mocha but works with any other runner (works with Jasmine and other). Unit.js can be used as an assertion library or as a full stack unit testing framework ready to use with Mocha.

Unit.js introduction
Getting started
Unit.js documentation
Community support on the IRC channel #unit.js (freenode).

Several styles

Basic

var obj = {message: 'hello', name: 'Nico'};

var str = 'Hello world';

// Structure of a request object.
// By example, provided by Express framework and other modules.
var req = {
  headers: {
    'content-type': 'application/json'
  }
};

test.object(obj).hasProperty('name');
test.object(obj).hasProperty('message', 'hello');

test.string(str).startsWith('Hello');
test.string(str).contains('world');
test.string(str).match(/[a-zA-Z]/);

test.value(req).hasHeader('content-type');

test.value(req).hasHeader('content-type', 'application/json');
// or
test.value(req).hasHeaderJson();

Fluent

var obj = {message: 'hello', name: 'Nico'};

var str = 'Hello world';

// Structure of a request object.
// By example, provided by Express framework and other modules.
var req = {
  headers: {
    'content-type': 'application/json'
  }
};

test
  .object(obj)
    .hasProperty('name')
    .hasProperty('message', 'hello')

  .string(str)
    .startsWith('Hello')
    .contains('world')
    .match(/[a-zA-Z]/)

  .value(req)
    .hasHeader('content-type')
    .hasHeader('content-type', 'application/json')
    // or
    .hasHeaderJson()
;

Expressive

var obj = {message: 'hello', name: 'Nico'};

var trigger = function(){
  throw new Error('Whoops !');
};

test
  .object(obj)
    .hasProperty('name')
    .hasProperty('message', 'hello')

  .when('Add "job" property', obj.job = 'developper')

  .then(function(){
    test.object(obj).hasProperty('job', 'developper');
  })

  .case('Delete all properties', function() {

    test
      .when(function() {
        delete obj.name;
        delete obj.message;
        delete obj.job;
      })

      .then(function(){
        test.object(obj).isEmpty();
      })
    ;
  })

  .if(obj.message = 'Hello world !')
  .and(obj.name = 'say hello')

  .string(obj.message)
    .startsWith('Hello')
    .endsWith('world !')
    .notContains('foobar')

  .given(obj = new Date(2014, 02))

  .date(obj)
    .isBefore(new Date(2020, 12))
    .isAfter(new Date(2010, 01))
    .isBetween(new Date(2014, 01), new Date(2014, 12))

  .then('Test the exception')

  .exception(trigger)
    .hasMessage('Whoops !')
    .hasMessage(/whoops/i)
    .isInstanceOf(Error)

  // or
  .error(trigger)
    .hasMessage('Whoops !')
    .hasMessage(/whoops/i)
;

Integrates the great assertions libraries

Assert

// test 'string' type
test.assert(typeof 'foobar' == 'string');

// then that actual value '==' expected value
test.assert.equal('foobar', 'foobar');

// then that actual value '===' expected value
test.assert.strictEqual('foobar', 'foobar');

// this shortcut works also like this
var assert = test.assert;

// test 'string' type
assert(typeof 'foobar' == 'string');

// then that actual value '==' expected value
assert.equal('foobar', 'foobar');

// then that actual value '===' expected value
assert.strictEqual('foobar', 'foobar');

See the assert tutorial.

Must.js

// test 'string' type
test.must('foobar').be.a.string();

// then that actual value '==' expected value
test.must('foobar' == 'foobar').be.true();

// then that actual value '===' expected value
test.must('foobar').be.equal('foobar');

// Must.js library (alternative style)
var must = test.must;

// test 'string' type
('foobar').must.be.a.string();

// then that actual value '==' expected value
('foobar' == 'foobar').must.be.true();

// then that actual value '===' expected value
('foobar').must.be.equal('foobar');

// this shortcut works also like this

// test 'string' type 
must('foobar').be.a.string();

// then that actual value '==' expected value
must('foobar' == 'foobar').be.true();

// then that actual value '===' expected value
must('foobar').be.equal('foobar');

See the Must.js tutorial.

Should.js

// test 'string' type
test.should('foobar').be.type('string');

// then that actual value '==' expected value
test.should('foobar' == 'foobar').be.ok;

// then that actual value '===' expected value
test.should('foobar').be.equal('foobar');

// Should.js library (alternative style)
var should = test.should;

// test 'string' type
('foobar').should.be.type('string');

// then that actual value '==' expected value
('foobar' == 'foobar').should.be.ok;

// then that actual value '===' expected value
('foobar').should.be.equal('foobar');

// this shortcut works also like this

// test 'string' type 
should('foobar').be.type('string');

// then that actual value '==' expected value
should('foobar' == 'foobar').be.ok;

// then that actual value '===' expected value
should('foobar').be.equal('foobar');

See the Should.js tutorial.

httpAgent

Testing Node.js HTTP servers (response and request) with the httpAgent.

httpAgent uses the modules supertest and superagent.

var 
  test = require('unit.js'),
  express = require('express')
;

var app = express();

app.get('/user', function(req, res){
  res.send(200, { name: 'tobi' });
});

test.httpAgent(app)
  .get('/user')
  .expect('Content-Type', /json/)
  .expect('Content-Length', '20')
  .expect(200)
  .end(function(err, res){
    if (err) throw err;
  });

Anything you can do with supertest and superagent, you can do with httpAgent - for example multipart file uploads!

test.httpAgent(app)
  .post('/user')
  .attach('avatar', 'test/fixtures/homeboy.jpg')
  // ...

Sinon.js

Mock :

function once(fn) {
  var 
    returnValue, 
    called = false
  ;

  return function () {
    if (!called) {
      called = true;
      returnValue = fn.apply(this, arguments);
    }
    return returnValue;
  };
};

var myAPI = { method: function () {} };
var mock = test.mock(myAPI);

mock
  .expects('method')
  .once()
  .returns(42)
;

var proxy = once(myAPI.method);

test.number(proxy()).is(42);

mock.verify();

Sandbox :

it('test using sandbox', test.sinon.test(function () {

  var myAPI = { 
    method: function () {} 
  };

  var mockMyApi = this.mock(myAPI).expects('method').once().returns(42);

  var proxy = once(myAPI.method);

  test.number(proxy()).isIdenticalTo(42);

  mockMyApi.verify();
}));

See the Sinon.js tutorial.

Installation

Unit.js is a Node.js module. You can install it with NPM (Node Package Manager).

npm install unit.js

Usage

create test directory create a file named example.js in the test directory.

path/your/project/test/example.js

Write this below code in the example.js file :

// load Unit.js module
var test = require('unit.js');

// just for example of tested value
var example = 'hello';

// assert that example variable is a string
test.string(example);

// or with Must.js
test.must(example).be.a.string();

// or with assert
test.assert(typeof example === 'string');

Run the tests with Mocha (or other runner)

node_modules/unit.js/bin/test test/example.js

example.js is tested :)

OR alias

node_modules/.bin/test test/example.js

Display the spec report with -R spec

node_modules/.bin/test test/example.js -R spec

You can launch the tests for all files in the test directory

node_modules/.bin/test test -R spec --recursive

See also the Mocha tutorial.

Example (proposal) of structured unit tests suite

var test = require('unit.js');

describe('Learning by the example', function(){

  it('example variable', function(){

    // just for example of tested value
    var example = 'hello world';

    test
      .string(example)
        .startsWith('hello')
        .match(/[a-z]/)

      .given(example = 'you are welcome')
        .string(example)
          .endsWith('welcome')
          .contains('you')

      .when('"example" becomes an object', function(){
        
        example = {
          message: 'hello world', 
          name: 'Nico', 
          job: 'developper',
          from: 'France'
        };
      })

      .then('test the "example" object', function(){

        test
          .object(example)
            .hasValue('developper')
            .hasProperty('name')
            .hasProperty('from', 'France')
            .contains({message: 'hello world'})
        ;
      })

      .if(example = 'bad value')
        .error(function(){
          example.badMethod();
        })
    ;

  });

  it('other test case', function(){
    // other tests ...
  });
  
});

Result :

Result of unit tests with Unit.js

Migrating to Unit.js

Unit.js should work with any framework (and runner) unit tests. I tested Unit.js with Mocha and Jasmine, it works very well with these two runners.

For use Unit.js in an existing tests suite, you can write your new tests with Unit.js in your new files of unit tests.

For use Unit.js in an existing file of unit tests, you just have to load it with require('unit.js') and use it like any assertion lib, example:

var test = require('unit.js');

// your old tests with your old assertion lib 
// and your new tests with Unit.js

Fully documented

The API of Unit.js is fanatically documented with examples for all assertions.

API doc : the API of all asserters.
spec : the spec of all asserters.
guide : several tutorials to learn the unit testing with Unit.js.
Unit.js Quickstart

Learning

Now take a little time to learn (see UnitJS.com) with the tutorials in the guide, the API doc and looking at the many examples of codes in the spec doc and unit tests.

You are operational and productive from the outset. The style of writing your unit tests is not imposed, it depends on your preferences. Unit.js is flexible enough to fit your coding style without effort on your part.

The mastery of Unit.js is very fast, especially if you already know one of the libraries of assertions (Assert of Node.js, Shoud.js, Must.js, Sinon.js, Atoum).

If you use the Sublime Text editor, I wrote a package for Sublime Text (pack of useful snippets for writing unit tests with Unit.js in Sublime Text editor).

License

Unit.js is released under a Lesser GNU Affero General Public License, which in summary means:

You can use this program for no cost.
You can use this program for both personal and commercial reasons.
You do not have to share your own program's code which uses this program.
You have to share modifications (e.g bug-fixes) you've made to this program.

For more convoluted language, see the LICENSE.

Unit.js package for Sublime Text editor

Author

Unit.js is designed and built with love by


Nicolas Talle

unit.js