Should.js 4.4.2

global

assertion

assertion assert

assertion bool

assertion chaining

assertion contain

assertion equality

assertion errors

assertion matching

assertion numbers

assertion property

assertion strings

assertion types

“global” Members

should(obj)

Ⓢ Ⓣ

Our function should

Arguments

  1. obj (*):

    Object to assert

Returns

(should.Assertion)

:

Returns new Assertion for beginning assertion chain

Example

var should = require('should');
should('abc').be.a.string;

should.config

Ⓢ Ⓣ

Object with configuration.
It contains such properties:

  • checkProtoEql boolean - Affect if .eql will check objects prototypes

Example

var a = { a: 10 }, b = Object.create(null);
b.a = 10;

a.should.be.eql(b);
//not throws

should.config.checkProtoEql = true;
a.should.be.eql(b);
//throws AssertionError: expected { a: 10 } to equal { a: 10 } (because A and B have different prototypes)

should.extend([propertyName], [proto])

Ⓢ Ⓣ

Allow to extend given prototype with should property using given name. This getter will unwrap all standard wrappers like Number, Boolean, String.
Using should(obj) is the equivalent of using obj.should with known issues (like nulls and method calls etc).

Arguments

  1. [propertyName] (string):

    Name of property to add. Default is 'should'.
  2. [proto] (Object):

    Prototype to extend with. Default is Object.prototype.

Returns

({ name: string, descriptor: Object, proto: Object })

:

Descriptor enough to return all back

Example

var prev = should.extend('must', Object.prototype);

'abc'.must.startWith('a');

var should = should.noConflict(prev);
should.not.exist(Object.prototype.must);

should.noConflict([desc])

Ⓢ Ⓣ

Delete previous extension. If desc missing it will remove default extension.

Arguments

  1. [desc] ({ name: string, descriptor: Object, proto: Object }):

    Returned from should.extend object

Returns

(Function)

:

Returns should function

Example

var should = require('should').noConflict();

should(Object.prototype).not.have.property('should');

var prev = should.extend('must', Object.prototype);
'abc'.must.startWith('a');
should.noConflict(prev);

should(Object.prototype).not.have.property('must');

should.use(f)

Ⓢ Ⓣ

Simple utility function for a bit more easier should assertion extension

Arguments

  1. f (Function):

    So called plugin function. It should accept 2 arguments: should function and Assertion constructor

Returns

(Function)

:

Returns should function

Example

should.use(function(should, Assertion) {
  Assertion.add('asset', function() {
     this.params = { operator: 'to be asset' };

     this.obj.should.have.property('id').which.is.a.Number;
     this.obj.should.have.property('path');
 })
})

should.AssertionError(options)

Ⓢ Ⓣ

should AssertionError

Arguments

  1. options (Object)

should.Assertion(obj)

Ⓢ Ⓣ

should Assertion

Arguments

  1. obj (*):

    Given object for assertion

“assertion” Members

Assertion.add(name, func, [isGetter])

Ⓢ Ⓣ

Way to extend Assertion function. It uses some logic
to define only positive assertions and itself rule with negative assertion.

All actions happen in subcontext and this method take care about negation.
Potentially we can add some more modifiers that does not depends from state of assertion.

Arguments

  1. name (String):

    Name of assertion. It will be used for defining method or getter on Assertion.prototype
  2. func (Function):

    Function that will be called on executing assertion
  3. [isGetter] (Boolean):

    If this assertion is getter. By default it is false.

Example

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

     this.obj.should.have.property('id').which.is.a.Number;
     this.obj.should.have.property('path');
});

Assertion.alias(from, to)

Ⓢ Ⓣ

Create alias for some Assertion property

Arguments

  1. from (String):

    Name of to map
  2. to (String):

    Name of alias

Example

Assertion.alias('true', 'True');

Assertion#assert(expr)

Ⓢ Ⓣ

Base method for assertions. Before calling this method need to fill Assertion#params object. This method usually called from other assertion methods.
Assertion#params can contain such properties:

  • operator - required string containing description of this assertion
  • obj - optional replacement for this.obj, it usefull if you prepare more clear object then given
  • message - if this property filled with string any others will be ignored and this one used as assertion message
  • expected - any object used when you need to assert relation between given object and expected. Like given == expected (== is a relation)
  • details - additional string with details to generated message

Arguments

  1. expr (*):

    Any expression that will be used as a condition for asserting.

Example

var a = new should.Assertion(42);

a.params = {
 operator: 'to be magic number',
}

a.assert(false);
//throws AssertionError: expected 42 to be magic number

Assertion#fail()

Ⓢ Ⓣ

Shortcut for Assertion#assert(false).

Example

var a = new should.Assertion(42);

a.params = {
 operator: 'to be magic number',
}

a.fail();
//throws AssertionError: expected 42 to be magic number

Assertion#not

Ⓢ Ⓣ

Negation modifier. Current assertion chain become negated. Each call invert negation on current assertion.

Assertion#any

Ⓢ Ⓣ

Any modifier - it affect on execution of sequenced assertion to do not check all, but check any of.

“assertion assert” Members

should.fail(actual, expected, message, operator)

Ⓢ Ⓣ

Node.js standard assert.fail.

Arguments

  1. actual (*):

    Actual object
  2. expected (*):

    Expected object
  3. message (string):

    Message for assertion
  4. operator (string):

    Operator text

should.ok(value, [message])

Ⓢ Ⓣ

Node.js standard assert.ok.

Arguments

  1. value (*)
  2. [message] (string)

should.equal(actual, expected, [message])

Ⓢ Ⓣ

Node.js standard assert.equal.

Arguments

  1. actual (*)
  2. expected (*)
  3. [message] (string)

should.notEqual(actual, expected, [message])

Ⓢ Ⓣ

Node.js standard assert.notEqual.

Arguments

  1. actual (*)
  2. expected (*)
  3. [message] (string)

should.deepEqual(actual, expected, [message])

Ⓢ Ⓣ

Node.js standard assert.deepEqual.

Arguments

  1. actual (*)
  2. expected (*)
  3. [message] (string)

should.notDeepEqual(actual, expected, [message])

Ⓢ Ⓣ

Node.js standard assert.notDeepEqual.

Arguments

  1. actual (*)
  2. expected (*)
  3. [message] (string)

should.strictEqual(actual, expected, [message])

Ⓢ Ⓣ

Node.js standard assert.strictEqual.

Arguments

  1. actual (*)
  2. expected (*)
  3. [message] (string)

should.notStrictEqual(actual, expected, [message])

Ⓢ Ⓣ

Node.js standard assert.notStrictEqual.

Arguments

  1. actual (*)
  2. expected (*)
  3. [message] (string)

should.throws(block, [error], [message])

Ⓢ Ⓣ

Node.js standard assert.throws.

Arguments

  1. block (Function)
  2. [error] (Function)
  3. [message] (String)

should.doesNotThrow(block, [message])

Ⓢ Ⓣ

Node.js standard assert.doesNotThrow.

Arguments

  1. block (Function)
  2. [message] (String)

should.ifError(err)

Ⓢ Ⓣ

Node.js standard assert.ifError.

Arguments

  1. err (Error)

should.exist(obj, [msg])

Ⓢ Ⓣ

Assert obj exists, with optional message.

Aliases

should.exists

Arguments

  1. obj (*)
  2. [msg] (String)

Example

should.exist(1);
should.exist(new Date());

should.not.exist(obj, [msg])

Ⓢ Ⓣ

Asserts obj does not exist, with optional message.

Aliases

should.not.exists

Arguments

  1. obj (*)
  2. [msg] (String)

Example

should.not.exist(null);
should.not.exist(void 0);

“assertion bool” Members

Assertion#true

Ⓢ Ⓣ

Assert given object is exactly true.

Aliases

Assertion#True

Example

(true).should.be.true;
false.should.not.be.True;

({ a: 10}).should.not.be.true;

Assertion#false

Ⓢ Ⓣ

Assert given object is exactly false.

Aliases

Assertion#False

Example

(true).should.not.be.false;
false.should.be.False;

Assertion#ok

Ⓢ Ⓣ

Assert given object is thuthy according javascript type conversions.

Example

(true).should.be.ok;
''.should.not.be.ok;
should(null).not.be.ok;
should(void 0).not.be.ok;

(10).should.be.ok;
(0).should.not.be.ok;

“assertion chaining” Members

Assertion#be

Ⓢ Ⓣ

Simple chaining. It actually do nothing.

Aliases

Assertion#an, Assertion#of, Assertion#a, Assertion#and, Assertion#have, Assertion#with, Assertion#is, Assertion#which, Assertion#the

“assertion contain” Members

Assertion#containEql(other)

Ⓢ Ⓣ

Assert that given object contain something that equal to other. It uses should-equal for equality checks.
If given object is array it search that one of elements was equal to other.
If given object is string it checks if other is a substring - expected that other is a string.
If given object is Object it checks that other is a subobject - expected that other is a object.

Arguments

  1. other (*):

    Nested object

Example

[1, 2, 3].should.containEql(1);
[{ a: 1 }, 'a', 10].should.containEql({ a: 1 });

'abc'.should.containEql('b');
'ab1c'.should.containEql(1);

({ a: 10, c: { d: 10 }}).should.containEql({ a: 10 });
({ a: 10, c: { d: 10 }}).should.containEql({ c: { d: 10 }});
({ a: 10, c: { d: 10 }}).should.containEql({ b: 10 });
// throws AssertionError: expected { a: 10, c: { d: 10 } } to contain { b: 10 }
//            expected { a: 10, c: { d: 10 } } to have property b

Assertion#containDeepOrdered(other)

Ⓢ Ⓣ

Assert that given object is contain equally structured object on the same depth level.
If given object is an array and other is an array it checks that the eql elements is going in the same sequence in given array (recursive)
For string it is working as Assertion#containEql If given object is an object it checks that the same keys contain deep equal values (recursive) On other cases it try to check with.eql`

Arguments

  1. other (*):

    Nested object

Example

[ 1, 2, 3].should.containDeepOrdered([1, 2]);
[ 1, 2, [ 1, 2, 3 ]].should.containDeepOrdered([ 1, [ 2, 3 ]]);

'123'.should.containDeepOrdered('1')

({ a: 10, b: { c: 10, d: [1, 2, 3] }}).should.containDeepOrdered({a: 10});
({ a: 10, b: { c: 10, d: [1, 2, 3] }}).should.containDeepOrdered({b: {c: 10}});
({ a: 10, b: { c: 10, d: [1, 2, 3] }}).should.containDeepOrdered({b: {d: [1, 3]}});

Assertion#containDeep(other)

Ⓢ Ⓣ

The same like Assertion#containDeepOrdered but all checks on arrays without order.

Arguments

  1. other (*):

    Nested object

Example

[ 1, 2, 3].should.containDeep([2, 1]);
[ 1, 2, [ 1, 2, 3 ]].should.containDeep([ 1, [ 3, 1 ]]);

“assertion equality” Members

Assertion#eql(val, [description])

Ⓢ Ⓣ

Deep object equality comparison. For full spec see should-equal tests.

Arguments

  1. val (*):

    Expected value
  2. [description] (string):

    Optional message

Example

(10).should.be.eql(10);
('10').should.not.be.eql(10);
(-0).should.not.be.eql(+0);

NaN.should.be.eql(NaN);

({ a: 10}).should.be.eql({ a: 10 });
[ 'a' ].should.not.be.eql({ '0': 'a' });

Assertion#equal(val, [description])

Ⓢ Ⓣ

Exact comparison using ===.

Aliases

Assertion#exactly

Arguments

  1. val (*):

    Expected value
  2. [description] (string):

    Optional message

Example

10.should.be.equal(10);
'a'.should.be.exactly('a');

should(null).be.exactly(null);

“assertion errors” Members

Assertion#throw([message], [properties])

Ⓢ Ⓣ

Assert given function throws error with such message.

Aliases

Assertion#throwError

Arguments

  1. [message] (string|RegExp|Function|Object):

    Message to match or properties
  2. [properties] (Object):

    Optional properties that will be matched to thrown error

Example

(function(){ throw new Error('fail') }).should.throw();
(function(){ throw new Error('fail') }).should.throw('fail');
(function(){ throw new Error('fail') }).should.throw(/fail/);

(function(){ throw new Error('fail') }).should.throw(Error);
var error = new Error();
error.a = 10;
(function(){ throw error; }).should.throw(Error, { a: 10 });
(function(){ throw error; }).should.throw({ a: 10 });

“assertion matching” Members

Assertion#match(other, [description])

Ⓢ Ⓣ

Asserts if given object match other object, using some assumptions:
First object matched if they are equal,
If other is a regexp and given object is a string check on matching with regexp
If other is a regexp and given object is an array check if all elements matched regexp
If other is a regexp and given object is an object check values on matching regexp
If other is a function check if this function throws AssertionError on given object or return false - it will be assumed as not matched
If other is an object check if the same keys matched with above rules
All other cases failed

Arguments

  1. other (*):

    Object to match
  2. [description] (string):

    Optional message

Example

'foobar'.should.match(/^foo/);
'foobar'.should.not.match(/^bar/);

({ a: 'foo', c: 'barfoo' }).should.match(/foo$/);

['a', 'b', 'c'].should.match(/[a-z]/);

(5).should.not.match(function(n) {
  return n < 0;
});
(5).should.not.match(function(it) {
   it.should.be.an.Array;
});
({ a: 10, b: 'abc', c: { d: 10 }, d: 0 }).should
.match({ a: 10, b: /c$/, c: function(it) {
   return it.should.have.property('d', 10);
}});

[10, 'abc', { d: 10 }, 0].should
.match({ '0': 10, '1': /c$/, '2': function(it) {
   return it.should.have.property('d', 10);
}});

Assertion#matchEach(other, [description])

Ⓢ Ⓣ

Asserts if given object values or array elements all match other object, using some assumptions:
First object matched if they are equal,
If other is a regexp - matching with regexp
If other is a function check if this function throws AssertionError on given object or return false - it will be assumed as not matched
All other cases check if this other equal to each element

Arguments

  1. other (*):

    Object to match
  2. [description] (string):

    Optional message

Example

[ 'a', 'b', 'c'].should.matchEach(/\w+/);
[ 'a', 'a', 'a'].should.matchEach('a');

[ 'a', 'a', 'a'].should.matchEach(function(value) { value.should.be.eql('a') });

{ a: 'a', b: 'a', c: 'a' }.should.matchEach(function(value) { value.should.be.eql('a') });

“assertion numbers” Members

Assertion#NaN

Ⓢ Ⓣ

Assert given object is NaN

Example

(10).should.not.be.NaN;
NaN.should.be.NaN;

Assertion#Infinity

Ⓢ Ⓣ

Assert given object is not finite (positive or negative)

Example

(10).should.not.be.Infinity;
NaN.should.not.be.Infinity;

Assertion#within(start, finish, [description])

Ⓢ Ⓣ

Assert given number between start and finish or equal one of them.

Arguments

  1. start (number):

    Start number
  2. finish (number):

    Finish number
  3. [description] (string):

    Optional message

Example

(10).should.be.within(0, 20);

Assertion#approximately(value, delta, [description])

Ⓢ Ⓣ

Assert given number near some other value within delta

Arguments

  1. value (number):

    Center number
  2. delta (number):

    Radius
  3. [description] (string):

    Optional message

Example

(9.99).should.be.approximately(10, 0.1);

Assertion#above(n, [description])

Ⓢ Ⓣ

Assert given number above n.

Aliases

Assertion#greaterThan

Arguments

  1. n (number):

    Margin number
  2. [description] (string):

    Optional message

Example

(10).should.be.above(0);

Assertion#below(n, [description])

Ⓢ Ⓣ

Assert given number below n.

Aliases

Assertion#lessThan

Arguments

  1. n (number):

    Margin number
  2. [description] (string):

    Optional message

Example

(0).should.be.above(10);

“assertion property” Members

Assertion#enumerable(name, [val])

Ⓢ Ⓣ

Asserts given object has enumerable property with optionally value

Arguments

  1. name (string):

    Name of property
  2. [val] (*):

    Optional property value to check

Example

({ a: 10 }).should.have.enumerable('a');

Assertion#property(name, [val])

Ⓢ Ⓣ

Asserts given object has property with optionally value. On success it change given object to be value of property.

Arguments

  1. name (string):

    Name of property
  2. [val] (*):

    Optional property value to check

Example

({ a: 10 }).should.have.property('a');

Assertion#properties(names)

Ⓢ Ⓣ

Asserts given object has properties. On this method affect .any modifier, which allow to check not all properties.

Arguments

  1. names (Array|...string|Object):

    Names of property

Example

({ a: 10 }).should.have.properties('a');

Assertion#length(n, [description])

Ⓢ Ⓣ

Asserts given object has property length with given value n

Aliases

Assertion#lengthOf

Arguments

  1. n (number):

    Expected length
  2. [description] (string):

    Optional message

Example

[1, 2].should.have.length(2);

Assertion#ownProperty(name, [description])

Ⓢ Ⓣ

Asserts given object has own property. On success it change given object to be value of property.

Aliases

Assertion#hasOwnProperty

Arguments

  1. name (string):

    Name of property
  2. [description] (string):

    Optional message

Example

({ a: 10 }).should.have.ownProperty('a');

Assertion#empty

Ⓢ Ⓣ

Asserts given object is empty. For strings, arrays and arguments it checks .length property, for objects it checks keys.

Example

''.should.be.empty;
[].should.be.empty;
({}).should.be.empty;

Assertion#keys([keys])

Ⓢ Ⓣ

Asserts given object has exact keys.

Aliases

Assertion#key

Arguments

  1. [keys] (Array|...string|Object):

    Keys to check

Example

({ a: 10}).should.have.keys('a');
({}).should.have.keys();

Assertion#propertyByPath(properties)

Ⓢ Ⓣ

Asserts given object has nested property in depth by path. On success it change given object to be value of final property.

Arguments

  1. properties (Array|...string):

    Properties path to search

Example

({ a: {b: 10}}).should.have.propertyByPath('a', 'b').eql(10);

“assertion strings” Members

Assertion#startWith(str, [description])

Ⓢ Ⓣ

Assert given string starts with prefix

Arguments

  1. str (string):

    Prefix
  2. [description] (string):

    Optional message

Example

'abc'.should.startWith('a');

Assertion#endWith(str, [description])

Ⓢ Ⓣ

Assert given string starts with prefix

Arguments

  1. str (string):

    Prefix
  2. [description] (string):

    Optional message

Example

'abc'.should.startWith('a');

“assertion types” Members

Assertion#Number

Ⓢ Ⓣ

Assert given object is number

Assertion#arguments

Ⓢ Ⓣ

Assert given object is arguments

Aliases

Assertion#Arguments

Assertion#type(type, [description])

Ⓢ Ⓣ

Assert given object has some type using typeof

Arguments

  1. type (string):

    Type name
  2. [description] (string):

    Optional message

Assertion#instanceof(constructor, [description])

Ⓢ Ⓣ

Assert given object is instance of constructor

Aliases

Assertion#instanceOf

Arguments

  1. constructor (Function):

    Constructor function
  2. [description] (string):

    Optional message

Assertion#Function

Ⓢ Ⓣ

Assert given object is function

Assertion#Object

Ⓢ Ⓣ

Assert given object is object

Assertion#String

Ⓢ Ⓣ

Assert given object is string

Assertion#Array

Ⓢ Ⓣ

Assert given object is array

Assertion#Boolean

Ⓢ Ⓣ

Assert given object is boolean

Assertion#Error

Ⓢ Ⓣ

Assert given object is error

Assertion#null

Ⓢ Ⓣ

Assert given object is null

Aliases

Assertion#Null