unit.js
Version:
Simple, intuitive and flexible unit testing framework for javascript / Node.js (browser and server). Integrates awesome assertions libraries like Must.js, Should.js, Assert of Node.js, Sinon.js and other friendly features (promise, IoC, plugins, ...).
270 lines (183 loc) • 8.31 kB
Markdown
[](https://www.npmjs.org/package/unit.js)
[](https://david-dm.org/unitjs/unit.js)
[](https://www.npmjs.org/package/unit.js)
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:
* &
* &
* &
* &
* &
* &
**=** [](https://unitjs.com)
Unit.js supports [dependency injection](https://unitjs.com/guide/dependency-injection.html) and is extensible via a [plugins system](https://unitjs.com/guide/plugins.html) 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:
```js
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.
* [Unit.js documentation](https://unitjs.com)
* [Unit.js introduction](https://unitjs.com/guide/introduction.html)
* [Quickstart](https://unitjs.com/guide/quickstart.html)
* [Helpers](https://unitjs.com/guide/helpers.html)
* Community support on the IRC channel __&
You can install Unit.js with NPM (Node Package Manager).
```shell
npm install unit.js
```
### For the browser
See [Unit.js in the browser](https://unitjs.com/guide/browser.html).
## Usage
See [quickstart](https://unitjs.com/guide/quickstart.html) in the guide.
### Example (proposal) of structured unit tests suite
```js
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 :
Unit.js provides a plugins system (based on [Noder.io](https://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](https://unitjs.com/guide/plugins.html) tutorial in the guide.
### Dependency injection (IOC)
Unit.js supports dependency injection (Inversion Of Control).
See [dependency-injection](https://unitjs.com/guide/dependency-injection.html) in the guide.
### Promise
Unit.js integrates [bluebird](https://github.com/petkaantonov/bluebird) for handling asynchronous unit tests.
Bluebird is a fully featured promise library with focus on innovative features and performance.
Example:
```js
var 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](https://en.wikipedia.org/wiki/Behavior-driven_development) style:
```js
test
.promise
.given(function() {
// ...
})
.when(function() {
// ...
})
.then(function() {
// ...
})
;
```
_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:
```js
var test = require('unit.js');
// your old tests with your old assertion lib
// and your new tests with Unit.js
```
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 Introduction](https://unitjs.com/guide/introduction.html)
* [Unit.js Quickstart](https://unitjs.com/guide/quickstart.html)
Takes a little time to learn (see [UnitJS.com](https://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](https://unitjs.com/guide/assert-node-js.html), [Shoud.js](https://unitjs.com/guide/should-js.html), [Must.js](https://unitjs.com/guide/must-js.html), [Sinon.js](https://unitjs.com/guide/sinon-js.html), [Atoum](http://docs.atoum.org/en/chapter2.html#Writing-tests)).
## Related
Useful _snippets_ for code editor:
* [Unit.js package for Atom.io editor](https://github.com/unitjs/atom-unitjs)
* [Unit.js package for Sublime Text editor](https://github.com/unitjs/sublime-unitjs)
## 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](https://unitjs.com/license.html).
## Author
Unit.js is designed and built with love by
| [](https://nicolab.net) |
|---|
| [Nicolas Talle](https://nicolab.net) |
| [](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=PGRH4ZXP36GUC) |