{"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,"search_vec":"'13.2.3':31 'across':98 'activ':35 'adjust':97 'agnost':20 'aim':101 'altern':75 'api':79 'assert':3,11,111 'bdd':2,9,110 'bdd-style':8 'be.something':82 'behavior':50 'clear':105 'code':107 'current':28 'default':49 'definit':89 'design':15 'differenti':46 'enabl':61 'enumer':58 'environ':66 'error':24 'express':7 'extend':52 'extens':69 'framework':19 'framework-agnost':18 'frequent':39 'function':77 'function-styl':76 'getter':60 'help':23 'import':92 'javascript':14,108 'key':45 'librari':12,84 'maintain':33 'messag':25 'minor':42,96 'non':57 'non-enumer':56 'object.prototype':53,68 'offer':73 'patch':40 'pattern':93 'provid':22 'readabl':103 'releas':36 'schedul':37 'seen':95 'ship':85 'should.be.something':63 'should.js':1,4 'specif':91 'style':10,78 'syntax':64 'test':106,109 'though':90 'type':88 'typescript':87,113 'undesir':71 'updat':43 'valu':62,81 'version':30,99","created_at":"2026-04-21T04:49:49.689520+00:00","updated_at":"2026-04-21T04:49:49.689520+00:00","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","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.5.4","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/shouldjs/should.js","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/should","openapi_spec":null,"status_page":null,"smithery":null,"categories":["testing"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-20","install_tag":null}}