FAQ

Browsers/Node support

Supported all actual node versions (LTS + Current). Browsers support is about last three versions of evergreen browsers and IE9+ (IE9 and IE10 with known engine bugs - See Known Bugs page).

When testing with async calls (promises, callbacks etc).

E.g. with mocha you should call done callback argument with or without error. With last version of mocha you can return promise and mocha will evaluate it.

it('should call something', function test() {
  library.asyncCall(function(err, result) {
    should.fail(); 
   // this probably will not be called because test finished as soon `test` function finished
   // and assertion will look like not working
  })
})

it('should call something2', function test(done) {
  library.asyncCall(function(err, result) {
    should.fail(); 
   // in this case you will see test timeouts, again because done not called
  })
})

it('should call something3', function test(done) {
  library.asyncCall(function(err, result) {
    should.fail(); 
    done();
   // that is it, done called and mocha will wait for it call
  })
})

In the last example above, if the assertion fails, the test may still timeout.

The assertion library throws an error and done() never gets called.

Here is a fix:

it('should call something4', function test(done) {
  library.asyncCall(function(err, result) {
    if (err) return done(err);
    try {
      should.fail(); // the assertion
      return done(); // if the assertion passes, the done will be called
    } catch (err2) { // here we catch an error which assertion throws when it fails
      return done(err2); // we need to call done(err2) to finish the test which failed
    }
  })
})

With promises it is similar:

// in this case again assertion will not happen because test will finished before .then callback called
it('should call something', function test() {
  library.asyncCall.then(function(result) {
    should.fail(); 
  })
})

// again you will see timeout
it('should call something2', function test(done) {
  library.asyncCall.then(function(result) {
    should.fail(); 
  })
})

// correct way
it('should call something3', function test(done) {
  //return required for promise evaluation
  return library.asyncCall(function(err, result) {
    should.fail(); 
  }).then(function() { done() }, done);
//first argument is wrapped `done` in case you return something in previous call
})

// correct way with last mocha
it('should call something4', function test() {
  //just return it and mocha will do rest
  return library.asyncCall(function(err, result) {
    should.fail(); 
  })
})

Using should without getter

When you call require('should'), Object.prototype extended with should getter. So

var should = require('should');
delete Object.prototype.should;

//use should that was returned

Confusing names

If you think that should is confusing word for invoking it as a functions, you always can use others like assert, expect, must etc.

var should = require('should');
var assert = should, expect = should;

assert.exist(null);

expect({ a: 1}).to.have.property('a');

Or

Object.defineProperty(Object.prototype, 'must', {
  get: function() { 
     return this.should;//or should(this);
  },
  enumerable: false 
});

({a :1)).must.have.property('a');

Use should as global function

Object.defineProperty(global, 'should', {
  value: should
});

or

global.should = require('should').noConflict();
should.extend();