should 5.2.0

test framework agnostic BDD-style assertions


Platform: npm

Language: JavaScript

License: MIT

View on registry:

Install: npm install should


Join the chat at

Build Status

Selenium Test Status

should is an expressive, readable, framework-agnostic assertion library. The main goals of this library are to be expressive and to be helpful. It keeps your test code clean, and your error messages helpful.

should extends the Object.prototype with a single non-enumerable getter that allows you to express how that object should behave. It also returns itself when required with require. It does not mean that you should use it like getter - it is possible to use it as function call. For this use .noConflict function.

Upgrading instructions

Please check wiki page for upgrading instructions.


var should = require('should');
var user = {
 name: 'tj'
 , pets: ['tobi', 'loki', 'jane', 'bandit']
};'name', 'tj');'pets').with.lengthOf(4);
// If the object was created with Object.create(null)
// then it doesn't inherit `Object.prototype`, so it will not have `.should` getter
// so you can do:
should(user)'name', 'tj');
// also you can test in that way for null's
someAsyncTask(foo, function(err, result){

To begin

  1. Install it:

    $ npm install should --save-dev
  2. Require it and use:

    var should = require('should');

In browser

Well, even when browsers by complains of authors has 100% es5 support, it does not mean it has not bugs. Please see wiki for known bugs.

If you want to use should in browser, use the should.js file in the root of this repository, or build it yourself. To build a fresh version:

$ npm install
$ gulp script

The script is exported to window.Should. It is the same as using should statically:


Also, in the case of node.js, Object.prototype is extended with should (hence the capital S in window.Should):;
// the same
// window is host object;
// you should not really care about it

You can easy install it with npm or bower:

npm install should --save-dev
# or
bower install shouldjs/should.js

API docs

Actual api docs generated by jsdoc comments and available at

Usage examples

Please look on usage in examples


.not negates the current assertion.


.any allow for assertions with multiple parameters to assert any of the parameters (but not all). This is similar to the native JavaScript array.some.


chaining assertions

Every assertion will return a should.js-wrapped Object, so assertions can be chained. To help chained assertions read more clearly, you can use the following helpers anywhere in your chain: .an, .of, .a, .and, .be, .have, .with, .is, .which. Use them for better readability; they do nothing at all. For example:'name', 'tj');;

Almost all assertions return the same object - so you can easy chain them. But some (eg: .length and .property) move the assertion object to a property value, so be careful.

Adding own assertions

To add own assertion you need to call should.Assertion.add function. It accept 3 arguments:

  1. name of assertion method (string)
  2. assertion function (function)
  3. optional boolean value to mark if this assertion should be getter

What assertion function should do. It should check only positive case. should will handle .not itself. this in assertion function will be instance of should.Assertion and you must define in any way this.params object in your assertion function call before assertion check happen.

params object can contain several fields:

  • operator - it is string which describe your assertion
  • actual it is actual value, you can assume it is your own this.obj if you need to define you own
  • expected it is any value that expected to be matched this.obj

You can assume its usage in generating AssertionError message like: expected obj? || this.obj not? operator expected?

In should sources appeared 2 kinds of usage of this method.

First not preferred and used only for shortcuts to other assertions, e.g how defined:

Assertion.add('true', function() {;
}, true);

There you can see that assertion function do not define own this.params and instead call within the same assertion .exactly that will fill this.params. You should use this way very carefully, but you can use it.

Second way preferred and i assume you will use it instead of first.

Assertion.add('true', function() {
 this.params = { operator: 'to be true', expected: true };;
}, true);

in this case this.params defined and then used new assertion context (because called .should). Internally this way does not create any edge cases as first.

Assertion.add('asset', function() {
 this.params = { operator: 'to be asset' };'id');'path');
> ({ id: '10' });
AssertionError: expected { id: '10' } to be asset
 expected '10' to be a number
> ({ id: 10 });
AssertionError: expected { id: 10 } to be asset
 expected { id: 10 } to have property path


Actual list of contributors if you want to show it your friends.

To run the tests for should simply run:

$ make test



Yes, yes it does, with a single getter should, and no it won't break your code, because it does this properly with a non-enumerable property.

Also it is possible use it without extension.


MIT © 2010-2014 TJ Holowaychuk

веселые картинки развлекательные гифки интресные факты смешные видео смешные истории из соцсетей

Development Dependencies


GitHub Repository

shouldjs/should.js shouldjs/should.js

BDD style assertions for node.js -- test framework agnostic

Fork of tj/should.js

Language: JavaScript

Created: May 28, 2014 11:20

Last updated: March 31, 2015 02:20

Last pushed: March 30, 2015 12:24

Size: 1.73 MB

Stars: 479

Forks: 38

Watchers: 15

Open issues: 1

Top Contributors

Denis Bardadym TJ Holowaychuk Thomas Rix Aseem Kishore Paul Serby Travis Jeffery Nathan Rajlich alsotang Gabriel Falcão Nick Daugherty Gabriel Falkenberg Farid Nouri Neshat fediev Daniel Tony Lukasavage Volodymyr Shatsky Swift Fredrik Enestad Nathan Brown Rudolf Meijering


  • 5.2.0 - March 12, 2015 11:28
  • 5.1.0 - March 05, 2015 07:28
  • 5.0.1 - February 21, 2015 09:27
  • 5.0.0 - February 10, 2015 10:23
  • 4.6.5 - February 05, 2015 19:03
  • 4.6.4 - February 05, 2015 10:08
  • 4.6.3 - February 02, 2015 17:52
  • 4.6.2 - January 28, 2015 10:00
  • 4.6.1 - January 18, 2015 17:20
  • 4.6.0 - January 13, 2015 16:08
See all 70 releases

Related Projects

BDD style assertions for node.js -- test framework agnostic
Bower - JavaScript - MIT - Published 20 days ago - 479 stars
chai 2.2.0
BDD/TDD assertion library for node.js and the browser. Test framework agnostic.
npm - JavaScript - MIT - Updated 5 days ago - 1,697 stars
jobject 0.0.2
A class that adds properties to your class that are easily overriden and maintain direct accessor...
npm - JavaScript - Updated over 2 years ago - 1,954 stars
must 0.12.0
Testing and assertion library with friendly BDD syntax — Many expressive ...
npm - JavaScript - Other - Updated 10 months ago - 180 stars
must-dist 0.12.0
Testing and assertion library with friendly BDD syntax — Many expressive ...
npm - JavaScript - Other - Updated 8 months ago - 180 stars
веселые картинки развлекательные гифки интресные факты смешные видео смешные истории из соцсетей