Version 1.0.0

@stackline/should

test framework agnostic BDD-style assertions

Independent maintenance of should 13.2.3. Original authors and licenses are retained.

Installation

# Preserve existing imports with an npm alias
npm install should@npm:@stackline/should@1.0.0
# Or use the scoped package name in your imports
npm install @stackline/should@1.0.0

Node.js: See compatibility notes. Read the compatibility and maintenance notes before migrating.

Usage and API

The reference below may retain upstream package names. Use the alias installation above to run those imports with this Stackline release.

@stackline/should

Independent maintenance fork of should@13.2.3. Original API, module format, runtime dependency ranges, and supported Node.js engines are preserved.

npm install @stackline/should
# Preserve existing imports with an npm alias:
npm install should@npm:@stackline/should@1.0.0

See UPSTREAM.md for the exact source and issue review, and CHANGELOG.md for focused maintenance changes. Development and release tooling runs on Node.js 24; that does not change the library runtime requirement.

Maintained by Stackline. Issues · npm.

Upstream documentation

should.js

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 require.

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 .noConflict function.

Results of (something).should getter and should(something) in most situations are the same

Upgrading instructions

Please check wiki page for upgrading instructions.

FAQ

You can take look in FAQ.

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.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);
});

To begin

Install it:
```
$ npm install should --save-dev
```

Require it and use:

var should = require('should');

(5).should.be.exactly(5).and.be.a.Number();

var should = require('should/as-function');

should(10).be.exactly(5).and.be.a.Number();

For TypeScript users:

```js
import * as should from 'should';

(0).should.be.Number();
```

In browser

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 window.should:

should(10).be.exactly(10)

You can easy install it with npm or bower:

npm install should -D
# or
bower install shouldjs/should.js

API docs

Actual api docs generated by jsdoc comments and available at http://shouldjs.github.io.

Usage examples

Please look on usage in examples

.not

.not negates the current assertion.

.any

.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.

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.

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 .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 assertion
actual it is actual value, you can assume it is your own this.obj if you need to define you own
expected it 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? 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);
});

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 };

    should(this.obj).be.exactly(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

Additional projects

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 assertions for assertion on http responses for node only
should-jq - assertions for jq (need maintainer)
karma-should - make more or less easy to work karma with should.js
should-spies - small and dirty simple zero dependencies spies

Contributions

Actual list of contributors if you want to show it your friends.

To run the tests for should simply run:

$ npm test

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 require('should/as-function') everywhere.

License

MIT. See LICENSE for details.

Security maintenance: should-format3.0.3 is vendored with its original MIT license and upstream source hash. Its function-name parser now performs a linear scan instead of overlapping regex quantifiers. All CJS, ESM, standalone and browser outputs use the same corrected source; the external should-format dependency was removed. Ordinary inputs are compared with the upstream helper and adversarial input runs in an isolated process with a timeout.

Upstream issues and maintenance review

Upstream review

Source: should@13.2.3, 38910f74a4e70f9f66b109241a41a2b3e7468fdf. Published upstream source files match the integrity-verified npm tarball. Generated distributions are rebuilt using current development tools; original library source, license and API contracts are retained.

Issue review (2026-09-29)

#185: rejectedWith custom errors: Retain and execute upstream promise/error assertion tests; do not introduce a new prototype matching rule.
#174: TypeScript extension definitions: Keep the original declaration file unchanged.
#170: matchEach index parameter: Preserve the existing API without adding an unreviewed callback argument.
#161: Browser harness: Verify the regenerated browser bundle in an isolated VM alongside the full existing runtime suite.

No upstream maintainer was contacted. These are scoped compatibility decisions rather than claims that every issue was solved.

Verification

Run npm ci --ignore-scripts, npm run build, npm test, npm run test:package, and npm audit --audit-level=low. CI and CodeQL must pass before the exact built tarball is published with provenance.

Release changes

Stackline changes

1.0.0

Scoped maintenance release preserving upstream library sources, exports, dependency ranges and supported runtime engines.
Replaced obsolete development bundlers/runners with current Rollup and Mocha, retaining upstream runtime tests and published module formats.
Added installed-tarball contracts, audited CI/CodeQL and artifact-only provenance/immutable releases.

Release files and references

Package bytes, npm provenance and the immutable GitHub release were verified for this version. Security checks describe the reviewed release; documented compatibility risks and upstream reports are not blanket claims of resolution.