0
# Basic Assertions
1

2
Core assertion methods for testing fundamental properties like truthiness, equality, and basic value comparisons.
3

4
## Truth Testing
5

6
### ok()
7

8
Test that a value is truthy.
9

10
```javascript { .api }
11
/**
12
 * Assert that the value is truthy (not null, undefined, 0, false, '', or NaN)
13
 * @returns This assertion for chaining
14
 */
15
ok(): Assertion;
16
```
17

18
**Usage:**
19
```javascript
20
import should from 'should';
21

22
true.should.be.ok();
23
1.should.be.ok();
24
'hello'.should.be.ok();
25
[].should.be.ok();
26
{}.should.be.ok();
27

28
// These will fail
29
false.should.not.be.ok();
30
0.should.not.be.ok();
31
''.should.not.be.ok();
32
null.should.not.be.ok();
33
```
34

35
### true() / True()
36

37
Test that a value is exactly `true`.
38

39
```javascript { .api }
40
/**
41
 * Assert that the value is exactly true (not just truthy)
42
 * @param message - Optional error message
43
 * @returns This assertion for chaining
44
 */
45
true(message?: string): Assertion;
46
True(message?: string): Assertion;
47
```
48

49
**Usage:**
50
```javascript
51
true.should.be.true();
52
true.should.be.True();
53

54
// Custom message
55
const result = true;
56
result.should.be.true('Expected result to be true');
57
```
58

59
### false() / False()
60

61
Test that a value is exactly `false`.
62

63
```javascript { .api }
64
/**
65
 * Assert that the value is exactly false (not just falsy)
66
 * @param message - Optional error message  
67
 * @returns This assertion for chaining
68
 */
69
false(message?: string): Assertion;
70
False(message?: string): Assertion;
71
```
72

73
**Usage:**
74
```javascript
75
false.should.be.false();
76
false.should.be.False();
77

78
const isValid = false;
79
isValid.should.be.false('Validation should have failed');
80
```
81

82
## Equality Testing
83

84
### equal() / equals()
85

86
Test for strict equality using `===`.
87

88
```javascript { .api }
89
/**
90
 * Assert strict equality (===) between actual and expected values
91
 * @param expected - The expected value
92
 * @param description - Optional error message
93
 * @returns This assertion for chaining
94
 */
95
equal(expected: any, description?: string): Assertion;
96
equals(expected: any, description?: string): Assertion;
97
```
98

99
**Usage:**
100
```javascript
101
(42).should.equal(42);
102
'hello'.should.equal('hello');
103
true.should.equal(true);
104

105
const user = { name: 'john' };
106
const sameUser = user;
107
user.should.equal(sameUser); // Same reference
108

109
// With description
110
const count = 5;
111
count.should.equal(5, 'Count should be 5');
112
```
113

114
### exactly()
115

116
Alias for strict equality testing, emphasizing exact comparison.
117

118
```javascript { .api }
119
/**
120
 * Assert exact equality (===) - alias for equal()
121
 * @param expected - The expected value
122
 * @param description - Optional error message
123
 * @returns This assertion for chaining
124
 */
125
exactly(expected: any, description?: string): Assertion;
126
```
127

128
**Usage:**
129
```javascript
130
(100).should.be.exactly(100);
131
'test'.should.be.exactly('test');
132

133
const id = 12345;
134
id.should.be.exactly(12345, 'ID should match exactly');
135
```
136

137
### eql()
138

139
Test for deep equality, comparing object contents recursively.
140

141
```javascript { .api }
142
/**
143
 * Assert deep equality, comparing object contents recursively
144
 * @param expected - The expected value or object
145
 * @param description - Optional error message
146
 * @returns This assertion for chaining
147
 */
148
eql(expected: any, description?: string): Assertion;
149
```
150

151
**Usage:**
152
```javascript
153
// Objects with same content
154
({ name: 'john', age: 30 }).should.eql({ name: 'john', age: 30 });
155

156
// Arrays with same elements
157
[1, 2, 3].should.eql([1, 2, 3]);
158

159
// Nested objects
160
const user1 = { profile: { name: 'john' }, roles: ['admin'] };
161
const user2 = { profile: { name: 'john' }, roles: ['admin'] };
162
user1.should.eql(user2);
163

164
// With description
165
const actual = { status: 'ok' };
166
const expected = { status: 'ok' };
167
actual.should.eql(expected, 'Response should match expected format');
168
```
169

170
### oneOf() / equalOneOf()
171

172
Test if a value equals any one of several provided values.
173

174
```javascript { .api }
175
/**
176
 * Assert that the value equals one of the provided values
177
 * @param values - Array of acceptable values or individual arguments
178
 * @returns This assertion for chaining
179
 */
180
oneOf(...values: any[]): Assertion;
181
oneOf(values: any[]): Assertion;
182
equalOneOf(...values: any[]): Assertion;
183
equalOneOf(values: any[]): Assertion;
184
```
185

186
**Usage:**
187
```javascript
188
'red'.should.be.oneOf('red', 'green', 'blue');
189
'red'.should.be.oneOf(['red', 'green', 'blue']);
190

191
(42).should.be.equalOneOf(40, 41, 42, 43);
192

193
const status = 'pending';
194
status.should.be.oneOf(['pending', 'complete', 'failed']);
195
```
196

197
## Core Assertion Methods
198

199
### assert()
200

201
Manually assert a boolean expression.
202

203
```javascript { .api }
204
/**
205
 * Assert that the given expression is truthy
206
 * @param expression - Boolean expression to test
207
 * @returns This assertion for chaining
208
 */
209
assert(expression: boolean): Assertion;
210
```
211

212
**Usage:**
213
```javascript
214
const value = 42;
215
value.should.assert(value > 0);
216
value.should.assert(value % 2 === 0, 'Value should be even');
217

218
// Can be used with complex conditions
219
const user = { age: 25, active: true };
220
user.should.assert(user.age >= 18 && user.active);
221
```
222

223
### fail()
224

225
Force an assertion failure.
226

227
```javascript { .api }
228
/**
229
 * Force an assertion failure with optional message
230
 * @returns This assertion for chaining
231
 */
232
fail(): Assertion;
233
```
234

235
**Usage:**
236
```javascript
237
// Force failure in conditional logic
238
if (someCondition) {
239
  value.should.fail();
240
}
241

242
// Use in test control flow
243
try {
244
  riskyOperation();
245
  // Should not reach here
246
  true.should.fail();
247
} catch (error) {
248
  // Expected error path
249
  error.should.be.an.Error();
250
}
251
```
252

253
## Negation
254

255
All basic assertions can be negated using `.not`:
256

257
```javascript
258
false.should.not.be.ok();
259
(1).should.not.equal(2);
260
'hello'.should.not.be.exactly('world');
261
({ a: 1 }).should.not.eql({ b: 2 });
262
'yellow'.should.not.be.oneOf('red', 'green', 'blue');
263
```
264

265
## Chaining
266

267
Basic assertions return the Assertion object for chaining:
268

269
```javascript
270
const value = 42;
271
value.should.be.ok().and.be.a.Number().and.be.above(0);
272

273
const user = { name: 'john', active: true };
274
user.name.should.equal('john').and.be.a.String();
275
user.active.should.be.true().and.not.be.false();
276
```