should.js BDD Assertions

Common errors

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

  cause 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 {}

  cause 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

  cause 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()`.

Warnings

• breaking Map 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.
• breaking The `.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.
• breaking As 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.
• gotcha By 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()`.
• gotcha TypeScript 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.

Install

• npm install should npm
• yarn add should yarn
• pnpm add should pnpm

Imports

• should (global)
  wrong:

  import should from 'should';

  correct:

  import 'should';
  // or for CommonJS:
  const should = require('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)
  wrong:

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

  correct:

  import should from 'should/as-function';
  // or for CommonJS:
  const should = require('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)
  wrong:

  import should from 'should';

  correct:

  import * as 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.

Quickstart

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');
    }
})();