0
# Number and Range Assertions
1

2
Methods for numeric comparisons, range validation, and testing special number values.
3

4
## Comparison Assertions
5

6
### above() / greaterThan()
7

8
Test that a number is greater than a specified value.
9

10
```javascript { .api }
11
/**
12
 * Assert that the number is greater than the specified value
13
 * @param value - The value to compare against
14
 * @param description - Optional error message
15
 * @returns This assertion for chaining
16
 */
17
above(value: number, description?: string): Assertion;
18
greaterThan(value: number, description?: string): Assertion;
19
```
20

21
**Usage:**
22
```javascript
23
import should from 'should';
24

25
(10).should.be.above(5);
26
(3.14).should.be.greaterThan(3);
27
(-5).should.be.above(-10);
28

29
// With description
30
const score = 85;
31
score.should.be.above(80, 'Score should be above passing grade');
32

33
// Chaining with other assertions
34
const temperature = 25.5;
35
temperature.should.be.above(20).and.be.a.Number();
36
```
37

38
### below() / lessThan()
39

40
Test that a number is less than a specified value.
41

42
```javascript { .api }
43
/**
44
 * Assert that the number is less than the specified value
45
 * @param value - The value to compare against
46
 * @param description - Optional error message
47
 * @returns This assertion for chaining
48
 */
49
below(value: number, description?: string): Assertion;
50
lessThan(value: number, description?: string): Assertion;
51
```
52

53
**Usage:**
54
```javascript
55
(5).should.be.below(10);
56
(2.5).should.be.lessThan(3);
57
(-10).should.be.below(-5);
58

59
// With description
60
const age = 16;
61
age.should.be.below(18, 'Age should be below adult threshold');
62

63
// Chaining
64
const price = 99.99;
65
price.should.be.below(100).and.be.above(90);
66
```
67

68
### aboveOrEqual() / greaterThanOrEqual()
69

70
Test that a number is greater than or equal to a specified value.
71

72
```javascript { .api }
73
/**
74
 * Assert that the number is greater than or equal to the specified value
75
 * @param value - The value to compare against
76
 * @param description - Optional error message
77
 * @returns This assertion for chaining
78
 */
79
aboveOrEqual(value: number, description?: string): Assertion;
80
greaterThanOrEqual(value: number, description?: string): Assertion;
81
```
82

83
**Usage:**
84
```javascript
85
(10).should.be.aboveOrEqual(10); // Equal case
86
(15).should.be.aboveOrEqual(10); // Greater case
87
(0).should.be.greaterThanOrEqual(0);
88

89
// Minimum value validation
90
const minAge = 18;
91
const userAge = 18;
92
userAge.should.be.aboveOrEqual(minAge, 'User must meet minimum age');
93
```
94

95
### belowOrEqual() / lessThanOrEqual()  
96

97
Test that a number is less than or equal to a specified value.
98

99
```javascript { .api }
100
/**
101
 * Assert that the number is less than or equal to the specified value
102
 * @param value - The value to compare against
103
 * @param description - Optional error message
104
 * @returns This assertion for chaining
105
 */
106
belowOrEqual(value: number, description?: string): Assertion;
107
lessThanOrEqual(value: number, description?: string): Assertion;
108
```
109

110
**Usage:**
111
```javascript
112
(5).should.be.belowOrEqual(10); // Less case
113
(10).should.be.belowOrEqual(10); // Equal case
114
(-5).should.be.lessThanOrEqual(0);
115

116
// Maximum value validation
117
const maxScore = 100;
118
const userScore = 95;
119
userScore.should.be.belowOrEqual(maxScore, 'Score cannot exceed maximum');
120
```
121

122
## Range Testing
123

124
### within()
125

126
Test that a number falls within a specified range (inclusive).
127

128
```javascript { .api }
129
/**
130
 * Assert that the number is within the specified range (inclusive)
131
 * @param start - Range start value (inclusive)
132
 * @param finish - Range end value (inclusive)
133
 * @param description - Optional error message
134
 * @returns This assertion for chaining
135
 */
136
within(start: number, finish: number, description?: string): Assertion;
137
```
138

139
**Usage:**
140
```javascript
141
(5).should.be.within(1, 10);
142
(10).should.be.within(10, 20); // Boundaries are inclusive
143
(15.5).should.be.within(15, 16);
144

145
// Temperature range validation
146
const temperature = 22.5;
147
temperature.should.be.within(20, 25, 'Temperature should be in comfort range');
148

149
// Percentage validation
150
const progress = 75;
151
progress.should.be.within(0, 100).and.be.a.Number();
152

153
// Negative ranges
154
const value = -5;
155
value.should.be.within(-10, 0);
156
```
157

158
### approximately()
159

160
Test that a number is approximately equal to another number within a delta.
161

162
```javascript { .api }
163
/**
164
 * Assert that the number is approximately equal to expected within delta
165
 * @param expected - The expected value
166
 * @param delta - The allowed difference (tolerance)
167
 * @param description - Optional error message
168
 * @returns This assertion for chaining
169
 */
170
approximately(expected: number, delta: number, description?: string): Assertion;
171
```
172

173
**Usage:**
174
```javascript
175
(3.14159).should.be.approximately(3.14, 0.01);
176
(10.05).should.be.approximately(10, 0.1);
177
(0.1 + 0.2).should.be.approximately(0.3, 0.0001); // Floating point precision
178

179
// Scientific calculations
180
const measurement = 9.807; // Gravity
181
measurement.should.be.approximately(9.8, 0.01, 'Gravity measurement within tolerance');
182

183
// Large numbers
184
const population = 1000500;
185
population.should.be.approximately(1000000, 1000);
186
```
187

188
## Special Number Values
189

190
### NaN()
191

192
Test that a value is NaN (Not a Number).
193

194
```javascript { .api }
195
/**
196
 * Assert that the value is NaN
197
 * @returns This assertion for chaining
198
 */
199
NaN(): Assertion;
200
```
201

202
**Usage:**
203
```javascript
204
NaN.should.be.NaN();
205
(0/0).should.be.NaN();
206
Number('invalid').should.be.NaN();
207
parseInt('not-a-number').should.be.NaN();
208

209
// Math operations resulting in NaN
210
const result = Math.sqrt(-1);
211
result.should.be.NaN();
212

213
// NaN is still type 'number'
214
NaN.should.be.NaN().and.be.a.Number();
215
```
216

217
### Infinity()
218

219
Test that a value is positive or negative Infinity.
220

221
```javascript { .api }
222
/**
223
 * Assert that the value is positive or negative Infinity
224
 * @returns This assertion for chaining
225
 */
226
Infinity(): Assertion;
227
```
228

229
**Usage:**
230
```javascript
231
Infinity.should.be.Infinity();
232
(-Infinity).should.be.Infinity();
233
(1/0).should.be.Infinity();
234
(-1/0).should.be.Infinity();
235

236
// Division by zero
237
const positiveInf = Number.POSITIVE_INFINITY;
238
positiveInf.should.be.Infinity();
239

240
const negativeInf = Number.NEGATIVE_INFINITY;
241
negativeInf.should.be.Infinity();
242

243
// Infinity is still type 'number'
244
Infinity.should.be.Infinity().and.be.a.Number();
245
```
246

247
## Practical Examples
248

249
### Range Validation
250
```javascript
251
function validateAge(age) {
252
  age.should.be.a.Number();
253
  age.should.be.within(0, 150);
254
  age.should.not.be.NaN();
255
}
256

257
function validatePercentage(percent) {
258
  percent.should.be.a.Number()
259
    .and.be.within(0, 100)
260
    .and.not.be.Infinity()
261
    .and.not.be.NaN();
262
}
263
```
264

265
### Mathematical Calculations
266
```javascript
267
// Testing mathematical results
268
const result = Math.PI * 2;
269
result.should.be.approximately(6.283, 0.001);
270

271
// Testing ratios
272
const ratio = 22/7; // Approximation of PI
273
ratio.should.be.approximately(Math.PI, 0.01);
274

275
// Testing geometric calculations
276
const area = Math.PI * Math.pow(5, 2); // Circle area, radius 5
277
area.should.be.above(75).and.be.below(80);
278
```
279

280
### Financial Calculations
281
```javascript
282
// Currency precision
283
const price = 19.99;
284
const tax = price * 0.08;
285
const total = price + tax;
286

287
total.should.be.approximately(21.59, 0.01);
288
total.should.be.above(price);
289

290
// Percentage calculations
291
const discount = 0.15;
292
const discountAmount = price * discount;
293
const finalPrice = price - discountAmount;
294

295
finalPrice.should.be.below(price);
296
finalPrice.should.be.approximately(16.99, 0.01);
297
```
298

299
### Scientific Measurements
300
```javascript
301
// Physical constants
302
const speedOfLight = 299792458; // m/s
303
speedOfLight.should.be.approximately(3e8, 1e6);
304

305
// Measurement tolerance
306
const measurement = 9.81; // gravity
307
measurement.should.be.within(9.8, 9.82);
308
measurement.should.be.approximately(9.8, 0.1);
309
```
310

311
## Edge Cases and Error Handling
312

313
```javascript
314
// Testing for invalid calculations
315
const invalidResult = Math.sqrt(-1);
316
invalidResult.should.be.NaN();
317

318
// Division by zero
319
const infinite = 1/0;
320
infinite.should.be.Infinity();
321

322
// Very large numbers
323
const veryLarge = Number.MAX_VALUE;
324
veryLarge.should.be.above(1e300);
325
veryLarge.should.not.be.Infinity();
326

327
// Very small numbers
328
const verySmall = Number.MIN_VALUE;
329
verySmall.should.be.above(0);
330
verySmall.should.be.below(1);
331
```
332

333
## Chaining and Negation
334

335
All number assertions support chaining and negation:
336

337
```javascript
338
const value = 42;
339

340
// Chaining multiple conditions
341
value.should.be.a.Number()
342
  .and.be.above(40)
343
  .and.be.below(50)
344
  .and.not.be.NaN()
345
  .and.not.be.Infinity();
346

347
// Range with negation
348
value.should.not.be.within(50, 100);
349
value.should.not.be.approximately(50, 5);
350

351
// Special values negation
352
value.should.not.be.NaN();
353
value.should.not.be.Infinity();
354
```