The 'should' npm package is an expressive, readable, framework-agnostic assertion library for Node.js and browsers. It extends the 'Object.prototype' with a single non-enumerable getter that allows you to express how your code should behave in a readable way. It can be used for writing tests and supports both BDD (Behavior-Driven Development) and TDD (Test-Driven Development) styles.
Chainable Assertions
Allows chaining multiple assertions together for readability and expressiveness.
should(value).be.exactly(42).and.be.a.Number();Type Assertions
Provides assertions to check the type of a variable.
should('test').be.a.String();Number Assertions
Includes assertions specifically for numbers, such as checking if a number is within a range.
should(10).be.above(5).and.below(15);Property Assertions
Allows asserting the presence and value of an object's property.
should({ name: 'Alice', age: 25 }).have.property('name', 'Alice');Equality Assertions
Enables asserting deep equality between objects or arrays.
should([1, 2, 3]).eql([1, 2, 3]);Error Assertions
Provides a way to assert that a function throws an error.
should(function() { throw new Error('fail'); }).throw();Chai is a BDD / TDD assertion library for node and the browser that can be delightfully paired with any javascript testing framework. It offers similar functionality to 'should' with chainable assertions but has a different syntax and additional interfaces like 'expect' and 'assert'.
Expect.js is a minimalistic BDD-style assertions library that can be used in Node.js or in the browser. It provides a similar API to 'should' but does not extend 'Object.prototype', which can be a desirable feature for some users to avoid potential conflicts.
Assert is a module that provides a simple set of assertion tests that can be used to test invariants. It is built into Node.js and offers a more traditional TDD assertion style, which is different from the BDD style provided by 'should'.
Jest is a delightful JavaScript Testing Framework with a focus on simplicity. It comes with its own assertion library and test runner. While it provides similar assertion capabilities, it is more than just an assertion library as it includes testing utilities and is often used as a complete testing solution.
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.
Please check wiki.
In 4.x .eql implementation was changed to fix old bug in deepEqual from node's assert module. To do not allow to assume that 10 is equal to '10'. You can still use old .eql implementation via should.config flags.
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.prototype`, so it will not have `.should` getter
// so you can do:
should(user).have.property('name', 'tj');
// also you can test in that way for null's
should(null).not.be.ok;
someAsyncTask(foo, function(err, result){
should.not.exist(err);
should.exist(result);
result.bar.should.equal(foo);
});
Install it:
$ npm install should --save-dev
Require it and use:
var should = require('should');
(5).should.be.exactly(5).and.be.a.Number;
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:
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);
You can easy install it with npm or bower:
npm install should --save-dev
# or
bower install shouldjs/should.js
Actual api docs generated by jsdoc comments and available at http://shouldjs.github.io.
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.
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.
Assert that a 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 performed on null and undefined values. 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;
Assert if a chained object === true:
true.should.be.true;
'1'.should.not.be.true;
Assert if a chained object === false:
false.should.be.false;
(0).should.not.be.false;
Asserts if a 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 });
By default for now .eql does not check object prototypes, so such test will pass:
var b = {a: 2};
var a = Object.create(null);
a.a = 2;
b.should.be.eql(a);
If you do not want such behaviour you can do:
should.config.checkProtoEql = true;
somewhere at the beginning of tests (or in tests where you need to test prototypes) and test upper will fail.
Asserts if a chained object is strictly equal to otherValue (using ===). It means primitive values compared as is (there is no any type conversion) and reference values compared by references.
(4).should.equal(4);
'test'.should.equal('test');
[1,2,3].should.not.equal([1,2,3]);
(4).should.be.exactly(4);
Assert that a string starts with str.
'foobar'.should.startWith('foo');
'foobar'.should.not.startWith('bar');
Assert that a string ends with str.
'foobar'.should.endWith('bar');
'foobar'.should.not.endWith('foo');
Assert inclusive numeric range (<= to and >= from):
user.age.should.be.within(5, 50);
(5).should.be.within(5, 10).and.within(5, 5);
Assert a floating point number is near num within the delta margin:
(99.99).should.be.approximately(100, 0.1);
Assert a numeric value is 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);
Assert a numeric value is 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);
Assert a numeric value is NaN:
(undefined + 0).should.be.NaN;
Assert a numeric value is Infinity:
(1/0).should.be.Infinity;
Assert a given object is of a particular type (using typeof operator):
user.should.be.type('object');
'test'.should.be.type('string');
Assert a given object is an instance of constructor (using instanceof operator):
user.should.be.an.instanceof(User);
[].should.be.an.instanceOf(Array);
Assert a given object is an Arguments:
var args = (function(){ return arguments; })(1,2,3);
args.should.be.arguments;
[].should.not.be.arguments;
Assert a 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;
Assert a property exists, is enumerable, and has an 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);
Assert property exists and has an 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!
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
});
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!
Assert given object has own property (using .hasOwnProperty):
({ foo: 'bar' }).should.have.ownProperty('foo').equal('bar');
NB .ownProperty and .hasOwnProperty change the chain's object to the given property value, so be careful when chaining!
Assert given value is empty. Strings, arrays, arguments with a length of 0, and objects without their own properties, are considered empty.
[].should.be.empty;
''.should.be.empty;
({}).should.be.empty;
(function() {
arguments.should.be.empty;
})();
Assert own object keys, which must match exactly, and will fail if you omit a key or two:
var obj = { foo: 'bar', baz: 'raz' };
obj.should.have.keys('foo', 'baz');
obj.should.have.keys(['foo', 'baz']);
({}).should.have.keys();
({}).should.have.keys('key'); //fail AssertionError: expected {} to have key 'key'missing keys: 'key'
Assert property exists and has optional value (compare using .eql):
var obj = { foo: 'bar', baz: 'raz', zad: { a: 10 } };
obj.should.have.propertyByPath('zad', 'a');
obj.should.not.have.propertyByPath(0, 1, 2);
NB .propertyByPath changes the chain's object to the given property's value if found
Assert given value to contain something .eql to otherValue. See examples to understand better:
'hello boy'.should.containEql('boy');
[1,2,3].should.containEql(3);
[[1],[2],[3]].should.containEql([3]);
[[1],[2],[3, 4]].should.not.containEql([3]);
({ b: 10 }).should.containEql({ b: 10 });
([1, 2, { a: 10 }]).should.containEql({ a: 10 });
[1, 2, 3].should.not.containEql({ a: 1 });
[{a: 'a'}, {b: 'b', c: 'c'}].should.containEql({a: 'a'});
[{a: 'a'}, {b: 'b', c: 'c'}].should.not.containEql({b: 'b'});
When .containEql check arrays it check elements to be in the same order in otherValue and object just to be presented.
Assert given value to contain something .eql to otherValue within depth. Again see examples:
'hello boy'.should.containDeep('boy');
[1,2,3].should.containDeep([3]);
[1,2,3].should.containDeep([1, 3]);
//but not
[1,2,3].should.containDeep([3, 1]);
({ a: { b: 10 }, b: { c: 10, d: 11, a: { b: 10, c: 11} }}).should
.containDeep({ a: { b: 10 }, b: { c: 10, a: { c: 11 }}});
[1, 2, 3, { a: { b: { d: 12 }}}].should.containDeep([{ a: { b: {d: 12}}}]);
[[1],[2],[3]].should.containDeep([[3]]);
[[1],[2],[3, 4]].should.containDeep([[3]]);
[{a: 'a'}, {b: 'b', c: 'c'}].should.containDeep([{a: 'a'}]);
[{a: 'a'}, {b: 'b', c: 'c'}].should.containDeep([{b: 'b'}]);
It does not search somewhere in depth it check all pattern in depth. Objects are checked
by properties key and value; arrays are checked like sub sequences. Everyting is compared using .eql.
Main difference with .containEql is that this assertion requires full type chain -
if asserted value is an object, otherValue should be also an object (which is sub object of given).
The same is true for arrays, otherValue should be an array which compared to be subsequence of given object.
Also exists assertion .containDeepOrdered which check arrays in the same order.
Assert given object matches otherValue.
Given: String, otherValue: regexp. Uses RegExp#exec(str):
username.should.match(/^\w+$/)
Given: Array, otherValue: regexp - assert each value match to regexp.
['a', 'b', 'c'].should.match(/[a-z]/);
['a', 'b', 'c'].should.not.match(/[d-z]/);
Given: Object, otherValue: regexp - assert own property's values to match regexp.
({ a: 'foo', c: 'barfoo' }).should.match(/foo$/);
({ a: 'a' }).should.not.match(/^http/);
Given: Anything, otherValue: function - assert if given value matched to function.
Function can use .should inside or return 'true' or 'false', in all other cases it do nothing. If you return value that return assertion, you will receive better error messages.
(5).should.match(function(n) { return n > 0; });
(5).should.not.match(function(n) { return n < 0; });
(5).should.not.match(function(it) { it.should.be.an.Array; });
(5).should.match(function(it) { return it.should.be.a.Number; });
Now compare messages:
(5).should.not.match(function(it) { it.should.be.a.Number; });
//AssertionError: expected 5 not to match [Function]
(5).should.not.match(function(it) { return it.should.be.a.Number; });
//AssertionError: expected 5 not to match [Function]
// expected 5 to be a number
Given: object, otherValue: another object - assert that object properties match to properties of another object in meaning that describe above cases. See examples:
({ 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); } });
[10, 'abc', { d: 10 }, 0].should
.match([10, /c$/, function(it) { return it.should.have.property('d', 10); }]);
Assert given property keys and values each match given check object.
If otherValue is RegExp, then each property value checked to match it:
(['a', 'b', 'c']).should.matchEach(/[a-c]/);
If otherValue is Function, then check each property value and key matched it:
[10, 11, 12].should.matchEach(function(it) { return it >= 10; });
[10, 11, 12].should.matchEach(function(it) { return it >= 10; });
In other cases it checks that each property value is .eql to otherValue:
[10, 10].should.matchEach(10);
Assert an exception is thrown:
(function(){
throw new Error('fail');
}).should.throw();
Assert an exception is not thrown:
(function(){
}).should.not.throw();
Assert exception message matches string:
(function(){
throw new Error('fail');
}).should.throw('fail');
Assert error message matches regexp:
(function(){
throw new Error('failed to foo');
}).should.throw(/^fail/);
Error properties to match some other properties (used .match):
var error = new Error();
error.a = 10;
(function(){ throw error; }).should.throw({ a: 10 });
(function(){ throw error; }).should.throw(Error, { a: 10 });
If you need to pass arguments and/or context to execute function use Function#bind(context, arg1, ...):
function isPositive(n) {
if(n <= 0) throw new Error('Given number is not positive')
}
isPositive.bind(null, 10).should.not.throw();
isPositive.bind(null, -10).should.throw();
If you need to check something in an asynchronous function, you must do it in 2 steps:
// first we need to check that function is called
var called = false;
collection.findOne({ _id: 10 }, function(err, res) {
called = true;
//second we test what you want
res.should.be....
});
called.should.be.true;
In case you are using something like Mocha, you should use an asynchronous test, and call done() in the proper place to make sure that your asynchronous function is called before the test finishes.
collection.findOne({ _id: 10 }, function(err, res) {
if(err) return done(err);
//second we test what you want
res.should.be....
done();
});
In general, if you need to check that something is executed, you are best using spies. A good example is sinon.
As it can often be difficult to ascertain exactly where failed assertions are coming from in your tests, an optional description parameter can be passed to several should matchers. The description will follow the failed assertion in the error:
(1).should.eql(0, 'some useful description')
AssertionError: some useful description
at Object.eql (/Users/swift/code/should.js/node_modules/should/lib/should.js:280:10)
...
The methods that support this optional description are: eql, equal, within, instanceof, above, below, match, length, ownProperty.
For example you can use should with the Mocha test framework by simply including it:
var should = require('should');
var mylib = require('mylib');
describe('mylib', function() {
it('should have a version with the format #.#.#', function() {
mylib.version.should.match(/^\d+\.\d+\.\d+$/);
});
});
To add own assertion you need to call should.Assertion.add function. It accept 3 arguments:
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 assertionobj it is actual value, you can assume it is your own this.obj if you need to define you ownexpected it is any value that expected to be matched this.objYou 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 .should.be.true defined:
Assertion.add('true', function() {
this.is.exactly(true);
}, 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 };
this.obj.should.be.exactly(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' };
this.obj.should.have.property('id').which.is.a.Number;
this.obj.should.have.property('path');
})
//then
> ({ id: '10' }).should.be.an.asset();
AssertionError: expected { id: '10' } to be asset
expected '10' to be a number
> ({ id: 10 }).should.be.an.asset();
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
See also CONTRIBUTING.
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.
MIT © 2010-2014 TJ Holowaychuk
4.6.5 / 2015-02-05
FAQs
test framework agnostic BDD-style assertions
The npm package should receives a total of 1,597,965 weekly downloads. As such, should popularity was classified as popular.
We found that should demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.