0
# Should.js
1

2
Should.js is an expressive, readable, framework-agnostic BDD-style assertion library for JavaScript testing. It provides intuitive assertion syntax that reads like natural language, making tests more readable and error messages more helpful.
3

4
## Package Information
5

6
- **Package Name**: should
7
- **Package Type**: npm
8
- **Language**: JavaScript (with TypeScript definitions)
9
- **Installation**: `npm install should --save-dev`
10

11
## Core Imports
12

13
### ES6 Modules
14
```javascript
15
import should from 'should';
16
```
17

18
### CommonJS  
19
```javascript
20
const should = require('should');
21
```
22

23
### As Function (no prototype extension)
24
```javascript  
25
const should = require('should/as-function');
26
```
27

28
### Browser (UMD)
29
```html
30
<script src="should.js"></script>
31
<!-- window.should is available globally -->
32
```
33

34
## Basic Usage
35

36
Should.js provides two main usage patterns for writing assertions:
37

38
### Prototype Extension (Default)
39
```javascript
40
import should from 'should';
41

42
const user = { name: 'john', age: 25 };
43

44
// Assertions using prototype extension
45
user.should.have.property('name', 'john');
46
user.should.have.property('age').which.is.a.Number();
47
user.age.should.be.above(18);
48
```
49

50
### Functional API
51
```javascript
52
const should = require('should/as-function');
53

54
const user = { name: 'john', age: 25 };
55

56
// Assertions using functional syntax
57
should(user).have.property('name', 'john');
58
should(user.age).be.above(18);
59
should(null).not.be.ok();
60
```
61

62
## Architecture
63

64
Should.js is built around a core `Assertion` object that wraps the value being tested. All assertion methods return the same Assertion object, enabling method chaining. The library includes:
65

66
- **Core Assertion Object**: Wraps values and provides assertion methods
67
- **Extension System**: Modular assertion plugins for different types
68
- **Chainable Syntax**: Fluent API with readable method names
69
- **Error Handling**: Custom assertion errors with helpful messages
70

71
## Capabilities
72

73
### Basic Assertions
74
Test fundamental properties like truthiness, equality, and types.
75

76
```javascript { .api }
77
/**
78
 * Core assertion methods for basic value testing
79
 */
80
interface BasicAssertions {
81
  ok(): Assertion;
82
  true(message?: string): Assertion;
83
  false(message?: string): Assertion;
84
  equal(expected: any, description?: string): Assertion;
85
  exactly(expected: any, description?: string): Assertion;
86
}
87
```
88

89
**[Basic Assertions](./basic-assertions.md)** - Truth testing, equality checks, and fundamental assertions.
90

91
### Type Assertions  
92
Verify the type and class of values using built-in JavaScript types.
93

94
```javascript { .api }
95
/**
96
 * Type checking and instanceof testing methods
97
 */
98
interface TypeAssertions {
99
  type(typeName: string, description?: string): Assertion;
100
  instanceof(constructor: Function, description?: string): Assertion;
101
  Number(): Assertion;
102
  String(): Assertion;
103
  Array(): Assertion;
104
  Object(): Assertion;
105
  Function(): Assertion;
106
}
107
```
108

109
**[Type Assertions](./type-assertions.md)** - Type checking, instanceof tests, and built-in type assertions.
110

111
### Object and Property Assertions
112
Test object properties, structure, and ownership.
113

114
```javascript { .api }
115
/**
116
 * Object and property testing methods
117
 */
118
interface PropertyAssertions {
119
  property(name: string, value?: any): Assertion;
120
  properties(...names: string[]): Assertion;
121
  ownProperty(name: string, description?: string): Assertion;
122
  keys(...keys: any[]): Assertion;
123
  empty(): Assertion;
124
  length(value: number, description?: string): Assertion;
125
}
126
```
127

128
**[Object and Property Assertions](./property-assertions.md)** - Object structure, property existence, and collection testing.
129

130
### Number and Range Assertions
131
Numeric comparisons, ranges, and special number values.
132

133
```javascript { .api }
134
/**
135
 * Numeric comparison and range testing methods
136
 */
137
interface NumberAssertions {
138
  above(value: number, description?: string): Assertion;
139
  below(value: number, description?: string): Assertion;
140
  within(start: number, finish: number, description?: string): Assertion;
141
  approximately(value: number, delta: number, description?: string): Assertion;
142
  NaN(): Assertion;
143
  Infinity(): Assertion;
144
}
145
```
146

147
**[Number and Range Assertions](./number-assertions.md)** - Numeric comparisons, range checks, and special values.
148

149
### String Assertions
150
String prefix/suffix testing and content validation.
151

152
```javascript { .api }
153
/**
154
 * String content testing methods
155
 */
156
interface StringAssertions {
157
  startWith(prefix: string, description?: string): Assertion;
158
  endWith(postfix: string, description?: string): Assertion;
159
}
160
```
161

162
**[String Assertions](./string-assertions.md)** - String content testing and pattern matching.
163

164
### Pattern Matching
165
Advanced pattern matching using regular expressions, functions, and object matchers.
166

167
```javascript { .api }
168
/**
169
 * Pattern matching methods for any value type
170
 */
171
interface PatternMatchingAssertions {
172
  match(pattern: RegExp | Function | object, description?: string): Assertion;
173
  matchEach(pattern: RegExp | string | Function, description?: string): Assertion;
174
  matchEvery(pattern: RegExp | string | Function, description?: string): Assertion;
175
  matchAny(pattern: RegExp | string | Function, description?: string): Assertion;
176
  matchSome(pattern: RegExp | string | Function, description?: string): Assertion;
177
}
178
```
179

180
**[Pattern Matching](./pattern-matching.md)** - Advanced pattern matching for strings, collections, and objects.
181

182
### Collection and Containment Assertions
183
Array and object containment, deep equality, and collection testing.
184

185
```javascript { .api }
186
/**
187
 * Collection containment and deep testing methods
188
 */
189
interface ContainmentAssertions {
190
  containEql(obj: any): Assertion;
191
  containDeep(obj: any): Assertion;
192
  containDeepOrdered(obj: any): Assertion;
193
  eql(obj: any, description?: string): Assertion;
194
  deepEqual(obj: any, description?: string): Assertion;
195
}
196
```
197

198
**[Collection and Containment Assertions](./containment-assertions.md)** - Array/object containment and deep equality testing.
199

200
### Error and Exception Assertions
201
Exception throwing, error handling, and error property testing.
202

203
```javascript { .api }
204
/**
205
 * Exception and error testing methods
206
 */
207
interface ErrorAssertions {
208
  throw(): Assertion;
209
  throw(message: RegExp | string | Function, properties?: object): Assertion;
210
  throwError(): Assertion;
211
  throwError(message: RegExp | string | Function, properties?: object): Assertion;
212
}
213
```
214

215
**[Error and Exception Assertions](./error-assertions.md)** - Exception testing and error property validation.
216

217
### Promise Assertions
218
Async testing, promise states, and async assertion chaining.
219

220
```javascript { .api }
221
/**
222
 * Promise state and async testing methods
223
 */
224
interface PromiseAssertions {
225
  Promise(): Assertion;
226
  fulfilled(): Promise<any>;
227
  rejected(): Promise<any>;
228
  fulfilledWith(obj: any): Promise<any>;
229
  rejectedWith(error: RegExp | string | Error, properties?: object): Promise<any>;
230
  finally: PromisedAssertion;
231
  eventually: PromisedAssertion;
232
}
233
```
234

235
**[Promise Assertions](./promise-assertions.md)** - Async testing, promise state checking, and async assertion chains.
236

237
### Configuration and Extension
238
Library configuration, custom assertions, and plugin system.
239

240
```javascript { .api }
241
/**
242
 * Configuration and extension methods
243
 */
244
interface ConfigurationMethods {
245
  extend(propertyName?: string, proto?: object): object;
246
  noConflict(descriptor?: object): Function;
247
  use(plugin: Function): Function;
248
  config: {
249
    checkProtoEql: boolean;
250
    plusZeroAndMinusZeroEqual: boolean;
251
  };
252
}
253
```
254

255
**[Configuration and Extension](./configuration.md)** - Library configuration, prototype extension, and custom assertion plugins.
256

257
## Static Methods
258

259
Should.js provides Node.js assert-compatible static methods that can be used without creating assertion chains:
260

261
```javascript { .api }
262
/**
263
 * Static assertion methods compatible with Node.js assert module
264
 */
265
interface StaticMethods {
266
  // Core assertion methods
267
  fail(actual: any, expected: any, message?: string, operator?: string): void;
268
  ok(value: any, message?: string): void;
269
  
270
  // Equality testing
271
  equal(actual: any, expected: any, message?: string): void;
272
  notEqual(actual: any, expected: any, message?: string): void;
273
  deepEqual(actual: any, expected: any, message?: string): void;
274
  notDeepEqual(actual: any, expected: any, message?: string): void;
275
  strictEqual(actual: any, expected: any, message?: string): void;
276
  notStrictEqual(actual: any, expected: any, message?: string): void;
277
  
278
  // Exception testing
279
  throws(block: Function, error?: Function | RegExp, message?: string): void;
280
  doesNotThrow(block: Function, message?: string): void;
281
  ifError(err: any): void;
282
  
283
  // Existence testing
284
  exist(obj: any, message?: string): void;
285
  exists(obj: any, message?: string): void;
286
}
287

288
// Negated existence testing
289
interface StaticNotMethods {
290
  exist(obj: any, message?: string): void;
291
  exists(obj: any, message?: string): void;
292
}
293
```
294

295
### Usage Examples
296

297
```javascript
298
import should from 'should';
299

300
// Basic assertions
301
should.ok(true);
302
should.fail(1, 2, 'Values should be equal', '==');
303

304
// Equality testing
305
should.equal(42, 42);
306
should.notEqual('hello', 'world');
307
should.deepEqual({ a: 1 }, { a: 1 });
308
should.strictEqual('5', '5');
309

310
// Exception testing
311
should.throws(() => { throw new Error('test'); });
312
should.doesNotThrow(() => { return 'safe'; });
313
should.ifError(null); // Passes if no error
314

315
// Existence testing
316
should.exist('hello');
317
should.exist([1, 2, 3]);
318
should.not.exist(null);
319
should.not.exist(undefined);
320
```
321

322
These methods are compatible with Node.js built-in assert methods and provide the same functionality as their instance method counterparts.