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.
By default (when you
require('should')) 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
It is also possible to use should.js without getter (it will not even try to extend Object.prototype), just
require('should/as-function'). Or if you already use version that auto add getter, you can call
(something).should getter and
should(something) in most situations are the same
Please check wiki page for upgrading instructions.
You can take look in FAQ.
var should = ;var user =name: 'tj'pets: 'tobi' 'loki' 'jane' 'bandit';usershouldhave;usershouldhavewith;// 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:have;// also you can test in that way for null'snotbe;;
Install it:$ npm install should --save-dev
Require it and use:var should = ;5shouldbeandbea;var should = ;beandbea;
Well, even when browsers by complaints of authors have 100% es5 support, it does not mean it has no 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$ npm run browser
The script is exported to
You can easy install it with npm or bower:
npm install should -D# orbower 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.
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:
.which. Use them for better readability; they do nothing at all.
Almost all assertions return the same object - so you can easy chain them. But some (eg:
.property) move the assertion object to a property value, so be careful.
Adding own assertions
Adding own assertion is pretty easy. You need to call
should.Assertion.add function. It accept 2 arguments:
- name of assertion method (string)
- assertion function (function)
What assertion function should do. It should check only positive case.
should will handle
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
actualit is actual value, you can assume it is your own this.obj if you need to define you own
expectedit 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?
should sources appeared 2 kinds of usage of this method.
First not preferred and used only for shortcuts to other assertions, e.g how
There you can see that assertion function do not define own
this.params and instead call within the same assertion
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.
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//then> id: '10' shouldbean;AssertionError: expected id: '10' to be assetexpected '10' to be a number> id: 10 shouldbean;AssertionError: expected id: 10 to be assetexpected id: 10 to have property path
should-sinon- adds additional assertions for sinon.js
should-immutable- extends different parts of should.js to make immutable.js first-class citizen in should.js
should-http- adds small assetions for assertion on http responses for node only
should-jq- asserions for jq (need maintainer)
karma-should- make more or less easy to work karma with should.js
should-spies- small and dirty simple zero dependcies spies
Actual list of contributors if you want to show it your friends.
To run the tests for should simply run:
$ npm test
See also CONTRIBUTING.
OMG IT EXTENDS OBJECT???!?!@
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. Just use
MIT. See LICENSE for details.