should

library0.5.4jsnpmunverified

should.js is an expressive, BDD-style assertion library for JavaScript, designed to be framework-agnostic and provide helpful error messages. It is currently at version 13.2.3 and maintains an active release schedule with frequent patch and minor updates. A key differentiator is its default behavior of extending `Object.prototype` with a non-enumerable `should` getter, enabling `(value).should.be.something` syntax. For environments where `Object.prototype` extension is undesirable, it offers an alternative function-style API, `should(value).be.something`. The library ships with TypeScript type definitions, though specific import patterns have seen minor adjustments across versions. It aims for readability and clear test code.

testing

npm install should

github ↗package ↗

INSTALL

IMPORT

SIG · SHOULD

should

testingjavascriptv0.5.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

should (global)

✓ import 'should'; // or for CommonJS: const should = require('should');

✗ import should from 'should';

Imports the library primarily for its side effect of extending `Object.prototype` with a `should` getter, making assertions available on any object. For CommonJS, `require('should')` also returns the function-style API.

should (as function)

✓ import should from 'should/as-function'; // or for CommonJS: const should = require('should/as-function');

✗ import { should } from 'should/as-function';

Imports the library as a standalone function, avoiding `Object.prototype` modification. This is preferred for cleaner environments, when testing `null`/`undefined`, or when the global getter is undesired.

should (TypeScript)

✓ import * as should from 'should';

✗ import should from 'should';

Standard TypeScript import for versions >=13.1.2 to access both the global assertions (via side effect) and the function-style `should()` API. Versions 13.1.0 briefly supported `import should from 'should'` for default exports, but this was reverted.

Demonstrates both the default `Object.prototype` extended assertion style and the explicit function-style `should()` API for various data types and asynchronous operations.

import 'should'; // Or `const should = require('should');` for CommonJS to get global assertions // Using the Object.prototype extension (default behavior) const user = { name: 'Alice', age: 30, isActive: true, tags: ['developer', 'tester'] }; user.should.have.property('name', 'Alice'); user.age.should.be.a.Number().and.be.exactly(30); user.tags.should.have.lengthOf(2).and.containEql('developer'); user.isActive.should.be.true(); // Using the function-style API (without Object.prototype modification) import shouldAsFunction from 'should/as-function'; // Or `const shouldAsFunction = require('should/as-function');` shouldAsFunction(null).not.be.ok(); shouldAsFunction(undefined).not.exist(); shouldAsFunction(user.name).be.exactly('Alice'); // Example for async assertions (assuming a promise-returning function) async function fetchData(id: number): Promise<any> { if (id === 1) return { id: 1, value: 'data' }; throw new Error('Not found'); } (async () => { try { const result = await fetchData(1); shouldAsFunction(result).be.an.Object().and.have.property('value', 'data'); } catch (err: any) { shouldAsFunction(err).not.exist(); // This path should not be taken } try { await fetchData(2); } catch (err: any) { shouldAsFunction(err).be.an.Error().and.have.property('message', 'Not found'); } })();

Debug

Known issues

breakingMap and Set equality checks changed behavior significantly in v12.0.0. Previously, `Map` and `Set` equality checked value equality. From v12.0.0 onwards, checks align with standard key checks, meaning objects used as keys must be strictly equal (`===`) for maps to be considered equal.

fix

Review existing tests involving `Map` or `Set` comparisons where object keys were used. Ensure keys are referentially identical if strict key equality is desired, or adjust tests to compare elements individually.

affects: >=12.0.0

breakingThe `.enumerable` and `.enumerables` assertions were removed in v13.0.0. These had been deprecated since v11.2.0 and are no longer available.

fix

Remove any usage of `.enumerable` or `.enumerables` from your assertion chains. Use standard JavaScript iteration or other assertion methods to check for enumerability if necessary.

affects: >=13.0.0

breakingAs of v13.1.0, all zero-argument assertions (e.g., `.ok()`, `.true()`, `.be.a.Number()`) will now throw a `TypeError` if any arguments are passed to them. This enforces correct usage of these specific assertions.

fix

Ensure no arguments are passed to zero-argument assertions. For assertions that require arguments (e.g., `.equal()`, `.property()`), use the correct assertion method.

affects: >=13.1.0

gotchaBy default, `should.js` extends `Object.prototype` with a non-enumerable `should` getter. While convenient, this can be problematic in some environments, for example, when working with `Object.create(null)` objects which do not inherit from `Object.prototype`, potentially causing unexpected behavior or conflicts.

fix

For cleaner code or when `Object.prototype` extension is undesirable, use `require('should/as-function')` or `import should from 'should/as-function'` to use the function-style API, e.g., `should(value).be.something()`.

affects: *

gotchaTypeScript users should generally import `should` using `import * as should from 'should';`. While `import should from 'should';` was temporarily fixed in v13.1.0 for default exports, this was reverted in v13.1.2, making the `* as` import the more robust and recommended approach for consistent behavior.

fix

Update TypeScript import statements to `import * as should from 'should';` to ensure compatibility and access to all assertion methods, especially if you encountered issues after upgrading from v13.1.0.

affects: >=13.1.2

Errors

Common errors & fixes

TypeError: Cannot read properties of null (reading 'should')

Attempting to use the `Object.prototype` extended `should` getter on `null` or `undefined` values, which do not inherit from `Object.prototype`.

fix

Use the function-style assertion API: `should(null).not.be.ok();` or `should(undefined).not.exist();`. Alternatively, ensure the value is not `null` or `undefined` before calling `.should`.

AssertionError: expected Map {} to be deeply equal to Map {}

This error, particularly when comparing two `Map` or `Set` objects where keys are different object instances but have equivalent content, is likely due to the breaking change in `should.js` v12.0.0 or later. This version changed Map/Set equality to use strict (`===`) key comparison.

fix

If object key identity is not strictly necessary, restructure your tests to compare the `Map` or `Set` contents differently, perhaps by iterating and comparing values. If strict identity is intended, ensure the same key object instance is used.

TypeError: (0).should.be.Number(1) is not a function

Passing an argument to a zero-argument assertion (e.g., `.be.Number()`, `.ok()`) which expects no arguments. This behavior started throwing a `TypeError` in v13.1.0.

fix

Remove any arguments passed to zero-argument assertions. For example, change `value.should.be.Number(someArg)` to `value.should.be.Number()`.

Upgrade

Version history

0.5.4latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/shouldjs/should.js ↗

packagehttps://www.npmjs.com/package/should ↗