{"id":15234,"library":"should","title":"should.js BDD Assertions","description":"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.","status":"active","version":"13.2.3","language":"javascript","source_language":"en","source_url":"https://github.com/shouldjs/should.js","tags":["javascript","test","bdd","assert","should","typescript"],"install":[{"cmd":"npm install should","lang":"bash","label":"npm"},{"cmd":"yarn add should","lang":"bash","label":"yarn"},{"cmd":"pnpm add should","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import should from 'should';","symbol":"should (global)","correct":"import 'should';\n// or for CommonJS:\nconst should = require('should');"},{"note":"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.","wrong":"import { should } from 'should/as-function';","symbol":"should (as function)","correct":"import should from 'should/as-function';\n// or for CommonJS:\nconst should = require('should/as-function');"},{"note":"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.","wrong":"import should from 'should';","symbol":"should (TypeScript)","correct":"import * as should from 'should';"}],"quickstart":{"code":"import 'should'; // Or `const should = require('should');` for CommonJS to get global assertions\n\n// Using the Object.prototype extension (default behavior)\nconst user = {\n    name: 'Alice',\n    age: 30,\n    isActive: true,\n    tags: ['developer', 'tester']\n};\n\nuser.should.have.property('name', 'Alice');\nuser.age.should.be.a.Number().and.be.exactly(30);\nuser.tags.should.have.lengthOf(2).and.containEql('developer');\nuser.isActive.should.be.true();\n\n// Using the function-style API (without Object.prototype modification)\nimport shouldAsFunction from 'should/as-function'; // Or `const shouldAsFunction = require('should/as-function');`\n\nshouldAsFunction(null).not.be.ok();\nshouldAsFunction(undefined).not.exist();\nshouldAsFunction(user.name).be.exactly('Alice');\n\n// Example for async assertions (assuming a promise-returning function)\nasync function fetchData(id: number): Promise<any> {\n    if (id === 1) return { id: 1, value: 'data' };\n    throw new Error('Not found');\n}\n\n(async () => {\n    try {\n        const result = await fetchData(1);\n        shouldAsFunction(result).be.an.Object().and.have.property('value', 'data');\n    } catch (err: any) {\n        shouldAsFunction(err).not.exist(); // This path should not be taken\n    }\n\n    try {\n        await fetchData(2);\n    } catch (err: any) {\n        shouldAsFunction(err).be.an.Error().and.have.property('message', 'Not found');\n    }\n})();","lang":"typescript","description":"Demonstrates both the default `Object.prototype` extended assertion style and the explicit function-style `should()` API for various data types and asynchronous operations."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=12.0.0"},{"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.","message":"The `.enumerable` and `.enumerables` assertions were removed in v13.0.0. These had been deprecated since v11.2.0 and are no longer available.","severity":"breaking","affected_versions":">=13.0.0"},{"fix":"Ensure no arguments are passed to zero-argument assertions. For assertions that require arguments (e.g., `.equal()`, `.property()`), use the correct assertion method.","message":"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.","severity":"breaking","affected_versions":">=13.1.0"},{"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()`.","message":"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.","severity":"gotcha","affected_versions":"*"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=13.1.2"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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`.","cause":"Attempting to use the `Object.prototype` extended `should` getter on `null` or `undefined` values, which do not inherit from `Object.prototype`.","error":"TypeError: Cannot read properties of null (reading 'should')"},{"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.","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.","error":"AssertionError: expected Map {} to be deeply equal to Map {}"},{"fix":"Remove any arguments passed to zero-argument assertions. For example, change `value.should.be.Number(someArg)` to `value.should.be.Number()`.","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.","error":"TypeError: (0).should.be.Number(1) is not a function"}],"ecosystem":"npm"}