0
# Assertions & Expectations
1

2
Comprehensive assertion library supporting both assert-style and expect-style validation patterns for test verification.
3

4
## Capabilities
5

6
### Assert-Style Assertions
7

8
Traditional assertion methods that throw errors on failure, suitable for immediate validation.
9

10
#### Element Existence Assertions
11

12
```javascript { .api }
13
/**
14
 * Assert element exists in DOM
15
 * @param selector - Element selector
16
 * @param message - Optional custom message
17
 * @returns Promise resolving when assertion passes
18
 */
19
browser.assert.elementPresent(selector: string, message?: string);
20

21
/**
22
 * Assert element doesn't exist in DOM
23
 * @param selector - Element selector
24
 * @param message - Optional custom message
25
 * @returns Promise resolving when assertion passes
26
 */
27
browser.assert.elementNotPresent(selector: string, message?: string);
28
```
29

30
#### Element Visibility Assertions
31

32
```javascript { .api }
33
/**
34
 * Assert element is visible
35
 * @param selector - Element selector
36
 * @param message - Optional custom message
37
 * @returns Promise resolving when assertion passes
38
 */
39
browser.assert.visible(selector: string, message?: string);
40

41
/**
42
 * Assert element is hidden
43
 * @param selector - Element selector
44
 * @param message - Optional custom message
45
 * @returns Promise resolving when assertion passes
46
 */
47
browser.assert.hidden(selector: string, message?: string);
48
```
49

50
#### Element State Assertions
51

52
```javascript { .api }
53
/**
54
 * Assert element is enabled for interaction
55
 * @param selector - Element selector
56
 * @param message - Optional custom message
57
 * @returns Promise resolving when assertion passes
58
 */
59
browser.assert.enabled(selector: string, message?: string);
60

61
/**
62
 * Assert element is selected (checkboxes/radio buttons)
63
 * @param selector - Element selector
64
 * @param message - Optional custom message
65
 * @returns Promise resolving when assertion passes
66
 */
67
browser.assert.selected(selector: string, message?: string);
68
```
69

70
#### Element Attribute & Class Assertions
71

72
```javascript { .api }
73
/**
74
 * Assert element has specific CSS class
75
 * @param selector - Element selector
76
 * @param className - CSS class name
77
 * @param message - Optional custom message
78
 * @returns Promise resolving when assertion passes
79
 */
80
browser.assert.hasClass(selector: string, className: string, message?: string);
81

82
/**
83
 * Assert element has specific attribute
84
 * @param selector - Element selector
85
 * @param attribute - Attribute name
86
 * @param message - Optional custom message
87
 * @returns Promise resolving when assertion passes
88
 */
89
browser.assert.hasAttribute(selector: string, attribute: string, message?: string);
90

91
/**
92
 * Assert element has child elements
93
 * @param selector - Element selector
94
 * @param message - Optional custom message
95
 * @returns Promise resolving when assertion passes
96
 */
97
browser.assert.hasDescendants(selector: string, message?: string);
98
```
99

100
#### Text Content Assertions
101

102
```javascript { .api }
103
/**
104
 * Assert element text contains specified string
105
 * @param selector - Element selector
106
 * @param text - Expected text content
107
 * @param message - Optional custom message
108
 * @returns Promise resolving when assertion passes
109
 */
110
browser.assert.textContains(selector: string, text: string, message?: string);
111

112
/**
113
 * Assert element text equals specified string
114
 * @param selector - Element selector
115
 * @param text - Expected text content
116
 * @param message - Optional custom message
117
 * @returns Promise resolving when assertion passes
118
 */
119
browser.assert.textEquals(selector: string, text: string, message?: string);
120

121
/**
122
 * Assert element text matches regular expression
123
 * @param selector - Element selector
124
 * @param regex - Regular expression pattern
125
 * @param message - Optional custom message
126
 * @returns Promise resolving when assertion passes
127
 */
128
browser.assert.textMatches(selector: string, regex: RegExp, message?: string);
129

130
/**
131
 * Assert element contains specified text (deprecated)
132
 * @param selector - Element selector
133
 * @param text - Expected text content
134
 * @param message - Optional custom message
135
 * @returns Promise resolving when assertion passes
136
 */
137
browser.assert.containsText(selector: string, text: string, message?: string);
138
```
139

140
#### Attribute & Property Assertions
141

142
```javascript { .api }
143
/**
144
 * Assert element attribute contains specified value
145
 * @param selector - Element selector
146
 * @param attr - Attribute name
147
 * @param text - Expected attribute content
148
 * @param message - Optional custom message
149
 * @returns Promise resolving when assertion passes
150
 */
151
browser.assert.attributeContains(selector: string, attr: string, text: string, message?: string);
152

153
/**
154
 * Assert element attribute equals specified value
155
 * @param selector - Element selector
156
 * @param attr - Attribute name
157
 * @param value - Expected attribute value
158
 * @param message - Optional custom message
159
 * @returns Promise resolving when assertion passes
160
 */
161
browser.assert.attributeEquals(selector: string, attr: string, value: string, message?: string);
162

163
/**
164
 * Assert element attribute matches regular expression
165
 * @param selector - Element selector
166
 * @param attr - Attribute name
167
 * @param regex - Regular expression pattern
168
 * @param message - Optional custom message
169
 * @returns Promise resolving when assertion passes
170
 */
171
browser.assert.attributeMatches(selector: string, attr: string, regex: RegExp, message?: string);
172

173
/**
174
 * Assert element CSS property has specified value
175
 * @param selector - Element selector
176
 * @param property - CSS property name
177
 * @param value - Expected property value
178
 * @param message - Optional custom message
179
 * @returns Promise resolving when assertion passes
180
 */
181
browser.assert.cssProperty(selector: string, property: string, value: string, message?: string);
182

183
/**
184
 * Assert DOM property contains specified value
185
 * @param selector - Element selector
186
 * @param prop - Property name
187
 * @param value - Expected property content
188
 * @param message - Optional custom message
189
 * @returns Promise resolving when assertion passes
190
 */
191
browser.assert.domPropertyContains(selector: string, prop: string, value: any, message?: string);
192

193
/**
194
 * Assert DOM property equals specified value
195
 * @param selector - Element selector
196
 * @param prop - Property name
197
 * @param value - Expected property value
198
 * @param message - Optional custom message
199
 * @returns Promise resolving when assertion passes
200
 */
201
browser.assert.domPropertyEquals(selector: string, prop: string, value: any, message?: string);
202

203
/**
204
 * Assert DOM property matches regular expression
205
 * @param selector - Element selector
206
 * @param prop - Property name
207
 * @param regex - Regular expression pattern
208
 * @param message - Optional custom message
209
 * @returns Promise resolving when assertion passes
210
 */
211
browser.assert.domPropertyMatches(selector: string, prop: string, regex: RegExp, message?: string);
212
```
213

214
#### Form Value Assertions
215

216
```javascript { .api }
217
/**
218
 * Assert form element value (deprecated)
219
 * @param selector - Element selector
220
 * @param expected - Expected value
221
 * @param message - Optional custom message
222
 * @returns Promise resolving when assertion passes
223
 */
224
browser.assert.value(selector: string, expected: string, message?: string);
225

226
/**
227
 * Assert element value contains specified text
228
 * @param selector - Element selector
229
 * @param text - Expected value content
230
 * @param message - Optional custom message
231
 * @returns Promise resolving when assertion passes
232
 */
233
browser.assert.valueContains(selector: string, text: string, message?: string);
234

235
/**
236
 * Assert element value equals expected value
237
 * @param selector - Element selector
238
 * @param expected - Expected value
239
 * @param message - Optional custom message
240
 * @returns Promise resolving when assertion passes
241
 */
242
browser.assert.valueEquals(selector: string, expected: string, message?: string);
243
```
244

245
#### Page-Level Assertions
246

247
```javascript { .api }
248
/**
249
 * Assert page title (deprecated)
250
 * @param expected - Expected title
251
 * @param message - Optional custom message
252
 * @returns Promise resolving when assertion passes
253
 */
254
browser.assert.title(expected: string, message?: string);
255

256
/**
257
 * Assert page title contains specified text
258
 * @param expected - Expected title content
259
 * @param message - Optional custom message
260
 * @returns Promise resolving when assertion passes
261
 */
262
browser.assert.titleContains(expected: string, message?: string);
263

264
/**
265
 * Assert page title equals specified text
266
 * @param expected - Expected title
267
 * @param message - Optional custom message
268
 * @returns Promise resolving when assertion passes
269
 */
270
browser.assert.titleEquals(expected: string, message?: string);
271

272
/**
273
 * Assert page title matches regular expression
274
 * @param regex - Regular expression pattern
275
 * @param message - Optional custom message
276
 * @returns Promise resolving when assertion passes
277
 */
278
browser.assert.titleMatches(regex: RegExp, message?: string);
279

280
/**
281
 * Assert URL contains specified text
282
 * @param expected - Expected URL content
283
 * @param message - Optional custom message
284
 * @returns Promise resolving when assertion passes
285
 */
286
browser.assert.urlContains(expected: string, message?: string);
287

288
/**
289
 * Assert URL equals specified text
290
 * @param expected - Expected URL
291
 * @param message - Optional custom message
292
 * @returns Promise resolving when assertion passes
293
 */
294
browser.assert.urlEquals(expected: string, message?: string);
295

296
/**
297
 * Assert URL matches regular expression
298
 * @param regex - Regular expression pattern
299
 * @param message - Optional custom message
300
 * @returns Promise resolving when assertion passes
301
 */
302
browser.assert.urlMatches(regex: RegExp, message?: string);
303
```
304

305
#### Element Count Assertions
306

307
```javascript { .api }
308
/**
309
 * Assert number of elements matching selector
310
 * @param selector - Element selector
311
 * @param count - Expected element count
312
 * @param message - Optional custom message
313
 * @returns Promise resolving when assertion passes
314
 */
315
browser.assert.elementsCount(selector: string, count: number, message?: string);
316
```
317

318
**Usage Examples:**
319

320
```javascript
321
// Element existence and visibility
322
browser.assert.elementPresent("#login-form");
323
browser.assert.visible("#submit-button");
324
browser.assert.hidden("#error-message");
325

326
// Text content
327
browser.assert.textContains("#status", "Success");
328
browser.assert.textEquals("#title", "Welcome");
329

330
// Attributes and properties
331
browser.assert.hasClass("#alert", "error");
332
browser.assert.attributeEquals("input", "type", "email");
333
browser.assert.valueContains("#search", "nightwatch");
334

335
// Page-level assertions
336
browser.assert.titleContains("Dashboard");
337
browser.assert.urlContains("/dashboard");
338

339
// Element count
340
browser.assert.elementsCount(".menu-item", 5);
341
```
342

343
### Expect-Style Assertions
344

345
Fluent, chainable expectation API providing readable test assertions.
346

347
#### Expect Factory Functions
348

349
```javascript { .api }
350
/**
351
 * Create element expectation for assertions
352
 * @param selector - Element selector
353
 * @returns Element expectation object
354
 */
355
browser.expect.element(selector: string): ElementExpectation;
356

357
/**
358
 * Create elements collection expectation
359
 * @param selector - Elements selector
360
 * @returns Elements expectation object
361
 */
362
browser.expect.elements(selector: string): ElementsExpectation;
363

364
/**
365
 * Create page object section expectation
366
 * @param selector - Section selector
367
 * @returns Section expectation object
368
 */
369
browser.expect.section(selector: string): SectionExpectation;
370

371
/**
372
 * Create component expectation
373
 * @param selector - Component selector
374
 * @returns Component expectation object
375
 */
376
browser.expect.component(selector: string): ComponentExpectation;
377

378
/**
379
 * Create cookie expectation
380
 * @param name - Cookie name
381
 * @returns Cookie expectation object
382
 */
383
browser.expect.cookie(name: string): CookieExpectation;
384

385
/**
386
 * Create page title expectation
387
 * @returns Title expectation object
388
 */
389
browser.expect.title(): TitleExpectation;
390

391
/**
392
 * Create URL expectation
393
 * @returns URL expectation object
394
 */
395
browser.expect.url(): UrlExpectation;
396
```
397

398
#### Element Property Expectations
399

400
```javascript { .api }
401
/**
402
 * Element expectation with chainable properties and methods
403
 */
404
interface ElementExpectation {
405
  // Element type/tag expectations
406
  a(type: string): ElementExpectation;
407
  an(type: string): ElementExpectation;
408
  
409
  // Attribute expectations
410
  attribute(name: string): AttributeExpectation;
411
  
412
  // CSS property expectations
413
  css(property: string): CssExpectation;
414
  
415
  // DOM property expectations
416
  property(name: string): PropertyExpectation;
417
  
418
  // Content expectations
419
  text: TextExpectation;
420
  value: ValueExpectation;
421
  
422
  // State expectations
423
  active: StateExpectation;
424
  enabled: StateExpectation;
425
  present: StateExpectation;
426
  selected: StateExpectation;
427
  visible: StateExpectation;
428
}
429
```
430

431
#### Language Chain Properties
432

433
```javascript { .api }
434
/**
435
 * Fluent language chains for readable assertions
436
 */
437
interface LanguageChains {
438
  to: ExpectationChain;
439
  be: ExpectationChain;
440
  been: ExpectationChain;
441
  is: ExpectationChain;
442
  that: ExpectationChain;
443
  which: ExpectationChain;
444
  and: ExpectationChain;
445
  has: ExpectationChain;
446
  have: ExpectationChain;
447
  with: ExpectationChain;
448
  at: ExpectationChain;
449
  does: ExpectationChain;
450
  of: ExpectationChain;
451
  same: ExpectationChain;
452
  
453
  // Negation chain
454
  not: ExpectationChain;
455
  
456
  // Deep equality flag
457
  deep: ExpectationChain;
458
}
459
```
460

461
#### Assertion Chain Methods
462

463
```javascript { .api }
464
/**
465
 * Equality assertion methods
466
 * @param value - Expected value
467
 * @returns Promise resolving when assertion passes
468
 */
469
equal(value: any): Promise<void>;
470
equals(value: any): Promise<void>;
471
eq(value: any): Promise<void>;
472

473
/**
474
 * Contains assertion methods
475
 * @param value - Expected contained value
476
 * @returns Promise resolving when assertion passes
477
 */
478
include(value: any): Promise<void>;
479
includes(value: any): Promise<void>;
480
contain(value: any): Promise<void>;
481
contains(value: any): Promise<void>;
482

483
/**
484
 * Regex match assertion methods
485
 * @param regex - Regular expression pattern
486
 * @returns Promise resolving when assertion passes
487
 */
488
match(regex: RegExp): Promise<void>;
489
matches(regex: RegExp): Promise<void>;
490

491
/**
492
 * String start assertion methods
493
 * @param value - Expected start value
494
 * @returns Promise resolving when assertion passes
495
 */
496
startWith(value: string): Promise<void>;
497
startsWith(value: string): Promise<void>;
498

499
/**
500
 * String end assertion methods
501
 * @param value - Expected end value
502
 * @returns Promise resolving when assertion passes
503
 */
504
endWith(value: string): Promise<void>;
505
endsWith(value: string): Promise<void>;
506

507
/**
508
 * Timeout assertion methods
509
 * @param ms - Timeout in milliseconds
510
 * @returns Promise resolving when assertion passes within timeout
511
 */
512
before(ms: number): Promise<void>;
513
after(ms: number): Promise<void>;
514
```
515

516
**Usage Examples:**
517

518
```javascript
519
// Element state expectations
520
browser.expect.element("#submit-button").to.be.visible;
521
browser.expect.element("#loading").to.not.be.present;
522
browser.expect.element("#checkbox").to.be.selected;
523

524
// Text content expectations
525
browser.expect.element("#status").text.to.contain("Success");
526
browser.expect.element("#title").text.to.equal("Welcome Dashboard");
527
browser.expect.element("#message").text.to.match(/^Success:/);
528

529
// Attribute expectations
530
browser.expect.element("input").to.have.attribute("type").equals("email");
531
browser.expect.element("#link").to.have.attribute("href").contains("example.com");
532

533
// CSS property expectations
534
browser.expect.element("#header").to.have.css("background-color").equals("rgb(255, 0, 0)");
535
browser.expect.element(".hidden").to.have.css("display").equals("none");
536

537
// Value expectations
538
browser.expect.element("#search").to.have.value.that.contains("nightwatch");
539
browser.expect.element("#email").to.have.value.that.matches(/^[^@]+@[^@]+$/);
540

541
// Page-level expectations
542
browser.expect.title().to.contain("Dashboard");
543
browser.expect.url().to.match(/\/dashboard$/);
544

545
// Cookie expectations
546
browser.expect.cookie("session_id").to.contain("abc");
547

548
// Negation expectations
549
browser.expect.element("#error").to.not.be.visible;
550
browser.expect.element("#disabled-button").to.not.be.enabled;
551

552
// Chained expectations
553
browser.expect.element("#form")
554
  .to.be.present.and
555
  .to.be.visible.and
556
  .to.have.attribute("method").equals("POST");
557
```
558

559
### Promise-Based Assertions
560

561
Handle dynamic content and asynchronous operations.
562

563
```javascript { .api }
564
/**
565
 * Assert promised value meets expectation
566
 * @param promise - Promise resolving to value
567
 * @param expected - Expected value
568
 * @param message - Optional custom message
569
 * @returns Promise resolving when assertion passes
570
 */
571
browser.assert.promisedValue(promise: Promise<any>, expected: any, message?: string);
572
```
573

574
**Usage Examples:**
575

576
```javascript
577
// Assert on promised values
578
const titlePromise = browser.getTitle();
579
browser.assert.promisedValue(titlePromise, "Expected Title");
580

581
// Use with async/await
582
const currentUrl = await browser.getCurrentUrl();
583
browser.assert.urlEquals(currentUrl, "https://example.com/dashboard");
584
```
585

586
### Advanced Expectation Patterns
587

588
Complex assertion scenarios and custom validation logic.
589

590
**Usage Examples:**
591

592
```javascript
593
// Multiple element expectations
594
browser.expect.elements(".menu-item").count.to.equal(5);
595
browser.expect.elements(".error").count.to.be.above(0);
596

597
// Timeout-based expectations
598
browser.expect.element("#loading").to.not.be.visible.before(5000);
599
browser.expect.element("#results").to.be.present.after(2000);
600

601
// Conditional expectations
602
const submitButton = browser.expect.element("#submit");
603
if (await browser.isVisible("#terms-checkbox")) {
604
  submitButton.to.be.enabled.after(1000);
605
} else {
606
  submitButton.to.be.enabled;
607
}
608

609
// Custom error messages in expect chains
610
browser.expect.element("#status")
611
  .text.to.contain("Complete")
612
  .before(10000, "Status should show Complete within 10 seconds");
613
```