Skip to content

Latest commit

 

History

History
268 lines (183 loc) · 8.12 KB

README.md

File metadata and controls

268 lines (183 loc) · 8.12 KB

Unit.js

Actual version published on NPM Dependencies npm module downloads per month

Unit testing framework for javascript / Node.js.

Philosophy of Unit.js: modern, flexible, simple and intuitive.

Unit.js is an assertion library for Javascript, running on Node.js and in the browser. It works with any test runner and unit testing framework like Mocha, Jasmine, Karma, protractor (E2E test framework for Angular apps), QUnit, ... and more.

Unit.js provides an awesome API to write your unit tests in the way you prefer:

  • + Unit.js (fluent style)
  • + Assert (of Node.js)
  • + Must.js
  • + Should.js
  • + Sinon.js
  • + other friendly features.

= Unit JS unit testing framework for javascript

Unit.js supports dependency injection and is extensible via a plugins system easy to use.

The learning curve to be productive with Unit.js is very short. The list of assertions is fully documented in the API doc and assertions are expressive like:

test.string('hello');
test.object(user).hasProperty('email');
test.array(fruit).hasValue('kiwi');
test.assert(myVar === true);
test.bool(myVar).isTrue();

Unit.js was designed to provide the essential tools for writing unit tests with fun and qualities.

Installation

For Node.js

You can install Unit.js with NPM (Node Package Manager).

npm install unit.js

For the browser

See Unit.js in the browser.

Usage

See quickstart in the guide.

Example (proposal) of structured unit tests suite

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

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

    // just for example of tested value
    const 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

Plugins

Unit.js provides a plugins system (based on Noder.io) for extending Unit.js's assertions and interfaces.

It is possible to create a package works easily as a plugin for Unit.js and also as a standalone module or library.

Also, it's useful for bundled the code to re-use easily across multiple projects or for a large application with its specific modules (by writing plugins to facilitate the unit tests of each module).

See plugins tutorial in the guide.

Dependency injection (IOC)

Unit.js supports dependency injection (Inversion Of Control).

See dependency-injection in the guide.

Promise

Unit.js integrates bluebird for handling asynchronous unit tests.

Bluebird is a fully featured promise library with focus on innovative features and performance.

Example:

const fs = test.promisifyAll(require('fs'));

it('async function', function(done) {
  test
    .promise
    .given(anyAsyncFunction())
    .then(function(contents) {
      test.string(contents).contains('some value');
    })
    .catch(function(err){
      test.fail(err.message);
    })
    .finally(done)
    .done()
  ;
});

it('read file async', function(done) {
  fs
    .readFileAsync('./file.js', 'utf8')
    .then(function(contents){
      test.string(contents);
    })
    .catch(function(err){
      test.fail(err.message);
    })
    .finally(done)
    .done()
  ;
});

A light adjustment was added to write promise with BDD style:

test
  .promise
  .given(function() {
    // ...
  })
  .when(function() {
    // ...
  })
  .then(function() {
    // ...
  })
;

Migrating to Unit.js

Unit.js should work with any framework (and runner) of 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:

const 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.

Learning

Takes 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 examples.

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).

Related

Useful snippets for code 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.

Author

Unit.js is designed and built with love by

Nicolas Tallefourtane - Nicolab.net
Nicolas Talle
Make a donation via Paypal