0
# Numeric Matchers
1
2
Specialized matchers for numeric comparisons and floating-point precision testing. These matchers provide essential tools for mathematical assertions and boundary testing.
3
4
## Capabilities
5
6
### Greater Than Comparisons
7
8
#### toBeGreaterThan
9
10
Checks if a number is greater than the expected value.
11
12
```javascript { .api }
13
/**
14
* Checks if number is greater than expected value
15
* @param expected - Number to compare against
16
*/
17
ExpectationObject.toBeGreaterThan(expected: number): void;
18
```
19
20
**Usage Examples:**
21
22
```javascript
23
expect(10).toBeGreaterThan(5);
24
expect(3.5).toBeGreaterThan(3);
25
expect(-1).toBeGreaterThan(-5);
26
27
// Useful for testing ranges and boundaries
28
const score = calculateScore();
29
expect(score).toBeGreaterThan(0);
30
expect(score).toBeGreaterThan(passingScore);
31
```
32
33
#### toBeGreaterThanOrEqual
34
35
Checks if a number is greater than or equal to the expected value.
36
37
```javascript { .api }
38
/**
39
* Checks if number is greater than or equal to expected value
40
* @param expected - Number to compare against
41
*/
42
ExpectationObject.toBeGreaterThanOrEqual(expected: number): void;
43
```
44
45
**Usage Examples:**
46
47
```javascript
48
expect(10).toBeGreaterThanOrEqual(10);
49
expect(10).toBeGreaterThanOrEqual(5);
50
expect(0).toBeGreaterThanOrEqual(0);
51
52
// Testing minimum values
53
const userAge = getUserAge();
54
expect(userAge).toBeGreaterThanOrEqual(18); // legal age requirement
55
```
56
57
### Less Than Comparisons
58
59
#### toBeLessThan
60
61
Checks if a number is less than the expected value.
62
63
```javascript { .api }
64
/**
65
* Checks if number is less than expected value
66
* @param expected - Number to compare against
67
*/
68
ExpectationObject.toBeLessThan(expected: number): void;
69
```
70
71
**Usage Examples:**
72
73
```javascript
74
expect(5).toBeLessThan(10);
75
expect(-10).toBeLessThan(-5);
76
expect(2.99).toBeLessThan(3);
77
78
// Testing maximum limits
79
const responseTime = measureResponseTime();
80
expect(responseTime).toBeLessThan(1000); // should be under 1 second
81
```
82
83
#### toBeLessThanOrEqual
84
85
Checks if a number is less than or equal to the expected value.
86
87
```javascript { .api }
88
/**
89
* Checks if number is less than or equal to expected value
90
* @param expected - Number to compare against
91
*/
92
ExpectationObject.toBeLessThanOrEqual(expected: number): void;
93
```
94
95
**Usage Examples:**
96
97
```javascript
98
expect(10).toBeLessThanOrEqual(10);
99
expect(5).toBeLessThanOrEqual(10);
100
expect(-1).toBeLessThanOrEqual(0);
101
102
// Testing upper bounds
103
const batteryLevel = getBatteryLevel();
104
expect(batteryLevel).toBeLessThanOrEqual(100); // can't exceed 100%
105
```
106
107
### Floating Point Precision
108
109
#### toBeCloseTo
110
111
Checks if a floating-point number is close to the expected value within a specified precision.
112
113
```javascript { .api }
114
/**
115
* Checks if floating point number is close to expected value
116
* @param expected - Expected number value
117
* @param precision - Number of decimal places for precision (default: 2)
118
*/
119
ExpectationObject.toBeCloseTo(expected: number, precision?: number): void;
120
```
121
122
**Usage Examples:**
123
124
```javascript
125
// Default precision (2 decimal places)
126
expect(0.1 + 0.2).toBeCloseTo(0.3); // handles floating point imprecision
127
expect(Math.PI).toBeCloseTo(3.14);
128
129
// Custom precision
130
expect(Math.PI).toBeCloseTo(3.14159, 5); // 5 decimal places
131
expect(1/3).toBeCloseTo(0.333, 3); // 3 decimal places
132
133
// Useful for calculations that may have small rounding errors
134
const result = complexCalculation();
135
expect(result).toBeCloseTo(expectedValue, 4);
136
```
137
138
### Special Numeric Values
139
140
#### toBeNaN
141
142
Checks if a value is `NaN` (Not a Number).
143
144
```javascript { .api }
145
/**
146
* Checks if value is NaN (Not a Number)
147
*/
148
ExpectationObject.toBeNaN(): void;
149
```
150
151
**Usage Examples:**
152
153
```javascript
154
expect(NaN).toBeNaN();
155
expect(parseInt('not a number')).toBeNaN();
156
expect(Math.sqrt(-1)).toBeNaN();
157
expect(0 / 0).toBeNaN();
158
159
// Testing invalid calculations
160
const result = divide(10, 0);
161
if (shouldBeInvalid) {
162
expect(result).toBeNaN();
163
} else {
164
expect(result).not.toBeNaN();
165
}
166
```
167
168
## Advanced Usage Patterns
169
170
### Range Testing
171
172
```javascript
173
// Testing if a value falls within a range
174
const temperature = getTemperature();
175
expect(temperature).toBeGreaterThan(0);
176
expect(temperature).toBeLessThan(100);
177
178
// Or combined
179
expect(temperature).toBeGreaterThan(0);
180
expect(temperature).toBeLessThan(100);
181
```
182
183
### Boundary Testing
184
185
```javascript
186
// Testing edge cases around boundaries
187
const limit = 100;
188
expect(getValue()).toBeLessThanOrEqual(limit);
189
expect(getValue()).toBeGreaterThanOrEqual(0);
190
191
// Testing just inside boundaries
192
expect(99).toBeLessThan(limit);
193
expect(100).toBeLessThanOrEqual(limit);
194
```
195
196
### Precision in Financial Calculations
197
198
```javascript
199
// Handling currency calculations
200
const price1 = 19.99;
201
const price2 = 9.99;
202
const total = price1 + price2;
203
204
expect(total).toBeCloseTo(29.98, 2); // 2 decimal places for currency
205
206
// Tax calculations
207
const tax = calculateTax(100, 0.0825); // 8.25% tax
208
expect(tax).toBeCloseTo(8.25, 2);
209
```
210
211
## Negation Support
212
213
All numeric matchers support negation:
214
215
```javascript
216
expect(5).not.toBeGreaterThan(10);
217
expect(10).not.toBeLessThan(5);
218
expect(Math.PI).not.toBeCloseTo(3, 0);
219
expect(42).not.toBeNaN();
220
```
221
222
## Promise Support
223
224
All numeric matchers work with promises:
225
226
```javascript
227
await expect(Promise.resolve(42)).resolves.toBeGreaterThan(40);
228
await expect(Promise.resolve(3.14159)).resolves.toBeCloseTo(3.14, 2);
229
await expect(Promise.resolve(parseInt('invalid'))).resolves.toBeNaN();
230
```