0
# Assertions
1

2
TestCafe provides a comprehensive assertion system for verifying application state, element properties, and expected behaviors. All assertions automatically wait for conditions to be met within a timeout period.
3

4
## Capabilities
5

6
### Basic Assertions
7

8
Core assertion methods for equality, truthiness, and value comparison.
9

10
```javascript { .api }
11
/**
12
 * Creates an assertion for a value
13
 * @param actual - Value or selector to assert against
14
 * @returns Assertion object with available assertion methods
15
 */
16
expect(actual: any): Assertion;
17

18
interface Assertion {
19
    /**
20
     * Asserts deep equality between actual and expected values
21
     * @param expected - Expected value for comparison
22
     * @param message - Optional custom error message
23
     * @returns Promise that resolves if assertion passes
24
     */
25
    eql(expected: any, message?: string): Promise<void>;
26
    
27
    /**
28
     * Asserts values are not deeply equal
29
     * @param unexpected - Value that should not match actual
30
     * @param message - Optional custom error message
31
     * @returns Promise that resolves if assertion passes
32
     */
33
    notEql(unexpected: any, message?: string): Promise<void>;
34
    
35
    /**
36
     * Asserts value is truthy
37
     * @param message - Optional custom error message
38
     * @returns Promise that resolves if assertion passes
39
     */
40
    ok(message?: string): Promise<void>;
41
    
42
    /**
43
     * Asserts value is falsy
44
     * @param message - Optional custom error message
45
     * @returns Promise that resolves if assertion passes
46
     */
47
    notOk(message?: string): Promise<void>;
48
}
49
```
50

51
**Usage Examples:**
52

53
```javascript
54
import { Selector } from 'testcafe';
55

56
fixture('Basic Assertions')
57
    .page('https://example.com');
58

59
test('Equality assertions', async t => {
60
    const heading = Selector('h1');
61
    const button = Selector('#submit-button');
62
    
63
    // Check element text
64
    await t.expect(heading.innerText).eql('Welcome');
65
    await t.expect(heading.innerText).notEql('Goodbye');
66
    
67
    // Check element existence
68
    await t.expect(button.exists).ok();
69
    await t.expect(Selector('#nonexistent').exists).notOk();
70
    
71
    // Check element visibility
72
    await t.expect(button.visible).ok();
73
    
74
    // Custom error messages
75
    await t.expect(heading.innerText).eql('Welcome', 'Page heading should be "Welcome"');
76
});
77
```
78

79
### String Assertions
80

81
Assertions for string content including contains, match, and type checking.
82

83
```javascript { .api }
84
interface Assertion {
85
    /**
86
     * Asserts string contains expected substring
87
     * @param expected - Substring that should be present
88
     * @param message - Optional custom error message
89
     * @returns Promise that resolves if assertion passes
90
     */
91
    contains(expected: string, message?: string): Promise<void>;
92
    
93
    /**
94
     * Asserts string does not contain substring
95
     * @param unexpected - Substring that should not be present
96
     * @param message - Optional custom error message
97
     * @returns Promise that resolves if assertion passes
98
     */
99
    notContains(unexpected: string, message?: string): Promise<void>;
100
    
101
    /**
102
     * Asserts string matches regular expression
103
     * @param re - Regular expression pattern to match
104
     * @param message - Optional custom error message
105
     * @returns Promise that resolves if assertion passes
106
     */
107
    match(re: RegExp, message?: string): Promise<void>;
108
    
109
    /**
110
     * Asserts string does not match regular expression
111
     * @param re - Regular expression pattern that should not match
112
     * @param message - Optional custom error message
113
     * @returns Promise that resolves if assertion passes
114
     */
115
    notMatch(re: RegExp, message?: string): Promise<void>;
116
    
117
    /**
118
     * Asserts value is of expected type
119
     * @param typeName - Expected type name ('string', 'number', 'boolean', etc.)
120
     * @param message - Optional custom error message
121
     * @returns Promise that resolves if assertion passes
122
     */
123
    typeOf(typeName: string, message?: string): Promise<void>;
124
    
125
    /**
126
     * Asserts value is not of specified type
127
     * @param typeName - Type name that should not match
128
     * @param message - Optional custom error message
129
     * @returns Promise that resolves if assertion passes
130
     */
131
    notTypeOf(typeName: string, message?: string): Promise<void>;
132
}
133
```
134

135
**Usage Examples:**
136

137
```javascript
138
test('String assertions', async t => {
139
    const errorMessage = Selector('.error-message');
140
    const userEmail = Selector('#user-email');
141
    
142
    // Check text contains substring
143
    await t.expect(errorMessage.innerText).contains('Invalid');
144
    await t.expect(errorMessage.innerText).notContains('Success');
145
    
146
    // Check text matches pattern
147
    await t.expect(userEmail.value).match(/^[\w\.-]+@[\w\.-]+\.\w+$/);
148
    await t.expect(userEmail.value).notMatch(/invalid-pattern/);
149
    
150
    // Check value types
151
    const itemCount = await Selector('#item-count').innerText;
152
    await t.expect(parseInt(itemCount)).typeOf('number');
153
    await t.expect(itemCount).typeOf('string');
154
});
155
```
156

157
### Numeric Assertions
158

159
Assertions for numeric comparisons including greater than, less than, and within ranges.
160

161
```javascript { .api }
162
interface Assertion {
163
    /**
164
     * Asserts number is greater than expected value
165
     * @param expected - Value that actual should exceed
166
     * @param message - Optional custom error message
167
     * @returns Promise that resolves if assertion passes
168
     */
169
    gt(expected: number, message?: string): Promise<void>;
170
    
171
    /**
172
     * Asserts number is greater than or equal to expected value
173
     * @param expected - Minimum value (inclusive)
174
     * @param message - Optional custom error message
175
     * @returns Promise that resolves if assertion passes
176
     */
177
    gte(expected: number, message?: string): Promise<void>;
178
    
179
    /**
180
     * Asserts number is less than expected value
181
     * @param expected - Value that actual should be below
182
     * @param message - Optional custom error message
183
     * @returns Promise that resolves if assertion passes
184
     */
185
    lt(expected: number, message?: string): Promise<void>;
186
    
187
    /**
188
     * Asserts number is less than or equal to expected value
189
     * @param expected - Maximum value (inclusive)
190
     * @param message - Optional custom error message
191
     * @returns Promise that resolves if assertion passes
192
     */
193
    lte(expected: number, message?: string): Promise<void>;
194
    
195
    /**
196
     * Asserts number is within specified range
197
     * @param start - Range start value (inclusive)
198
     * @param finish - Range end value (inclusive)
199
     * @param message - Optional custom error message
200
     * @returns Promise that resolves if assertion passes
201
     */
202
    within(start: number, finish: number, message?: string): Promise<void>;
203
    
204
    /**
205
     * Asserts number is not within specified range
206
     * @param start - Range start value (inclusive)
207
     * @param finish - Range end value (inclusive)
208
     * @param message - Optional custom error message
209
     * @returns Promise that resolves if assertion passes
210
     */
211
    notWithin(start: number, finish: number, message?: string): Promise<void>;
212
}
213
```
214

215
**Usage Examples:**
216

217
```javascript
218
test('Numeric assertions', async t => {
219
    const price = Selector('.price');
220
    const quantity = Selector('#quantity');
221
    const progress = Selector('.progress-bar');
222
    
223
    // Compare numbers
224
    const priceValue = parseFloat(await price.innerText.replace('$', ''));
225
    await t.expect(priceValue).gt(0);
226
    await t.expect(priceValue).gte(9.99);
227
    await t.expect(priceValue).lt(1000);
228
    await t.expect(priceValue).lte(999.99);
229
    
230
    // Check ranges
231
    const quantityValue = parseInt(await quantity.value);
232
    await t.expect(quantityValue).within(1, 100);
233
    
234
    // Check progress percentage
235
    const progressWidth = (await progress.boundingClientRect).width;
236
    const containerWidth = (await progress.parent().boundingClientRect).width;
237
    const progressPercent = (progressWidth / containerWidth) * 100;
238
    await t.expect(progressPercent).within(0, 100);
239
});
240
```
241

242
### Element State Assertions
243

244
Specialized assertions for DOM element states and properties.
245

246
```javascript { .api }
247
interface Assertion {
248
    /**
249
     * Asserts element exists in DOM
250
     * @param message - Optional custom error message
251
     * @returns Promise that resolves if assertion passes
252
     */
253
    exists(message?: string): Promise<void>;
254
    
255
    /**
256
     * Asserts element is visible on page
257
     * @param message - Optional custom error message
258
     * @returns Promise that resolves if assertion passes
259
     */
260
    visible(message?: string): Promise<void>;
261
    
262
    /**
263
     * Asserts element is hidden or not visible
264
     * @param message - Optional custom error message
265
     * @returns Promise that resolves if assertion passes
266
     */
267
    hidden(message?: string): Promise<void>;
268
    
269
    /**
270
     * Asserts element has keyboard focus
271
     * @param message - Optional custom error message
272
     * @returns Promise that resolves if assertion passes
273
     */
274
    focused(message?: string): Promise<void>;
275
    
276
    /**
277
     * Asserts checkbox or radio button is checked
278
     * @param message - Optional custom error message
279
     * @returns Promise that resolves if assertion passes
280
     */
281
    checked(message?: string): Promise<void>;
282
    
283
    /**
284
     * Asserts checkbox or radio button is not checked
285
     * @param message - Optional custom error message
286
     * @returns Promise that resolves if assertion passes
287
     */
288
    notChecked(message?: string): Promise<void>;
289
    
290
    /**
291
     * Asserts option element is selected
292
     * @param message - Optional custom error message
293
     * @returns Promise that resolves if assertion passes
294
     */
295
    selected(message?: string): Promise<void>;
296
    
297
    /**
298
     * Asserts option element is not selected
299
     * @param message - Optional custom error message
300
     * @returns Promise that resolves if assertion passes
301
     */
302
    notSelected(message?: string): Promise<void>;
303
}
304
```
305

306
**Usage Examples:**
307

308
```javascript
309
test('Element state assertions', async t => {
310
    const modal = Selector('#modal');
311
    const checkbox = Selector('#terms-checkbox');
312
    const dropdown = Selector('#country-select');
313
    const textInput = Selector('#username');
314
    
315
    // Element visibility
316
    await t.expect(modal.exists).ok();
317
    await t.expect(modal.visible).ok();
318
    await t.expect(Selector('#hidden-element').hidden).ok();
319
    
320
    // Form element states
321
    await t.click(checkbox);
322
    await t.expect(checkbox.checked).ok();
323
    
324
    await t.click(textInput);
325
    await t.expect(textInput.focused).ok();
326
    
327
    // Select element options
328
    await t.click(dropdown);
329
    await t.click(dropdown.find('option[value="us"]'));
330
    await t.expect(dropdown.find('option[value="us"]').selected).ok();
331
    await t.expect(dropdown.find('option[value="uk"]').notSelected).ok();
332
});
333
```
334

335
### Collection Assertions
336

337
Assertions for arrays, collections, and element counts.
338

339
```javascript { .api }
340
interface Assertion {
341
    /**
342
     * Asserts collection contains specified item
343
     * @param expected - Item that should be present in collection
344
     * @param message - Optional custom error message
345
     * @returns Promise that resolves if assertion passes
346
     */
347
    contains(expected: any, message?: string): Promise<void>;
348
    
349
    /**
350
     * Asserts collection does not contain specified item
351
     * @param unexpected - Item that should not be present in collection
352
     * @param message - Optional custom error message
353
     * @returns Promise that resolves if assertion passes
354
     */
355
    notContains(unexpected: any, message?: string): Promise<void>;
356
}
357
```
358

359
**Usage Examples:**
360

361
```javascript
362
test('Collection assertions', async t => {
363
    const menuItems = Selector('.menu li');
364
    const tableRows = Selector('table tbody tr');
365
    const selectedOptions = Selector('#multi-select option:checked');
366
    
367
    // Element count assertions
368
    await t.expect(menuItems.count).eql(5);
369
    await t.expect(menuItems.count).gt(3);
370
    await t.expect(tableRows.count).gte(1);
371
    
372
    // Check if collections contain specific items
373
    const menuTexts = [];
374
    const menuCount = await menuItems.count;
375
    for (let i = 0; i < menuCount; i++) {
376
        menuTexts.push(await menuItems.nth(i).innerText);
377
    }
378
    
379
    await t.expect(menuTexts).contains('Home');
380
    await t.expect(menuTexts).notContains('Admin');
381
    
382
    // Multiple selection assertions
383
    await t.expect(selectedOptions.count).gte(1);
384
});
385
```
386

387
### Custom Assertions
388

389
Create custom assertion logic using client functions.
390

391
```javascript { .api }
392
/**
393
 * Use client functions for custom assertions
394
 * @param clientFn - Client function returning value to assert
395
 * @returns Assertion chain for the returned value
396
 */
397
expect(clientFn: ClientFunction): Assertion;
398
```
399

400
**Usage Examples:**
401

402
```javascript
403
import { ClientFunction } from 'testcafe';
404

405
test('Custom assertions', async t => {
406
    // Custom client function for assertion
407
    const getLocalStorageItem = ClientFunction((key) => {
408
        return localStorage.getItem(key);
409
    });
410
    
411
    const getCurrentUrl = ClientFunction(() => window.location.href);
412
    
413
    const getElementCount = ClientFunction((selector) => {
414
        return document.querySelectorAll(selector).length;
415
    });
416
    
417
    // Assert localStorage values
418
    await t.expect(getLocalStorageItem('userToken')).ok();
419
    await t.expect(getLocalStorageItem('theme')).eql('dark');
420
    
421
    // Assert current URL
422
    await t.expect(getCurrentUrl()).contains('/dashboard');
423
    
424
    // Assert dynamic element counts
425
    await t.expect(getElementCount('.notification')).gt(0);
426
    await t.expect(getElementCount('.error')).eql(0);
427
});
428
```
429

430
### Assertion Options
431

432
Control assertion behavior with timeout and other options.
433

434
```javascript { .api }
435
/**
436
 * Configure assertion timeout
437
 * @param timeout - Maximum wait time in milliseconds
438
 * @returns Modified assertion with custom timeout
439
 */
440
within(timeout: number): Assertion;
441
```
442

443
**Usage Examples:**
444

445
```javascript
446
test('Assertion timeouts', async t => {
447
    const slowElement = Selector('#slow-loading-element');
448
    const quickElement = Selector('#quick-element');
449
    
450
    // Wait longer for slow elements
451
    await t.expect(slowElement.exists).ok().within(10000); // 10 seconds
452
    
453
    // Quick timeout for elements that should appear fast
454
    await t.expect(quickElement.visible).ok().within(1000); // 1 second
455
    
456
    // Default timeout (configurable globally)
457
    await t.expect(Selector('#normal-element').exists).ok();
458
});
459
```