Repo was moved to own organization. See https://github.com/shouldjs/should.js.

should.js

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

It extends the Object.prototype with a single non-enumerable getter that allows you to express how that object should behave, also it returns itself when required with require.

Example

var should = require('should');

var user = {
    name: 'tj'
  , pets: ['tobi', 'loki', 'jane', 'bandit']
};

user.should.have.property('name', 'tj');
user.should.have.property('pets').with.lengthOf(4);

// if the object was created with Object.create(null)
// then it doesn't inherit `Object` and have the `should` getter
// so you can do:

should(user).have.property('name', 'tj');
should(true).ok;

someAsyncTask(foo, function(err, result){
  should.not.exist(err);
  should.exist(result);
  result.bar.should.equal(foo);
});

To begin

1. Install it:

   $ npm install should --save-dev
   

2. Require it and use:

   var should = require('should');
   
   (5).should.be.exactly(5).and.be.a.Number;
   

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. It is built with browserify (see Makefile). To build a fresh version:

# you should have browserify
$ npm install -g browserify
$ make browser

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

Should(5).be.exactly(5)

Also, in the case of node.js, Object.prototype is extended with should (hence the capital S in window.Should):

window.should.be.exactly(window);
// the same
// window is host object
should.be.exactly(window);
// you should not really care about it

(5).should.be.exactly(5);

should.js uses EcmaScript 5 very extensively so any browser that support ES5 is supported. (IE <=8 not supported). See kangax's compat table to know which exactly.

You can easy install it with npm or bower:

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

Static should and assert module

For some rare cases should can be used statically, without Object.prototype. It can be a replacement for the node assert module:

assert.fail(actual, expected, message, operator) // just write wrong should assertion
assert(value, message), assert.ok(value, [message]) // should(value).ok
assert.equal(actual, expected, [message]) // should(actual).eql(expected, [message])
assert.notEqual(actual, expected, [message]) // should(actual).not.eql(expected, [message])
assert.deepEqual(actual, expected, [message]) // should(actual).eql(expected, [message])
assert.notDeepEqual(actual, expected, [message]) // should(actual).not.eql(expected, [message])
assert.strictEqual(actual, expected, [message]) // should(actual).equal(expected, [message])
assert.notStrictEqual(actual, expected, [message]) // should(actual).not.equal(expected, [message])
assert.throws(block, [error], [message]) // should(block).throw([error])
assert.doesNotThrow(block, [message]) // should(block).not.throw([error])
assert.ifError(value) // should(value).Error (to check if it is error) or should(value).not.ok (to check that it is falsy)

.not

.not negate current assertion.

.any

.any allow for assertions with multiple parameters to assert on any of parameters (not all)

Assertions

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:

user.should.be.an.instanceOf(Object).and.have.property('name', 'tj');
user.pets.should.be.instanceof(Array).and.have.lengthOf(4);

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.

.ok

Assert if chained object is truthy in javascript (ie: not '', null, undefined, 0 , NaN).

Assert truthfulness:

true.should.be.ok;
'yay'.should.be.ok;
(1).should.be.ok;
({}).should.be.ok;

or negated:

false.should.not.be.ok;
''.should.not.be.ok;
(0).should.not.be.ok;

Warning: No assertions can be done on null and undefined. e.g.

  undefined.should.not.be.ok;

will give you Uncaught TypeError: Cannot read property 'should' of undefined).

In order to test for null use

(err === null).should.be.true;

.true

Assert if chained object === true:

true.should.be.true;
'1'.should.not.be.true;

.false

Assert if chained object === false:

false.should.be.false;
(0).should.not.be.false;

.eql(otherValue)

Assert if chained object is equal to otherValue. The object is compared by its actual content, not just reference equality.

({ foo: 'bar' }).should.eql({ foo: 'bar' });
[1,2,3].should.eql([1,2,3]);
// see next example it is correct, even if it is different types, but actual content the same
[1, 2, 3].should.eql({ '0': 1, '1': 2, '2': 3 });

.equal(otherValue) and .exactly(otherValue)

Assert if chained object is strictly equal to otherValue (using === - no type conversion for primitive types and reference equivalence for reference types).

(4).should.equal(4);
'test'.should.equal('test');
[1,2,3].should.not.equal([1,2,3]);
(4).should.be.exactly(4);

.startWith(str)

Assert that a string starts with str.

'foobar'.should.startWith('foo');
'foobar'.should.not.startWith('bar');

.endWith(str)

Assert that a string ends with str.

'foobar'.should.endWith('bar');
'foobar'.should.not.endWith('foo');

.within(from, to)

Assert inclusive numeric range (<= to and >= from):

user.age.should.be.within(5, 50);
(5).should.be.within(5, 10).and.within(5, 5);

.approximately(num, delta)

Assert floating point number near num within delta margin:

(99.99).should.be.approximately(100, 0.1);

.above(num) and .greaterThan(num)

Assert numeric value above the given value (> num):

user.age.should.be.above(5);
user.age.should.not.be.above(100);
(5).should.be.above(0);
(5).should.not.be.above(5);

.below(num) and .lessThan(num)

Assert numeric value below the given value (< num):

user.age.should.be.below(100);
user.age.should.not.be.below(5);
(5).should.be.below(6);
(5).should.not.be.below(5);

.NaN

Assert numeric value is NaN:

(undefined + 0).should.be.NaN;

.Infinity

Assert numeric value is Infinity:

(1/0).should.be.Infinity;

.type(str)

Assert given object is of a particular type (using typeof operator):

user.should.be.type('object');
'test'.should.be.type('string');

.instanceof(constructor) and .instanceOf(constructor)

Assert given object is an instance of constructor (using instanceof operator):

user.should.be.an.instanceof(User);
[].should.be.an.instanceOf(Array);

.arguments

Assert given object is an Arguments:

var args = (function(){ return arguments; })(1,2,3);
args.should.be.arguments;
[].should.not.be.arguments;

.Object, .Number, .Array, .Boolean, .Function, .String, .Error

Assert given object is instance of the given constructor (shortcut for .instanceof assertion).

({}).should.be.an.Object;
(1).should.be.a.Number;
[].should.be.an.Array.and.an.Object;
(true).should.be.a.Boolean;
''.should.be.a.String;

.enumerable(name[, value])

Assert a property exists, is enumerable, and has optional value (compare using .eql):

'asd'.should.not.have.enumerable('0');
user.should.have.enumerable('name');
user.should.have.enumerable('age', 15);
user.should.not.have.enumerable('rawr');
user.should.not.have.enumerable('age', 0);
[1, 2].should.have.enumerable('0', 1);

.property(name[, value])

Assert property exists and has optional value (compare using .eql):

user.should.have.property('name');
user.should.have.property('age', 15);
user.should.not.have.property('rawr');
user.should.not.have.property('age', 0);
[1, 2].should.have.property('0', 1);

NB .property changes the chain's object to the given property's value, so be careful when chaining after .property!

.properties(propName1, propName2, ...) or .properties([propName1, propName2, ...]) or .properties(obj)

obj should be an object that maps properties to their actual values.

Assert all given properties exist and have given values (compare using .eql):

user.should.have.properties('name', 'age');
user.should.have.properties(['name', 'age']);
user.should.have.properties({
    name: 'denis',
    age: 24
});

.length(number) and .lengthOf(number)

Assert length property exists and has a value of the given number (shortcut for .property('length', number)):

user.pets.should.have.length(5);
user.pets.should.have.a.lengthOf(5);
({ length: 10}).should.have.length(10);

NB .length and .lengthOf change the chain's object to the given length value, so be careful when chaining!

.ownProperty(str) and .hasOwnProperty(str)

Assert given object has own property (