Repository navigation
Expand file tree
/
Copy pathindex.html
More file actions
672 lines (440 loc) · 146 KB
/
Copy pathindex.html
File metadata and controls
672 lines (440 loc) · 146 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
<!DOCTYPE html><html lang="en" dir="ltr" data-theme="dark" data-has-toc data-has-sidebar class="astro-qj6ycuyd"> <head><meta name="astro-view-transitions-enabled" content="true"><meta name="astro-view-transitions-fallback" content="animate"><script type="module" src="/_astro/ClientRouter.astro_astro_type_script_index_0_lang.CUKa2Nj2.js"></script> <meta charset="utf-8"/><meta name="viewport" content="width=device-width, initial-scale=1"/><title>Locators | </title><link rel="canonical" href="https://codecept.io/locators/"/><link rel="sitemap" href="/sitemap-index.xml"/><link rel="shortcut icon" href="/favicon.svg" type="image/svg+xml"/><meta name="generator" content="Astro v5.16.5"/><meta name="generator" content="Starlight v0.37.1"/><meta property="og:title" content="Locators"/><meta property="og:type" content="article"/><meta property="og:url" content="https://codecept.io/locators/"/><meta property="og:locale" content="en"/><meta property="og:site_name" content/><meta name="twitter:card" content="summary_large_image"/> <meta name="vtbot-replace-swap" content="data-theme"><script type="module" src="/_astro/ReplacementSwap.astro_astro_type_script_index_0_lang.D1Fl65FS.js"></script> <script type="module" src="/_astro/StarlightConnector.astro_astro_type_script_index_0_lang.BdsaPlsR.js"></script> <link rel="icon" href="/favicon.ico" sizes="32x32"> <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png"> <link rel="manifest" href="/site.webmanifest"> <meta name="theme-color" content="#ffffff" media="(prefers-color-scheme: light)"> <meta name="theme-color" content="#1a1d28" media="(prefers-color-scheme: dark)"> <meta property="og:image" content="https://codecept.io/og-image.png"> <meta property="og:image:width" content="1200"> <meta property="og:image:height" content="630"> <meta property="og:image:alt" content="CodeceptJS — Supercharged End 2 End Testing"> <meta name="twitter:image" content="https://codecept.io/og-image.png"> <script type="application/ld+json">{"@context":"https://schema.org","@type":"WebSite","@id":"locators","image":{"@type":"ImageObject","url":"https://codecept.io/og-image.png"},"inLanguage":"en","name":"","url":"https://codecept.io/locators/","sameAs":["https://codecept.io/","https://twitter.com/codeceptjs","https://codeceptjs.slack.com/join/shared_invite/zt-1dkxkju78-9aThX6G2~iDkLwhuRsPVsg","https://codecept.discourse.group/","https://stackoverflow.com/questions/tagged/codeceptjs","https://github.com/codeceptjs/CodeceptJS/discussions","https://github.com/codeceptjs/CodeceptJS"]}</script><script type="application/ld+json">{"@context":"https://schema.org","@type":"Organization","image":{"@type":"ImageObject","url":"https://codecept.io/og-image.png"},"url":"https://codecept.io/locators/","sameAs":["https://codecept.io/","https://twitter.com/codeceptjs","https://codeceptjs.slack.com/join/shared_invite/zt-1dkxkju78-9aThX6G2~iDkLwhuRsPVsg","https://codecept.discourse.group/","https://stackoverflow.com/questions/tagged/codeceptjs","https://github.com/codeceptjs/CodeceptJS/discussions","https://github.com/codeceptjs/CodeceptJS"],"logo":{"@type":"ImageObject","url":"https://codecept.io/favicon-512.png"},"name":"","@id":"locators"}</script><script type="application/ld+json">{"@context":"https://schema.org","@type":"Article","headline":"Locators","url":"https://codecept.io/locators/","image":{"@type":"ImageObject","url":"https://codecept.io/og-image.png"},"inLanguage":"en"}</script><script>
window.StarlightThemeProvider = (() => {
const storedTheme =
typeof localStorage !== 'undefined' && localStorage.getItem('starlight-theme');
const theme =
storedTheme ||
(window.matchMedia('(prefers-color-scheme: light)').matches ? 'light' : 'dark');
document.documentElement.dataset.theme = theme === 'light' ? 'light' : 'dark';
return {
updatePickers(theme = storedTheme || 'auto') {
document.querySelectorAll('starlight-theme-select').forEach((picker) => {
const select = picker.querySelector('select');
if (select) select.value = theme;
/** @type {HTMLTemplateElement | null} */
const tmpl = document.querySelector(`#theme-icons`);
const newIcon = tmpl && tmpl.content.querySelector('.' + theme);
if (newIcon) {
const oldIcon = picker.querySelector('svg.label-icon');
if (oldIcon) {
oldIcon.replaceChildren(...newIcon.cloneNode(true).childNodes);
}
}
});
},
};
})();
</script><template id="theme-icons"><svg aria-hidden="true" class="light astro-cbi3kmoi" width="16" height="16" viewBox="0 0 24 24" fill="currentColor" style="--sl-icon-size: 1em;"><path d="M5 12a1 1 0 0 0-1-1H3a1 1 0 0 0 0 2h1a1 1 0 0 0 1-1Zm.64 5-.71.71a1 1 0 0 0 0 1.41 1 1 0 0 0 1.41 0l.71-.71A1 1 0 0 0 5.64 17ZM12 5a1 1 0 0 0 1-1V3a1 1 0 0 0-2 0v1a1 1 0 0 0 1 1Zm5.66 2.34a1 1 0 0 0 .7-.29l.71-.71a1 1 0 1 0-1.41-1.41l-.66.71a1 1 0 0 0 0 1.41 1 1 0 0 0 .66.29Zm-12-.29a1 1 0 0 0 1.41 0 1 1 0 0 0 0-1.41l-.71-.71a1.004 1.004 0 1 0-1.43 1.41l.73.71ZM21 11h-1a1 1 0 0 0 0 2h1a1 1 0 0 0 0-2Zm-2.64 6A1 1 0 0 0 17 18.36l.71.71a1 1 0 0 0 1.41 0 1 1 0 0 0 0-1.41l-.76-.66ZM12 6.5a5.5 5.5 0 1 0 5.5 5.5A5.51 5.51 0 0 0 12 6.5Zm0 9a3.5 3.5 0 1 1 0-7 3.5 3.5 0 0 1 0 7Zm0 3.5a1 1 0 0 0-1 1v1a1 1 0 0 0 2 0v-1a1 1 0 0 0-1-1Z"/></svg><svg aria-hidden="true" class="dark astro-cbi3kmoi" width="16" height="16" viewBox="0 0 24 24" fill="currentColor" style="--sl-icon-size: 1em;"><path d="M21.64 13a1 1 0 0 0-1.05-.14 8.049 8.049 0 0 1-3.37.73 8.15 8.15 0 0 1-8.14-8.1 8.59 8.59 0 0 1 .25-2A1 1 0 0 0 8 2.36a10.14 10.14 0 1 0 14 11.69 1 1 0 0 0-.36-1.05Zm-9.5 6.69A8.14 8.14 0 0 1 7.08 5.22v.27a10.15 10.15 0 0 0 10.14 10.14 9.784 9.784 0 0 0 2.1-.22 8.11 8.11 0 0 1-7.18 4.32v-.04Z"/></svg><svg aria-hidden="true" class="auto astro-cbi3kmoi" width="16" height="16" viewBox="0 0 24 24" fill="currentColor" style="--sl-icon-size: 1em;"><path d="M21 14h-1V7a3 3 0 0 0-3-3H7a3 3 0 0 0-3 3v7H3a1 1 0 0 0-1 1v2a3 3 0 0 0 3 3h14a3 3 0 0 0 3-3v-2a1 1 0 0 0-1-1ZM6 7a1 1 0 0 1 1-1h10a1 1 0 0 1 1 1v7H6V7Zm14 10a1 1 0 0 1-1 1H5a1 1 0 0 1-1-1v-1h16v1Z"/></svg></template><link rel="stylesheet" href="/_astro/print.DNXP8c50.css" media="print"><link rel="stylesheet" href="/_astro/index.pXKxT3jn.css"><script type="module" src="/_astro/page.DxliP9JT.js"></script></head> <body class="astro-qj6ycuyd"> <a href="#_top" class="astro-6tfyvusb">Skip to content</a> <div class="page sl-flex astro-4toy2ex6" data-page-slug="locators"> <header id="site-header" class="header astro-4toy2ex6"> <div class="header astro-6cxfurdp"> <div class="title-wrapper sl-flex astro-6cxfurdp"> <a href="/" class="site-title sl-flex astro-idrpryed"> <img class="light:sl-hidden print:hidden astro-idrpryed" alt="CodeceptJS" src="/_astro/logo-dark.CPgSpTW_.svg" width="307" height="60"> <img class="dark:sl-hidden print:block astro-idrpryed" alt="CodeceptJS" src="/_astro/logo-light.BK93Ex33.svg" width="307" height="60"> <span class="sr-only astro-idrpryed" translate="no"> <span class="text-xl font-bold bg-clip-text text-gray-700 dark:text-gray-300 astro-idrpryed">CodeceptJS</span> </span> </a> </div> <div class="sl-flex print:hidden astro-6cxfurdp"> <div id="docsearch"></div> <script type="module" async>const apiKey = "6daf922b0e4a0992c66430766e751b1006a943857f503413ae4d36e489eeecc1";
const searchHost = "https://search.testomat.io";
const indexUid = "codeceptjs";
import { docsearch } from "https://cdn.jsdelivr.net/npm/meilisearch-docsearch@latest/dist/index.bundled.esm.js"
// web-api / mobile-api prioritization is handled server-side via
// `page_rank` + the `page_rank:desc` ranking rule in docsearch.json
// (custom_settings). No client-side hit reordering needed.
docsearch({
container: "#docsearch",
host: searchHost,
apiKey: apiKey,
indexUid: indexUid,
meilisearchOptions: {
limit: 20,
},
});
document.addEventListener("astro:before-preparation", () => {
document.querySelector(".docsearch-modal-search-cancel-btn")?.click();
});
</script> </div> <div class="sl-hidden md:sl-flex print:hidden right-group astro-6cxfurdp"> <div class="sl-flex social-icons astro-6cxfurdp"> <nav class="cc-header-nav" aria-label="Main navigation"> <button type="button" class="cc-nav-burger" aria-expanded="false" aria-label="Open navigation menu"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="cc-nav-burger-icon cc-nav-burger-open"><line x1="4" x2="20" y1="6" y2="6"></line><line x1="4" x2="20" y1="12" y2="12"></line><line x1="4" x2="20" y1="18" y2="18"></line></svg> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="cc-nav-burger-icon cc-nav-burger-close"><line x1="18" x2="6" y1="6" y2="18"></line><line x1="6" x2="18" y1="6" y2="18"></line></svg> </button> <div class="cc-nav-links"> <a href="/quickstart/" class="cc-nav-link no-underline text-gray-700 dark:text-gray-300 hover:text-black dark:hover:text-gray-200 transition-colors">
Guides
</a> <a href="/web-api/" class="cc-nav-link no-underline text-gray-700 dark:text-gray-300 hover:text-black dark:hover:text-gray-200 transition-colors">
API
</a> <a href="/blog/codeceptjs-4-2/" class="cc-nav-link no-underline text-gray-700 dark:text-gray-300 hover:text-black dark:hover:text-gray-200 transition-colors">
Blog
</a> <div class="cc-nav-dropdown"> <button type="button" class="cc-nav-link cc-nav-dropdown-btn text-gray-700 dark:text-gray-300 hover:text-black dark:hover:text-gray-200 transition-colors" aria-expanded="false">
Community
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="cc-nav-chevron lucide lucide-chevron-down"><path d="m6 9 6 6 6-6"></path></svg> </button> <div class="cc-nav-dropdown-panel bg-white dark:bg-gray-800"> <a href="https://github.com/codeceptjs/CodeceptJS" class="cc-nav-dropdown-item no-underline text-gray-700 dark:text-gray-300 hover:text-black dark:hover:text-gray-200"> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-github"><path d="M15 22v-4a4.8 4.8 0 0 0-1-3.5c3 0 6-2 6-5.5.08-1.25-.27-2.48-1-3.5.28-1.15.28-2.35 0-3.5 0 0-1 0-3 1.5-2.64-.5-5.36-.5-8 0C6 2 5 2 5 2c-.3 1.15-.3 2.35 0 3.5A5.403 5.403 0 0 0 4 9c0 3.5 3 5.5 6 5.5-.39.49-.68 1.05-.85 1.65-.17.6-.22 1.23-.15 1.85v4"></path><path d="M9 18c-4.51 2-5-2-7-2"></path></svg>
GitHub
</a> <a href="https://github.com/codeceptjs/CodeceptJS/discussions" class="cc-nav-dropdown-item no-underline text-gray-700 dark:text-gray-300 hover:text-black dark:hover:text-gray-200"> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-message-circle"><path d="M7.9 20A9 9 0 1 0 4 16.1L2 22Z"></path></svg>
Discussions
</a> <a href="https://github.com/codeceptjs/CodeceptJS/issues" class="cc-nav-dropdown-item no-underline text-gray-700 dark:text-gray-300 hover:text-black dark:hover:text-gray-200"> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-circle-dot"><circle cx="12" cy="12" r="10"></circle><circle cx="12" cy="12" r="1"></circle></svg>
Issues
</a> <a href="https://bit.ly/chat-codeceptjs" class="cc-nav-dropdown-item no-underline text-gray-700 dark:text-gray-300 hover:text-black dark:hover:text-gray-200"> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-message-circle"><path d="M7.9 20A9 9 0 1 0 4 16.1L2 22Z"></path></svg>
Slack
</a> <div class="cc-nav-dropdown-divider"></div> <a href="/release" class="cc-nav-dropdown-item no-underline text-gray-700 dark:text-gray-300 hover:text-black dark:hover:text-gray-200"> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-tag"><path d="M12.586 2.586A2 2 0 0 0 11.172 2H4a2 2 0 0 0-2 2v7.172a2 2 0 0 0 .586 1.414l8.704 8.704a2.426 2.426 0 0 0 3.42 0l6.58-6.58a2.426 2.426 0 0 0 0-3.42z"></path><circle cx="7.5" cy="7.5" r=".5" fill="currentColor"></circle></svg>
Releases
</a> <a href="/media-kit" class="cc-nav-dropdown-item no-underline text-gray-700 dark:text-gray-300 hover:text-black dark:hover:text-gray-200"> <img src="/logo/icon.svg" alt="" width="16" height="16">
Media Kit
</a> </div> </div> <a href="https://github.com/codeceptjs/CodeceptJS" class="cc-nav-link cc-nav-stars no-underline text-gray-700 dark:text-gray-300 hover:text-black dark:hover:text-gray-200 transition-colors" aria-label="CodeceptJS on GitHub, 4242 stars"> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-github" aria-hidden="true"><path d="M15 22v-4a4.8 4.8 0 0 0-1-3.5c3 0 6-2 6-5.5.08-1.25-.27-2.48-1-3.5.28-1.15.28-2.35 0-3.5 0 0-1 0-3 1.5-2.64-.5-5.36-.5-8 0C6 2 5 2 5 2c-.3 1.15-.3 2.35 0 3.5A5.403 5.403 0 0 0 4 9c0 3.5 3 5.5 6 5.5-.39.49-.68 1.05-.85 1.65-.17.6-.22 1.23-.15 1.85v4"></path><path d="M9 18c-4.51 2-5-2-7-2"></path></svg> <span class="cc-nav-stars-count"> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><path d="M11.525 2.295a.53.53 0 0 1 .95 0l2.31 4.679a2.123 2.123 0 0 0 1.595 1.16l5.166.756a.53.53 0 0 1 .294.904l-3.736 3.638a2.123 2.123 0 0 0-.611 1.878l.882 5.14a.53.53 0 0 1-.771.56l-4.618-2.428a2.122 2.122 0 0 0-1.973 0L6.396 21.01a.53.53 0 0 1-.77-.56l.881-5.139a2.122 2.122 0 0 0-.611-1.879L2.16 9.795a.53.53 0 0 1 .294-.906l5.165-.755a2.122 2.122 0 0 0 1.597-1.16z"></path></svg> 4.2k </span> </a> <div class="cc-nav-theme"> <span class="cc-nav-theme-label">Theme</span> <starlight-theme-toggle> <button type="button" class="cc-theme-toggle" role="switch" aria-checked="false" aria-label="Toggle dark mode" title="Toggle dark mode"> <span class="cc-theme-active" aria-hidden="true"></span> <span class="cc-theme-icon-side cc-theme-icon-sun" aria-hidden="true"> <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="4"></circle> <path d="M12 2v2"></path><path d="M12 20v2"></path> <path d="m4.93 4.93 1.41 1.41"></path><path d="m17.66 17.66 1.41 1.41"></path> <path d="M2 12h2"></path><path d="M20 12h2"></path> <path d="m6.34 17.66-1.41 1.41"></path><path d="m19.07 4.93-1.41 1.41"></path> </svg> </span> <span class="cc-theme-icon-side cc-theme-icon-moon" aria-hidden="true"> <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"> <path d="M12 3a6 6 0 0 0 9 9 9 9 0 1 1-9-9Z"></path> </svg> </span> </button> </starlight-theme-toggle> </div> </div> </nav> <script type="module" src="/_astro/Links.astro_astro_type_script_index_0_lang.BujyuUnY.js"></script> </div> <starlight-theme-toggle> <button type="button" class="cc-theme-toggle" role="switch" aria-checked="false" aria-label="Toggle dark mode" title="Toggle dark mode"> <span class="cc-theme-active" aria-hidden="true"></span> <span class="cc-theme-icon-side cc-theme-icon-sun" aria-hidden="true"> <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="4"></circle> <path d="M12 2v2"></path><path d="M12 20v2"></path> <path d="m4.93 4.93 1.41 1.41"></path><path d="m17.66 17.66 1.41 1.41"></path> <path d="M2 12h2"></path><path d="M20 12h2"></path> <path d="m6.34 17.66-1.41 1.41"></path><path d="m19.07 4.93-1.41 1.41"></path> </svg> </span> <span class="cc-theme-icon-side cc-theme-icon-moon" aria-hidden="true"> <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"> <path d="M12 3a6 6 0 0 0 9 9 9 9 0 1 1-9-9Z"></path> </svg> </span> </button> </starlight-theme-toggle> <script type="module" src="/_astro/ThemeSelect.astro_astro_type_script_index_0_lang.Bo6WLquL.js"></script> <script type="module" src="/_astro/LanguageSelect.astro_astro_type_script_index_0_lang.Ce-i7NLC.js"></script> </div> </div> </header> <nav class="sidebar print:hidden astro-4toy2ex6" aria-label="Main"> <starlight-menu-button class="print:hidden astro-5jxskpfx"> <button aria-expanded="false" aria-label="Menu" aria-controls="starlight__sidebar" class="sl-flex md:sl-hidden astro-5jxskpfx"> <svg aria-hidden="true" class="open-menu astro-5jxskpfx astro-cbi3kmoi" width="16" height="16" viewBox="0 0 24 24" fill="currentColor" style="--sl-icon-size: 1em;"><path d="M3 8h18a1 1 0 1 0 0-2H3a1 1 0 0 0 0 2Zm18 8H3a1 1 0 0 0 0 2h18a1 1 0 0 0 0-2Zm0-5H3a1 1 0 0 0 0 2h18a1 1 0 0 0 0-2Z"/></svg> <svg aria-hidden="true" class="close-menu astro-5jxskpfx astro-cbi3kmoi" width="16" height="16" viewBox="0 0 24 24" fill="currentColor" style="--sl-icon-size: 1em;"><path d="m13.41 12 6.3-6.29a1.004 1.004 0 1 0-1.42-1.42L12 10.59l-6.29-6.3a1.004 1.004 0 0 0-1.42 1.42l6.3 6.29-6.3 6.29a1 1 0 0 0 0 1.42.998.998 0 0 0 1.42 0l6.29-6.3 6.29 6.3a.999.999 0 0 0 1.42 0 1 1 0 0 0 0-1.42L13.41 12Z"/></svg> </button> </starlight-menu-button> <script type="module" src="/_astro/MobileMenuToggle.astro_astro_type_script_index_0_lang.CsfLbggW.js"></script> <div id="starlight__sidebar" class="sidebar-pane astro-4toy2ex6"> <div class="sidebar-content sl-flex astro-4toy2ex6"> <ul class="starlight-sidebar-topics astro-mqaomtvk"> <li class="astro-mqaomtvk"> <a href="/quickstart/" class="starlight-sidebar-topics-current astro-mqaomtvk"> <div class="astro-mqaomtvk"> Guides </div> </a> </li><li class="astro-mqaomtvk"> <a href="/web-api/" class="astro-mqaomtvk"> <div class="astro-mqaomtvk"> Reference </div> </a> </li><li class="astro-mqaomtvk"> <a href="/blog/codeceptjs-4-2/" class="astro-mqaomtvk"> <div class="astro-mqaomtvk"> Blog </div> </a> </li> </ul> <sl-sidebar-state-persist data-hash="0o7lit9" class="astro-xy2ooljs"> <script aria-hidden="true">
(() => {
try {
if (!matchMedia('(min-width: 50em)').matches) return;
/** @type {HTMLElement | null} */
const target = document.querySelector('sl-sidebar-state-persist');
const state = JSON.parse(sessionStorage.getItem('sl-sidebar-state') || '0');
if (!target || !state || target.dataset.hash !== state.hash) return;
window._starlightScrollRestore = state.scroll;
customElements.define(
'sl-sidebar-restore',
class SidebarRestore extends HTMLElement {
connectedCallback() {
try {
const idx = parseInt(this.dataset.index || '');
const details = this.closest('details');
if (details && typeof state.open[idx] === 'boolean') details.open = state.open[idx];
} catch {}
}
}
);
} catch {}
})();
</script> <ul class="top-level astro-ova6qb4d"> <li class="astro-ova6qb4d"> <details open class="astro-ova6qb4d"> <summary class="astro-ova6qb4d"> <span class="group-label astro-ova6qb4d"> <span class="large astro-ova6qb4d">Setup</span> </span> <svg aria-hidden="true" class="caret astro-ova6qb4d astro-cbi3kmoi" width="16" height="16" viewBox="0 0 24 24" fill="currentColor" style="--sl-icon-size: 1.25rem;"><path d="m14.83 11.29-4.24-4.24a1 1 0 1 0-1.42 1.41L12.71 12l-3.54 3.54a1 1 0 0 0 0 1.41 1 1 0 0 0 .71.29 1 1 0 0 0 .71-.29l4.24-4.24a1.002 1.002 0 0 0 0-1.42Z"/></svg> </summary> <sl-sidebar-restore data-index="0"></sl-sidebar-restore> <ul class="astro-ova6qb4d"> <li class="astro-ova6qb4d"> <a href="/quickstart" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Quickstart</span> </a> </li><li class="astro-ova6qb4d"> <a href="/installation" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Installation</span> </a> </li><li class="astro-ova6qb4d"> <a href="/migration-4" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Upgrade</span> </a> </li><li class="astro-ova6qb4d"> <a href="/migrate-from-cypress" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Migrate from Cypress.io</span> </a> </li><li class="astro-ova6qb4d"> <a href="/migrate-from-java" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Migrate from Java Selenium</span> </a> </li><li class="astro-ova6qb4d"> <a href="/migrate-from-testcafe" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Migrate from TestCafe</span> </a> </li><li class="astro-ova6qb4d"> <a href="/migrate-from-protractor" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Migrate from Protractor</span> </a> </li> </ul> </details> </li><li class="astro-ova6qb4d"> <details open class="astro-ova6qb4d"> <summary class="astro-ova6qb4d"> <span class="group-label astro-ova6qb4d"> <span class="large astro-ova6qb4d">Basics</span> </span> <svg aria-hidden="true" class="caret astro-ova6qb4d astro-cbi3kmoi" width="16" height="16" viewBox="0 0 24 24" fill="currentColor" style="--sl-icon-size: 1.25rem;"><path d="m14.83 11.29-4.24-4.24a1 1 0 1 0-1.42 1.41L12.71 12l-3.54 3.54a1 1 0 0 0 0 1.41 1 1 0 0 0 .71.29 1 1 0 0 0 .71-.29l4.24-4.24a1.002 1.002 0 0 0 0-1.42Z"/></svg> </summary> <sl-sidebar-restore data-index="1"></sl-sidebar-restore> <ul class="astro-ova6qb4d"> <li class="astro-ova6qb4d"> <a href="/basics" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Web Basics</span> </a> </li><li class="astro-ova6qb4d"> <a href="/agents" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Agentic Testing</span> </a> </li><li class="astro-ova6qb4d"> <a href="/explorbot" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Self-Driving Tests</span> </a> </li><li class="astro-ova6qb4d"> <a href="/test-structure" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Test Structure</span> </a> </li><li class="astro-ova6qb4d"> <a href="/locators" aria-current="page" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Locators</span> </a> </li><li class="astro-ova6qb4d"> <a href="/assertions" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Assertions</span> </a> </li><li class="astro-ova6qb4d"> <a href="/element-based-testing" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Element Testing</span> </a> </li><li class="astro-ova6qb4d"> <a href="/debugging" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Debugging</span> </a> </li> </ul> </details> </li><li class="astro-ova6qb4d"> <details open class="astro-ova6qb4d"> <summary class="astro-ova6qb4d"> <span class="group-label astro-ova6qb4d"> <span class="large astro-ova6qb4d">Web & Mobile Testing</span> </span> <svg aria-hidden="true" class="caret astro-ova6qb4d astro-cbi3kmoi" width="16" height="16" viewBox="0 0 24 24" fill="currentColor" style="--sl-icon-size: 1.25rem;"><path d="m14.83 11.29-4.24-4.24a1 1 0 1 0-1.42 1.41L12.71 12l-3.54 3.54a1 1 0 0 0 0 1.41 1 1 0 0 0 .71.29 1 1 0 0 0 .71-.29l4.24-4.24a1.002 1.002 0 0 0 0-1.42Z"/></svg> </summary> <sl-sidebar-restore data-index="2"></sl-sidebar-restore> <ul class="astro-ova6qb4d"> <li class="astro-ova6qb4d"> <a href="/playwright" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Testing with Playwright</span> </a> </li><li class="astro-ova6qb4d"> <a href="/webdriver" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Testing with WebDriver</span> </a> </li><li class="astro-ova6qb4d"> <a href="/puppeteer" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Testing with Puppeteer</span> </a> </li><li class="astro-ova6qb4d"> <a href="/alternative-browsers" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Alternative Browsers</span> </a> </li><li class="astro-ova6qb4d"> <a href="/mobile" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Mobile Testing with Appium</span> </a> </li><li class="astro-ova6qb4d"> <a href="/detox" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Testing React Native with Detox</span> </a> </li> </ul> </details> </li><li class="astro-ova6qb4d"> <details open class="astro-ova6qb4d"> <summary class="astro-ova6qb4d"> <span class="group-label astro-ova6qb4d"> <span class="large astro-ova6qb4d">Organizing Tests</span> </span> <svg aria-hidden="true" class="caret astro-ova6qb4d astro-cbi3kmoi" width="16" height="16" viewBox="0 0 24 24" fill="currentColor" style="--sl-icon-size: 1.25rem;"><path d="m14.83 11.29-4.24-4.24a1 1 0 1 0-1.42 1.41L12.71 12l-3.54 3.54a1 1 0 0 0 0 1.41 1 1 0 0 0 .71.29 1 1 0 0 0 .71-.29l4.24-4.24a1.002 1.002 0 0 0 0-1.42Z"/></svg> </summary> <sl-sidebar-restore data-index="3"></sl-sidebar-restore> <ul class="astro-ova6qb4d"> <li class="astro-ova6qb4d"> <a href="/pageobjects" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Page Objects</span> </a> </li><li class="astro-ova6qb4d"> <a href="/data" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Data Management</span> </a> </li><li class="astro-ova6qb4d"> <a href="/bdd" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Behavior Driven Development</span> </a> </li><li class="astro-ova6qb4d"> <a href="/best" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Best Practices</span> </a> </li> </ul> </details> </li><li class="astro-ova6qb4d"> <details open class="astro-ova6qb4d"> <summary class="astro-ova6qb4d"> <span class="group-label astro-ova6qb4d"> <span class="large astro-ova6qb4d">Advanced Usage</span> </span> <svg aria-hidden="true" class="caret astro-ova6qb4d astro-cbi3kmoi" width="16" height="16" viewBox="0 0 24 24" fill="currentColor" style="--sl-icon-size: 1.25rem;"><path d="m14.83 11.29-4.24-4.24a1 1 0 1 0-1.42 1.41L12.71 12l-3.54 3.54a1 1 0 0 0 0 1.41 1 1 0 0 0 .71.29 1 1 0 0 0 .71-.29l4.24-4.24a1.002 1.002 0 0 0 0-1.42Z"/></svg> </summary> <sl-sidebar-restore data-index="4"></sl-sidebar-restore> <ul class="astro-ova6qb4d"> <li class="astro-ova6qb4d"> <a href="/api" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">API Testing</span> </a> </li><li class="astro-ova6qb4d"> <a href="/architecture" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Architecture</span> </a> </li><li class="astro-ova6qb4d"> <a href="/bootstrap" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Bootstrap</span> </a> </li><li class="astro-ova6qb4d"> <a href="/continuous-integration" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Continuous Integration</span> </a> </li><li class="astro-ova6qb4d"> <a href="/docker" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Docker</span> </a> </li><li class="astro-ova6qb4d"> <a href="/effects" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Effects</span> </a> </li><li class="astro-ova6qb4d"> <a href="/element-selection" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Element Selection</span> </a> </li><li class="astro-ova6qb4d"> <a href="/ai" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Enable AI</span> </a> </li><li class="astro-ova6qb4d"> <a href="/hooks" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Extending</span> </a> </li><li class="astro-ova6qb4d"> <a href="/parallel" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Parallel Execution</span> </a> </li><li class="astro-ova6qb4d"> <a href="/reports" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Reporting</span> </a> </li><li class="astro-ova6qb4d"> <a href="/retry" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Retries</span> </a> </li><li class="astro-ova6qb4d"> <a href="/secrets" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Secrets</span> </a> </li><li class="astro-ova6qb4d"> <a href="/heal" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Self-Healing</span> </a> </li><li class="astro-ova6qb4d"> <a href="/timeouts" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Timeouts</span> </a> </li><li class="astro-ova6qb4d"> <a href="/typescript" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">TypeScript</span> </a> </li><li class="astro-ova6qb4d"> <a href="/within" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Within</span> </a> </li><li class="astro-ova6qb4d"> <a href="/shadow" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Shadow DOM</span> </a> </li><li class="astro-ova6qb4d"> <a href="/translation" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Translation</span> </a> </li> </ul> </details> </li><li class="astro-ova6qb4d"> <details open class="astro-ova6qb4d"> <summary class="astro-ova6qb4d"> <span class="group-label astro-ova6qb4d"> <span class="large astro-ova6qb4d">Resources</span> </span> <svg aria-hidden="true" class="caret astro-ova6qb4d astro-cbi3kmoi" width="16" height="16" viewBox="0 0 24 24" fill="currentColor" style="--sl-icon-size: 1.25rem;"><path d="m14.83 11.29-4.24-4.24a1 1 0 1 0-1.42 1.41L12.71 12l-3.54 3.54a1 1 0 0 0 0 1.41 1 1 0 0 0 .71.29 1 1 0 0 0 .71-.29l4.24-4.24a1.002 1.002 0 0 0 0-1.42Z"/></svg> </summary> <sl-sidebar-restore data-index="5"></sl-sidebar-restore> <ul class="astro-ova6qb4d"> <li class="astro-ova6qb4d"> <a href="/tutorial" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Tutorial</span> </a> </li><li class="astro-ova6qb4d"> <a href="/cheatsheet" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Cheatsheet</span> </a> </li><li class="astro-ova6qb4d"> <a href="/media-kit" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Media Kit</span> </a> </li><li class="astro-ova6qb4d"> <a href="/release" aria-current="false" class="astro-ova6qb4d"> <span class="astro-ova6qb4d">Release Notes</span> </a> </li> </ul> </details> </li> </ul> <script aria-hidden="true">
(() => {
const scroller = document.getElementById('starlight__sidebar');
if (!window._starlightScrollRestore || !scroller) return;
scroller.scrollTop = window._starlightScrollRestore;
delete window._starlightScrollRestore;
})();
</script> </sl-sidebar-state-persist> <div class="md:sl-hidden"> <div class="mobile-preferences sl-flex astro-yw2ikf7j"> <div class="social-icons astro-yw2ikf7j"> <nav class="cc-header-nav" aria-label="Main navigation"> <button type="button" class="cc-nav-burger" aria-expanded="false" aria-label="Open navigation menu"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="cc-nav-burger-icon cc-nav-burger-open"><line x1="4" x2="20" y1="6" y2="6"></line><line x1="4" x2="20" y1="12" y2="12"></line><line x1="4" x2="20" y1="18" y2="18"></line></svg> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="cc-nav-burger-icon cc-nav-burger-close"><line x1="18" x2="6" y1="6" y2="18"></line><line x1="6" x2="18" y1="6" y2="18"></line></svg> </button> <div class="cc-nav-links"> <a href="/quickstart/" class="cc-nav-link no-underline text-gray-700 dark:text-gray-300 hover:text-black dark:hover:text-gray-200 transition-colors">
Guides
</a> <a href="/web-api/" class="cc-nav-link no-underline text-gray-700 dark:text-gray-300 hover:text-black dark:hover:text-gray-200 transition-colors">
API
</a> <a href="/blog/codeceptjs-4-2/" class="cc-nav-link no-underline text-gray-700 dark:text-gray-300 hover:text-black dark:hover:text-gray-200 transition-colors">
Blog
</a> <div class="cc-nav-dropdown"> <button type="button" class="cc-nav-link cc-nav-dropdown-btn text-gray-700 dark:text-gray-300 hover:text-black dark:hover:text-gray-200 transition-colors" aria-expanded="false">
Community
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="cc-nav-chevron lucide lucide-chevron-down"><path d="m6 9 6 6 6-6"></path></svg> </button> <div class="cc-nav-dropdown-panel bg-white dark:bg-gray-800"> <a href="https://github.com/codeceptjs/CodeceptJS" class="cc-nav-dropdown-item no-underline text-gray-700 dark:text-gray-300 hover:text-black dark:hover:text-gray-200"> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-github"><path d="M15 22v-4a4.8 4.8 0 0 0-1-3.5c3 0 6-2 6-5.5.08-1.25-.27-2.48-1-3.5.28-1.15.28-2.35 0-3.5 0 0-1 0-3 1.5-2.64-.5-5.36-.5-8 0C6 2 5 2 5 2c-.3 1.15-.3 2.35 0 3.5A5.403 5.403 0 0 0 4 9c0 3.5 3 5.5 6 5.5-.39.49-.68 1.05-.85 1.65-.17.6-.22 1.23-.15 1.85v4"></path><path d="M9 18c-4.51 2-5-2-7-2"></path></svg>
GitHub
</a> <a href="https://github.com/codeceptjs/CodeceptJS/discussions" class="cc-nav-dropdown-item no-underline text-gray-700 dark:text-gray-300 hover:text-black dark:hover:text-gray-200"> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-message-circle"><path d="M7.9 20A9 9 0 1 0 4 16.1L2 22Z"></path></svg>
Discussions
</a> <a href="https://github.com/codeceptjs/CodeceptJS/issues" class="cc-nav-dropdown-item no-underline text-gray-700 dark:text-gray-300 hover:text-black dark:hover:text-gray-200"> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-circle-dot"><circle cx="12" cy="12" r="10"></circle><circle cx="12" cy="12" r="1"></circle></svg>
Issues
</a> <a href="https://bit.ly/chat-codeceptjs" class="cc-nav-dropdown-item no-underline text-gray-700 dark:text-gray-300 hover:text-black dark:hover:text-gray-200"> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-message-circle"><path d="M7.9 20A9 9 0 1 0 4 16.1L2 22Z"></path></svg>
Slack
</a> <div class="cc-nav-dropdown-divider"></div> <a href="/release" class="cc-nav-dropdown-item no-underline text-gray-700 dark:text-gray-300 hover:text-black dark:hover:text-gray-200"> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-tag"><path d="M12.586 2.586A2 2 0 0 0 11.172 2H4a2 2 0 0 0-2 2v7.172a2 2 0 0 0 .586 1.414l8.704 8.704a2.426 2.426 0 0 0 3.42 0l6.58-6.58a2.426 2.426 0 0 0 0-3.42z"></path><circle cx="7.5" cy="7.5" r=".5" fill="currentColor"></circle></svg>
Releases
</a> <a href="/media-kit" class="cc-nav-dropdown-item no-underline text-gray-700 dark:text-gray-300 hover:text-black dark:hover:text-gray-200"> <img src="/logo/icon.svg" alt="" width="16" height="16">
Media Kit
</a> </div> </div> <a href="https://github.com/codeceptjs/CodeceptJS" class="cc-nav-link cc-nav-stars no-underline text-gray-700 dark:text-gray-300 hover:text-black dark:hover:text-gray-200 transition-colors" aria-label="CodeceptJS on GitHub, 4242 stars"> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-github" aria-hidden="true"><path d="M15 22v-4a4.8 4.8 0 0 0-1-3.5c3 0 6-2 6-5.5.08-1.25-.27-2.48-1-3.5.28-1.15.28-2.35 0-3.5 0 0-1 0-3 1.5-2.64-.5-5.36-.5-8 0C6 2 5 2 5 2c-.3 1.15-.3 2.35 0 3.5A5.403 5.403 0 0 0 4 9c0 3.5 3 5.5 6 5.5-.39.49-.68 1.05-.85 1.65-.17.6-.22 1.23-.15 1.85v4"></path><path d="M9 18c-4.51 2-5-2-7-2"></path></svg> <span class="cc-nav-stars-count"> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><path d="M11.525 2.295a.53.53 0 0 1 .95 0l2.31 4.679a2.123 2.123 0 0 0 1.595 1.16l5.166.756a.53.53 0 0 1 .294.904l-3.736 3.638a2.123 2.123 0 0 0-.611 1.878l.882 5.14a.53.53 0 0 1-.771.56l-4.618-2.428a2.122 2.122 0 0 0-1.973 0L6.396 21.01a.53.53 0 0 1-.77-.56l.881-5.139a2.122 2.122 0 0 0-.611-1.879L2.16 9.795a.53.53 0 0 1 .294-.906l5.165-.755a2.122 2.122 0 0 0 1.597-1.16z"></path></svg> 4.2k </span> </a> <div class="cc-nav-theme"> <span class="cc-nav-theme-label">Theme</span> <starlight-theme-toggle> <button type="button" class="cc-theme-toggle" role="switch" aria-checked="false" aria-label="Toggle dark mode" title="Toggle dark mode"> <span class="cc-theme-active" aria-hidden="true"></span> <span class="cc-theme-icon-side cc-theme-icon-sun" aria-hidden="true"> <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="4"></circle> <path d="M12 2v2"></path><path d="M12 20v2"></path> <path d="m4.93 4.93 1.41 1.41"></path><path d="m17.66 17.66 1.41 1.41"></path> <path d="M2 12h2"></path><path d="M20 12h2"></path> <path d="m6.34 17.66-1.41 1.41"></path><path d="m19.07 4.93-1.41 1.41"></path> </svg> </span> <span class="cc-theme-icon-side cc-theme-icon-moon" aria-hidden="true"> <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"> <path d="M12 3a6 6 0 0 0 9 9 9 9 0 1 1-9-9Z"></path> </svg> </span> </button> </starlight-theme-toggle> </div> </div> </nav> </div> <starlight-theme-toggle> <button type="button" class="cc-theme-toggle" role="switch" aria-checked="false" aria-label="Toggle dark mode" title="Toggle dark mode"> <span class="cc-theme-active" aria-hidden="true"></span> <span class="cc-theme-icon-side cc-theme-icon-sun" aria-hidden="true"> <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="4"></circle> <path d="M12 2v2"></path><path d="M12 20v2"></path> <path d="m4.93 4.93 1.41 1.41"></path><path d="m17.66 17.66 1.41 1.41"></path> <path d="M2 12h2"></path><path d="M20 12h2"></path> <path d="m6.34 17.66-1.41 1.41"></path><path d="m19.07 4.93-1.41 1.41"></path> </svg> </span> <span class="cc-theme-icon-side cc-theme-icon-moon" aria-hidden="true"> <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"> <path d="M12 3a6 6 0 0 0 9 9 9 9 0 1 1-9-9Z"></path> </svg> </span> </button> </starlight-theme-toggle> </div> </div> </div> </div> </nav> <div class="main-frame astro-4toy2ex6"> <script type="module" src="/_astro/Page.astro_astro_type_script_index_0_lang.BHQeG8Vj.js"></script> <div class="lg:sl-flex astro-4deqquyo"> <aside class="right-sidebar-container print:hidden astro-4deqquyo"> <div class="right-sidebar astro-4deqquyo"> <div class="lg:sl-hidden astro-nzouaqej"><mobile-starlight-toc data-min-h="2" data-max-h="3" class="astro-g3oy5c6o"><nav aria-labelledby="starlight__on-this-page--mobile" class="astro-g3oy5c6o"><details id="starlight__mobile-toc" class="astro-g3oy5c6o"><summary id="starlight__on-this-page--mobile" class="sl-flex astro-g3oy5c6o"><span class="toggle sl-flex astro-g3oy5c6o">On this page<svg aria-hidden="true" class="caret astro-g3oy5c6o astro-cbi3kmoi" width="16" height="16" viewBox="0 0 24 24" fill="currentColor" style="--sl-icon-size: 1rem;"><path d="m14.83 11.29-4.24-4.24a1 1 0 1 0-1.42 1.41L12.71 12l-3.54 3.54a1 1 0 0 0 0 1.41 1 1 0 0 0 .71.29 1 1 0 0 0 .71-.29l4.24-4.24a1.002 1.002 0 0 0 0-1.42Z"/></svg></span><span class="display-current astro-g3oy5c6o"></span></summary><div class="dropdown astro-g3oy5c6o"><ul class="isMobile astro-vfcvrjst" style="--depth: 0;"> <li class="astro-vfcvrjst" style="--depth: 0;"> <a href="#_top" class="astro-vfcvrjst" style="--depth: 0;"> <span class="astro-vfcvrjst" style="--depth: 0;">Overview</span> </a> </li><li class="astro-vfcvrjst" style="--depth: 0;"> <a href="#locator-types-at-a-glance" class="astro-vfcvrjst" style="--depth: 0;"> <span class="astro-vfcvrjst" style="--depth: 0;">Locator types at a glance</span> </a> </li><li class="astro-vfcvrjst" style="--depth: 0;"> <a href="#aria-locators" class="astro-vfcvrjst" style="--depth: 0;"> <span class="astro-vfcvrjst" style="--depth: 0;">ARIA locators</span> </a> </li><li class="astro-vfcvrjst" style="--depth: 0;"> <a href="#css-selectors" class="astro-vfcvrjst" style="--depth: 0;"> <span class="astro-vfcvrjst" style="--depth: 0;">CSS selectors</span> </a> </li><li class="astro-vfcvrjst" style="--depth: 0;"> <a href="#xpath" class="astro-vfcvrjst" style="--depth: 0;"> <span class="astro-vfcvrjst" style="--depth: 0;">XPath</span> </a> </li><li class="astro-vfcvrjst" style="--depth: 0;"> <a href="#semantic-locators" class="astro-vfcvrjst" style="--depth: 0;"> <span class="astro-vfcvrjst" style="--depth: 0;">Semantic locators</span> </a> <ul class="isMobile astro-vfcvrjst" style="--depth: 1;"> <li class="astro-vfcvrjst" style="--depth: 1;"> <a href="#pair-semantic-locators-with-a-context" class="astro-vfcvrjst" style="--depth: 1;"> <span class="astro-vfcvrjst" style="--depth: 1;">Pair semantic locators with a context</span> </a> </li><li class="astro-vfcvrjst" style="--depth: 1;"> <a href="#how-matching-works" class="astro-vfcvrjst" style="--depth: 1;"> <span class="astro-vfcvrjst" style="--depth: 1;">How matching works</span> </a> </li> </ul> </li><li class="astro-vfcvrjst" style="--depth: 0;"> <a href="#id-locators" class="astro-vfcvrjst" style="--depth: 0;"> <span class="astro-vfcvrjst" style="--depth: 0;">ID locators</span> </a> </li><li class="astro-vfcvrjst" style="--depth: 0;"> <a href="#picking-a-specific-element" class="astro-vfcvrjst" style="--depth: 0;"> <span class="astro-vfcvrjst" style="--depth: 0;">Picking a specific element</span> </a> </li><li class="astro-vfcvrjst" style="--depth: 0;"> <a href="#combining-locators" class="astro-vfcvrjst" style="--depth: 0;"> <span class="astro-vfcvrjst" style="--depth: 0;">Combining locators</span> </a> <ul class="isMobile astro-vfcvrjst" style="--depth: 1;"> <li class="astro-vfcvrjst" style="--depth: 1;"> <a href="#context-scope-any-locator-to-a-region" class="astro-vfcvrjst" style="--depth: 1;"> <span class="astro-vfcvrjst" style="--depth: 1;">Context: scope any locator to a region</span> </a> </li><li class="astro-vfcvrjst" style="--depth: 1;"> <a href="#locate-builder-compose-css-and-xpath" class="astro-vfcvrjst" style="--depth: 1;"> <span class="astro-vfcvrjst" style="--depth: 1;">locate() builder: compose CSS and XPath</span> </a> </li> </ul> </li><li class="astro-vfcvrjst" style="--depth: 0;"> <a href="#custom-locators" class="astro-vfcvrjst" style="--depth: 0;"> <span class="astro-vfcvrjst" style="--depth: 0;">Custom locators</span> </a> </li> </ul> </div></details></nav></mobile-starlight-toc><script type="module" src="/_astro/MobileTableOfContents.astro_astro_type_script_index_0_lang.C181hMzK.js"></script></div><div class="right-sidebar-panel sl-hidden lg:sl-block astro-nzouaqej"><div class="sl-container astro-nzouaqej"><starlight-toc data-min-h="2" data-max-h="3"><nav aria-labelledby="starlight__on-this-page"><h2 id="starlight__on-this-page">On this page</h2><ul class="astro-vfcvrjst" style="--depth: 0;"> <li class="astro-vfcvrjst" style="--depth: 0;"> <a href="#_top" class="astro-vfcvrjst" style="--depth: 0;"> <span class="astro-vfcvrjst" style="--depth: 0;">Overview</span> </a> </li><li class="astro-vfcvrjst" style="--depth: 0;"> <a href="#locator-types-at-a-glance" class="astro-vfcvrjst" style="--depth: 0;"> <span class="astro-vfcvrjst" style="--depth: 0;">Locator types at a glance</span> </a> </li><li class="astro-vfcvrjst" style="--depth: 0;"> <a href="#aria-locators" class="astro-vfcvrjst" style="--depth: 0;"> <span class="astro-vfcvrjst" style="--depth: 0;">ARIA locators</span> </a> </li><li class="astro-vfcvrjst" style="--depth: 0;"> <a href="#css-selectors" class="astro-vfcvrjst" style="--depth: 0;"> <span class="astro-vfcvrjst" style="--depth: 0;">CSS selectors</span> </a> </li><li class="astro-vfcvrjst" style="--depth: 0;"> <a href="#xpath" class="astro-vfcvrjst" style="--depth: 0;"> <span class="astro-vfcvrjst" style="--depth: 0;">XPath</span> </a> </li><li class="astro-vfcvrjst" style="--depth: 0;"> <a href="#semantic-locators" class="astro-vfcvrjst" style="--depth: 0;"> <span class="astro-vfcvrjst" style="--depth: 0;">Semantic locators</span> </a> <ul class="astro-vfcvrjst" style="--depth: 1;"> <li class="astro-vfcvrjst" style="--depth: 1;"> <a href="#pair-semantic-locators-with-a-context" class="astro-vfcvrjst" style="--depth: 1;"> <span class="astro-vfcvrjst" style="--depth: 1;">Pair semantic locators with a context</span> </a> </li><li class="astro-vfcvrjst" style="--depth: 1;"> <a href="#how-matching-works" class="astro-vfcvrjst" style="--depth: 1;"> <span class="astro-vfcvrjst" style="--depth: 1;">How matching works</span> </a> </li> </ul> </li><li class="astro-vfcvrjst" style="--depth: 0;"> <a href="#id-locators" class="astro-vfcvrjst" style="--depth: 0;"> <span class="astro-vfcvrjst" style="--depth: 0;">ID locators</span> </a> </li><li class="astro-vfcvrjst" style="--depth: 0;"> <a href="#picking-a-specific-element" class="astro-vfcvrjst" style="--depth: 0;"> <span class="astro-vfcvrjst" style="--depth: 0;">Picking a specific element</span> </a> </li><li class="astro-vfcvrjst" style="--depth: 0;"> <a href="#combining-locators" class="astro-vfcvrjst" style="--depth: 0;"> <span class="astro-vfcvrjst" style="--depth: 0;">Combining locators</span> </a> <ul class="astro-vfcvrjst" style="--depth: 1;"> <li class="astro-vfcvrjst" style="--depth: 1;"> <a href="#context-scope-any-locator-to-a-region" class="astro-vfcvrjst" style="--depth: 1;"> <span class="astro-vfcvrjst" style="--depth: 1;">Context: scope any locator to a region</span> </a> </li><li class="astro-vfcvrjst" style="--depth: 1;"> <a href="#locate-builder-compose-css-and-xpath" class="astro-vfcvrjst" style="--depth: 1;"> <span class="astro-vfcvrjst" style="--depth: 1;">locate() builder: compose CSS and XPath</span> </a> </li> </ul> </li><li class="astro-vfcvrjst" style="--depth: 0;"> <a href="#custom-locators" class="astro-vfcvrjst" style="--depth: 0;"> <span class="astro-vfcvrjst" style="--depth: 0;">Custom locators</span> </a> </li> </ul> </nav></starlight-toc><script type="module" src="/_astro/TableOfContents.astro_astro_type_script_index_0_lang.CKWWgpjV.js"></script></div></div> </div> </aside> <div class="main-pane astro-4deqquyo"> <main data-pagefind-body class="astro-qj6ycuyd" lang="en" dir="ltr"> <div class="content-panel astro-7vmgf2si"> <div class="sl-container astro-7vmgf2si"> <div class="astro-guvttfii"></div><h1 id="_top" class="astro-bmayhthr">Locators</h1> </div> </div> <div class="content-panel astro-7vmgf2si"> <div class="sl-container astro-7vmgf2si"> <starlight-image-zoom> <template class="astro-qteoq5nn"> <dialog class="starlight-image-zoom-dialog astro-qteoq5nn"> <button aria-label="Unzoom image" class="starlight-image-zoom-control astro-qteoq5nn"> <svg aria-hidden="true" fill="currentColor" viewBox="0 0 24 24" class="astro-qteoq5nn"> <use href="#starlight-image-zoom-icon-unzoom" class="astro-qteoq5nn"></use> </svg> </button> <figure class="astro-qteoq5nn"></figure> </dialog> </template> <svg xmlns="http://www.w3.org/2000/svg" style="display:none" class="astro-qteoq5nn"> <symbol id="starlight-image-zoom-icon-zoom" viewBox="0 0 24 24" class="astro-qteoq5nn"> <path d="M9.79 12.79 4 18.59V17a1 1 0 0 0-2 0v4a1 1 0 0 0 .08.38 1 1 0 0 0 .54.54A1 1 0 0 0 3 22h4a1 1 0 0 0 0-2H5.41l5.8-5.79a1 1 0 0 0-1.42-1.42ZM21.92 2.62a1 1 0 0 0-.54-.54A1 1 0 0 0 21 2h-4a1 1 0 0 0 0 2h1.59l-5.8 5.79a1 1 0 0 0 0 1.42 1 1 0 0 0 1.42 0L20 5.41V7a1 1 0 0 0 2 0V3a1 1 0 0 0-.08-.38Z" class="astro-qteoq5nn"></path> </symbol> <symbol id="starlight-image-zoom-icon-unzoom" viewBox="0 0 24 24" class="astro-qteoq5nn"> <path d="M21.71 2.29a1 1 0 0 0-1.42 0l-5.79 5.8V6.5a1 1 0 0 0-2 0v4a1 1 0 0 0 .08.38 1 1 0 0 0 .54.54 1 1 0 0 0 .38.08h4a1 1 0 0 0 0-2h-1.59l5.8-5.79a1 1 0 0 0 0-1.42ZM10.88 12.58a1 1 0 0 0-.38-.08h-4a1 1 0 0 0 0 2h1.59l-5.8 5.79a1 1 0 0 0 0 1.42 1 1 0 0 0 1.42 0l5.79-5.8v1.59a1 1 0 0 0 2 0v-4a1 1 0 0 0-.08-.38 1 1 0 0 0-.54-.54Z" class="astro-qteoq5nn"></path> </symbol> </svg> </starlight-image-zoom> <script type="module" src="/_astro/ImageZoom.astro_astro_type_script_index_0_lang.J1tlcSSG.js"></script> <div class="sl-markdown-content"> <!-- Auto-generated by scripts/sync-codeceptjs-docs.mjs from codeceptjs/CodeceptJS@4.x. Do not edit. -->
<p>Locators tell CodeceptJS which element on the page a step acts on. Every action that touches the DOM — <code dir="auto">click</code>, <code dir="auto">fillField</code>, <code dir="auto">see</code>, <code dir="auto">waitForVisible</code> — accepts one.</p>
<p>CodeceptJS accepts locators in two forms:</p>
<ul>
<li><strong>Strict locator</strong> — an object whose single key names the strategy: <code dir="auto">{ css: 'button' }</code>, <code dir="auto">{ role: 'button', name: 'Submit' }</code>, <code dir="auto">{ xpath: '//td[1]' }</code>, <code dir="auto">{ id: 'email' }</code>. The strategy is explicit, so the helper runs exactly one query.</li>
<li><strong>Semantic locator</strong> — a plain string like <code dir="auto">'Sign In'</code> or <code dir="auto">'Email'</code>. CodeceptJS matches it against labels, button text, placeholders, and <code dir="auto">aria-*</code> attributes the way a user would read the page.</li>
</ul>
<p>Both are idiomatic. The strongest pattern in CodeceptJS — readable, resilient, and unambiguous — is a <strong>semantic locator scoped to a context</strong>:</p>
<div class="expressive-code"><link rel="stylesheet" href="/_astro/ec.y86o5.css"><script type="module" src="/_astro/ec.p1z7b.js"></script><figure class="frame not-content"><figcaption class="header"></figcaption><pre data-language="js"><code><div class="ec-line"><div class="code"><span style="--0:#db2777;--0fw:bold;--1:#db2777;--1fw:bold">I</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">click</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'Save'</span><span style="--0:#9CA3AF;--1:#4B5563">,</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'.header'</span><span style="--0:#9CA3AF;--1:#4B5563">)</span></div></div><div class="ec-line"><div class="code"><span style="--0:#db2777;--0fw:bold;--1:#db2777;--1fw:bold">I</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">fillField</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'Search'</span><span style="--0:#9CA3AF;--1:#4B5563">,</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'Item 1'</span><span style="--0:#9CA3AF;--1:#4B5563">,</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'.topbar'</span><span style="--0:#9CA3AF;--1:#4B5563">)</span></div></div><div class="ec-line"><div class="code"><span style="--0:#db2777;--0fw:bold;--1:#db2777;--1fw:bold">I</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">click</span><span style="--0:#9CA3AF;--1:#4B5563">({</span><span style="--0:#C9D1D9;--1:#1F2937"> role</span><span style="--0:#9CA3AF;--1:#4B5563">:</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'button'</span><span style="--0:#9CA3AF;--1:#4B5563">,</span><span style="--0:#C9D1D9;--1:#1F2937"> name</span><span style="--0:#9CA3AF;--1:#4B5563">:</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'Submit'</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#9CA3AF;--1:#4B5563">},</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'#login-form'</span><span style="--0:#9CA3AF;--1:#4B5563">)</span></div></div></code></pre><div class="copy"><button title="Copy to clipboard" data-copied="Copied!" data-code="I.click('Save', '.header')I.fillField('Search', 'Item 1', '.topbar')I.click({ role: 'button', name: 'Submit' }, '#login-form')"><div></div></button></div></figure></div>
<p>The context narrows the search to one region of the page, and the semantic string says what the user actually clicks. This is <strong>more precise than ARIA or CSS alone</strong> because it combines structural scope with human-readable intent.</p>
<p>Supported strategies: <code dir="auto">css</code>, <code dir="auto">xpath</code>, <code dir="auto">id</code>, <code dir="auto">name</code>, <code dir="auto">role</code>, <code dir="auto">frame</code>, <code dir="auto">shadow</code>, <code dir="auto">pw</code>. Shadow DOM has its own page — see <a href="/shadow">Shadow DOM</a>. Playwright-specific locators use the <code dir="auto">pw</code> strategy: <code dir="auto">{ pw: '[data-testid="save"]' }</code>. To test components by their accessible role, use <a href="#aria-locators">ARIA locators</a>.</p>
<figure class="injected-figure"><starlight-image-zoom-zoomable><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1700 340" class="injected-fig-locators" role="img" aria-label="CodeceptJS locator strategies in preference order: Semantic + Context, ARIA Role, CSS, and XPath as a last resort."><title>CodeceptJS locator strategies in preference order: Semantic + Context, ARIA Role, CSS, and XPath as a last resort.</title>
<defs>
<filter id="ambient" x="-10%" y="-10%" width="120%" height="120%">
<feDropShadow dx="0" dy="4" stdDeviation="9" flood-color="#1a1d28" flood-opacity="0.12"></feDropShadow>
</filter>
<marker id="arrowGold" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto" visibility="visible">
<path d="M0,1 L9,5 L0,9 z" fill="#C88800" visibility="visible"></path>
</marker>
</defs>
<style>@import url('https://fonts.googleapis.com/css2?family=Bricolage+Grotesque:opsz,wght@12..96,400..800&family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@500;600;700&display=swap');
.injected-fig-locators .title { font-family: 'Bricolage Grotesque', sans-serif; font-weight: 700; font-size: 28px; letter-spacing: -0.025em; font-feature-settings: 'ss01','ss02'; }
.injected-fig-locators .body { font-family: 'Inter', sans-serif; font-weight: 500; font-size: 14px; letter-spacing: -0.005em; }
.injected-fig-locators .mono { font-family: 'JetBrains Mono', monospace; font-weight: 600; font-size: 13px; }</style>
<!-- Card 1 — Semantic + Context -->
<g transform="translate(110, 50)">
<path d="M0,0 L320,0 L334,-8 L14,-8 Z" fill="#F1F5F9"></path>
<path d="M320,0 L334,-8 L334,252 L320,260 Z" fill="#E2E8F0"></path>
<rect width="320" height="260" fill="#FFFFFF" filter="url(#ambient)"></rect>
<text x="24" y="70" class="title" fill="#111827">Semantic + Context</text>
<text x="24" y="130" class="mono" fill="#C88800">I.click('Save', '.header')</text>
<text x="24" y="200" class="body" fill="#4B5563">Plain string scoped to a region —</text>
<text x="24" y="222" class="body" fill="#4B5563">reads like prose.</text>
</g>
<!-- Card 2 — ARIA Role -->
<g transform="translate(500, 50)">
<path d="M0,0 L320,0 L334,-8 L14,-8 Z" fill="#F1F5F9"></path>
<path d="M320,0 L334,-8 L334,252 L320,260 Z" fill="#E2E8F0"></path>
<rect width="320" height="260" fill="#FFFFFF" filter="url(#ambient)"></rect>
<text x="24" y="70" class="title" fill="#111827">ARIA Role</text>
<text x="24" y="130" class="mono" fill="#C88800">I.click({ role: 'button',</text>
<text x="104" y="152" class="mono" fill="#C88800">name: 'Save' })</text>
<text x="24" y="200" class="body" fill="#4B5563">Role + accessible name —</text>
<text x="24" y="222" class="body" fill="#4B5563">pair with context too.</text>
</g>
<!-- Card 3 — CSS -->
<g transform="translate(890, 50)">
<path d="M0,0 L320,0 L334,-8 L14,-8 Z" fill="#F1F5F9"></path>
<path d="M320,0 L334,-8 L334,252 L320,260 Z" fill="#E2E8F0"></path>
<rect width="320" height="260" fill="#FFFFFF" filter="url(#ambient)"></rect>
<text x="24" y="70" class="title" fill="#111827">CSS</text>
<text x="24" y="130" class="mono" fill="#C88800">I.click('.btn-save')</text>
<text x="24" y="200" class="body" fill="#4B5563">Fast and familiar — pair with</text>
<text x="24" y="222" class="body" fill="#4B5563">data-testid, not style classes.</text>
</g>
<!-- Card 4 — XPath -->
<g transform="translate(1280, 50)">
<path d="M0,0 L320,0 L334,-8 L14,-8 Z" fill="#F1F5F9"></path>
<path d="M320,0 L334,-8 L334,252 L320,260 Z" fill="#E2E8F0"></path>
<rect width="320" height="260" fill="#FFFFFF" filter="url(#ambient)"></rect>
<text x="24" y="70" class="title" fill="#111827">XPath</text>
<text x="24" y="130" class="mono" fill="#C88800">I.click("//tr[td='Acme']")</text>
<text x="24" y="200" class="body" fill="#4B5563">Text match and axis navigation —</text>
<text x="24" y="222" class="body" fill="#4B5563">verbose, but reaches anywhere.</text>
</g>
<!-- Preference arrows between cards -->
<g stroke="#C88800" stroke-width="2.2" fill="none" marker-end="url(#arrowGold)" stroke-linecap="round">
<line x1="454" y1="180" x2="488" y2="180"></line>
<line x1="844" y1="180" x2="878" y2="180"></line>
<line x1="1234" y1="180" x2="1268" y2="180"></line>
</g>
</svg><button aria-label="Zoom image: CodeceptJS locator strategies in preference order: Semantic + Context, ARIA Role, CSS, and XPath as a last resort." class="starlight-image-zoom-control"><svg aria-hidden="true" fill="currentColor" viewBox="0 0 24 24"><use href="#starlight-image-zoom-icon-zoom"></use></svg></button></starlight-image-zoom-zoomable></figure><div class="sl-heading-wrapper level-h2"><h2 id="locator-types-at-a-glance">Locator types at a glance</h2><a class="sl-anchor-link" href="#locator-types-at-a-glance"><span aria-hidden="true" class="sl-anchor-icon"><svg width="16" height="16" viewBox="0 0 24 24"><path fill="currentcolor" d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 0 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 1 0-1.42-1.42Zm8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 0 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 1 0 1.42 1.42l3.88-3.89a4.49 4.49 0 0 0 0-6.33ZM8.83 15.17a1 1 0 0 0 1.1.22 1 1 0 0 0 .32-.22l4.92-4.92a1 1 0 0 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42Z"></path></svg></span><span class="sr-only">Section titled “Locator types at a glance”</span></a></div>
<table><thead><tr><th>Type</th><th>Example</th><th>Strengths</th><th>Weaknesses</th><th>Reach for it when</th></tr></thead><tbody><tr><td><strong>Semantic + context</strong></td><td><code dir="auto">I.click('Save', '.header')</code></td><td>Reads like prose; survives CSS and ARIA refactors; the context disambiguates duplicates</td><td>Needs a stable region to scope into</td><td><strong>Default for stable suites.</strong> Anywhere a label, button text, or placeholder identifies the element</td></tr><tr><td><strong>ARIA role</strong></td><td><code dir="auto">{ role: 'button', name: 'Save' }</code></td><td>Survives markup changes; matches how users and screen readers identify elements; exposes accessibility gaps</td><td>Needs correct ARIA roles and accessible names; slower than CSS</td><td>The app follows accessibility guidelines and you want tests that mirror user intent</td></tr><tr><td><strong>Semantic (no context)</strong></td><td><code dir="auto">'Sign In'</code>, <code dir="auto">'Email'</code></td><td>No locator to maintain; reads like prose</td><td>Ambiguous when the same label appears more than once on the page</td><td>A label is unique on the page, or you are prototyping</td></tr><tr><td><strong>CSS</strong></td><td><code dir="auto">{ css: '.btn-save' }</code> or <code dir="auto">.btn-save</code></td><td>Fast; familiar to every web developer; composes with class, attribute, and pseudo-selectors</td><td>Couples tests to styling; breaks on CSS refactors; cannot match by visible text</td><td>A stable class, id, or data-attribute exists on the target</td></tr><tr><td><strong>XPath</strong></td><td><code dir="auto">{ xpath: '//table//tr[2]/td[last()]' }</code></td><td>Walks the tree in any direction (<code dir="auto">ancestor</code>, <code dir="auto">following-sibling</code>); matches visible text</td><td>Verbose; slow; harder to read than CSS</td><td>You need text matching or axis navigation that CSS cannot express</td></tr><tr><td><strong>ID / name</strong></td><td><code dir="auto">#email</code>, <code dir="auto">{ name: 'user[email]' }</code></td><td>Shortest possible locator; unambiguous</td><td>Requires an <code dir="auto">id</code> or <code dir="auto">name</code> attribute to exist</td><td>Forms and elements with stable ids</td></tr><tr><td><strong>Accessibility id</strong></td><td><code dir="auto">~login-button</code></td><td>Works in both web (<code dir="auto">aria-label</code>) and mobile</td><td>Mobile apps need to expose the id</td><td>Cross-platform web and mobile tests</td></tr><tr><td><strong>Custom (<code dir="auto">$foo</code>)</strong></td><td><code dir="auto">$register_button</code></td><td>Encodes team convention (<code dir="auto">data-qa</code>, <code dir="auto">data-test</code>) in two characters</td><td>Needs the <a href="/plugins#customlocator">customLocator plugin</a></td><td>Your team uses dedicated test attributes</td></tr></tbody></table>
<div class="sl-heading-wrapper level-h2"><h2 id="aria-locators">ARIA locators</h2><a class="sl-anchor-link" href="#aria-locators"><span aria-hidden="true" class="sl-anchor-icon"><svg width="16" height="16" viewBox="0 0 24 24"><path fill="currentcolor" d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 0 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 1 0-1.42-1.42Zm8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 0 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 1 0 1.42 1.42l3.88-3.89a4.49 4.49 0 0 0 0-6.33ZM8.83 15.17a1 1 0 0 0 1.1.22 1 1 0 0 0 .32-.22l4.92-4.92a1 1 0 0 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42Z"></path></svg></span><span class="sr-only">Section titled “ARIA locators”</span></a></div>
<p>ARIA role locators are the modern default. They identify elements the way assistive technology does — by role and accessible name — and they survive layout and class refactors that break CSS.</p>
<div class="expressive-code"><figure class="frame not-content"><figcaption class="header"></figcaption><pre data-language="js"><code><div class="ec-line"><div class="code"><span style="--0:#db2777;--0fw:bold;--1:#db2777;--1fw:bold">I</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">click</span><span style="--0:#9CA3AF;--1:#4B5563">({</span><span style="--0:#C9D1D9;--1:#1F2937"> role</span><span style="--0:#9CA3AF;--1:#4B5563">:</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'button'</span><span style="--0:#9CA3AF;--1:#4B5563">,</span><span style="--0:#C9D1D9;--1:#1F2937"> name</span><span style="--0:#9CA3AF;--1:#4B5563">:</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'Login'</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#9CA3AF;--1:#4B5563">})</span></div></div><div class="ec-line"><div class="code"><span style="--0:#db2777;--0fw:bold;--1:#db2777;--1fw:bold">I</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">fillField</span><span style="--0:#9CA3AF;--1:#4B5563">({</span><span style="--0:#C9D1D9;--1:#1F2937"> role</span><span style="--0:#9CA3AF;--1:#4B5563">:</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'textbox'</span><span style="--0:#9CA3AF;--1:#4B5563">,</span><span style="--0:#C9D1D9;--1:#1F2937"> name</span><span style="--0:#9CA3AF;--1:#4B5563">:</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'Email Address'</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#9CA3AF;--1:#4B5563">},</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'user@test.com'</span><span style="--0:#9CA3AF;--1:#4B5563">)</span></div></div><div class="ec-line"><div class="code"><span style="--0:#db2777;--0fw:bold;--1:#db2777;--1fw:bold">I</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">seeElement</span><span style="--0:#9CA3AF;--1:#4B5563">({</span><span style="--0:#C9D1D9;--1:#1F2937"> role</span><span style="--0:#9CA3AF;--1:#4B5563">:</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'heading'</span><span style="--0:#9CA3AF;--1:#4B5563">,</span><span style="--0:#C9D1D9;--1:#1F2937"> name</span><span style="--0:#9CA3AF;--1:#4B5563">:</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'Dashboard'</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#9CA3AF;--1:#4B5563">})</span></div></div><div class="ec-line"><div class="code"><span style="--0:#db2777;--0fw:bold;--1:#db2777;--1fw:bold">I</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">selectOption</span><span style="--0:#9CA3AF;--1:#4B5563">({</span><span style="--0:#C9D1D9;--1:#1F2937"> role</span><span style="--0:#9CA3AF;--1:#4B5563">:</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'combobox'</span><span style="--0:#9CA3AF;--1:#4B5563">,</span><span style="--0:#C9D1D9;--1:#1F2937"> name</span><span style="--0:#9CA3AF;--1:#4B5563">:</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'Country'</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#9CA3AF;--1:#4B5563">},</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'Ukraine'</span><span style="--0:#9CA3AF;--1:#4B5563">)</span></div></div></code></pre><div class="copy"><button title="Copy to clipboard" data-copied="Copied!" data-code="I.click({ role: 'button', name: 'Login' })I.fillField({ role: 'textbox', name: 'Email Address' }, 'user@test.com')I.seeElement({ role: 'heading', name: 'Dashboard' })I.selectOption({ role: 'combobox', name: 'Country' }, 'Ukraine')"><div></div></button></div></figure></div>
<p>The <code dir="auto">name</code> matches the element’s accessible name — its visible text, <code dir="auto">aria-label</code>, or the text referenced by <code dir="auto">aria-labelledby</code>.</p>
<p>Common roles: <code dir="auto">button</code>, <code dir="auto">link</code>, <code dir="auto">textbox</code>, <code dir="auto">checkbox</code>, <code dir="auto">radio</code>, <code dir="auto">combobox</code>, <code dir="auto">listbox</code>, <code dir="auto">menuitem</code>, <code dir="auto">tab</code>, <code dir="auto">dialog</code>, <code dir="auto">alert</code>, <code dir="auto">heading</code>, <code dir="auto">navigation</code>, <code dir="auto">banner</code>, <code dir="auto">main</code>.</p>
<p><strong>Prefer ARIA when:</strong></p>
<ul>
<li>The element has a visible label or accessible text.</li>
<li>You want the test to double as an accessibility smoke check.</li>
<li>The UI is rewritten often and class names drift.</li>
</ul>
<p><strong>Reach for something else when:</strong></p>
<ul>
<li>The element has no accessible name (purely decorative icons, unlabeled inputs).</li>
<li>The page predates ARIA annotation and you cannot change it.</li>
<li>A hot loop runs thousands of locator calls and needs the speed of a direct CSS query.</li>
</ul>
<blockquote>
<p>ARIA locators rely on the accessibility tree of the underlying helper. Playwright and modern WebDriver support them natively.</p>
</blockquote>
<div class="sl-heading-wrapper level-h2"><h2 id="css-selectors">CSS selectors</h2><a class="sl-anchor-link" href="#css-selectors"><span aria-hidden="true" class="sl-anchor-icon"><svg width="16" height="16" viewBox="0 0 24 24"><path fill="currentcolor" d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 0 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 1 0-1.42-1.42Zm8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 0 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 1 0 1.42 1.42l3.88-3.89a4.49 4.49 0 0 0 0-6.33ZM8.83 15.17a1 1 0 0 0 1.1.22 1 1 0 0 0 .32-.22l4.92-4.92a1 1 0 0 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42Z"></path></svg></span><span class="sr-only">Section titled “CSS selectors”</span></a></div>
<p>CSS is the fastest locator type and most frontend developers read it fluently.</p>
<div class="expressive-code"><figure class="frame not-content"><figcaption class="header"></figcaption><pre data-language="js"><code><div class="ec-line"><div class="code"><span style="--0:#db2777;--0fw:bold;--1:#db2777;--1fw:bold">I</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">seeElement</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'.user-profile .avatar'</span><span style="--0:#9CA3AF;--1:#4B5563">)</span></div></div><div class="ec-line"><div class="code"><span style="--0:#db2777;--0fw:bold;--1:#db2777;--1fw:bold">I</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">click</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'#checkout-btn'</span><span style="--0:#9CA3AF;--1:#4B5563">)</span></div></div><div class="ec-line"><div class="code"><span style="--0:#db2777;--0fw:bold;--1:#db2777;--1fw:bold">I</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">fillField</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'input[name="email"]'</span><span style="--0:#9CA3AF;--1:#4B5563">,</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'user@test.com'</span><span style="--0:#9CA3AF;--1:#4B5563">)</span></div></div></code></pre><div class="copy"><button title="Copy to clipboard" data-copied="Copied!" data-code="I.seeElement('.user-profile .avatar')I.click('#checkout-btn')I.fillField('input[name="email"]', 'user@test.com')"><div></div></button></div></figure></div>
<p>Pair CSS with stable test attributes — <code dir="auto">data-testid</code>, <code dir="auto">data-qa</code> — rather than style classes. Style classes drift with every design update; test attributes exist to be locators.</p>
<div class="expressive-code"><figure class="frame not-content"><figcaption class="header"></figcaption><pre data-language="js"><code><div class="ec-line"><div class="code"><span style="--0:#db2777;--0fw:bold;--1:#db2777;--1fw:bold">I</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">click</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'[data-testid="submit-order"]'</span><span style="--0:#9CA3AF;--1:#4B5563">)</span></div></div></code></pre><div class="copy"><button title="Copy to clipboard" data-copied="Copied!" data-code="I.click('[data-testid="submit-order"]')"><div></div></button></div></figure></div>
<p>Tie locators to structure, not to presentation: <code dir="auto">.btn-primary</code> survives a redesign; <code dir="auto">.bg-green-500</code> does not.</p>
<p>Force CSS when a bare string would trigger fuzzy matching:</p>
<div class="expressive-code"><figure class="frame not-content"><figcaption class="header"></figcaption><pre data-language="js"><code><div class="ec-line"><div class="code"><span style="--0:#db2777;--0fw:bold;--1:#db2777;--1fw:bold">I</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">fillField</span><span style="--0:#9CA3AF;--1:#4B5563">({</span><span style="--0:#C9D1D9;--1:#1F2937"> css</span><span style="--0:#9CA3AF;--1:#4B5563">:</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'input[type=password]'</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#9CA3AF;--1:#4B5563">},</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'123456'</span><span style="--0:#9CA3AF;--1:#4B5563">)</span></div></div></code></pre><div class="copy"><button title="Copy to clipboard" data-copied="Copied!" data-code="I.fillField({ css: 'input[type=password]' }, '123456')"><div></div></button></div></figure></div>
<div class="sl-heading-wrapper level-h2"><h2 id="xpath">XPath</h2><a class="sl-anchor-link" href="#xpath"><span aria-hidden="true" class="sl-anchor-icon"><svg width="16" height="16" viewBox="0 0 24 24"><path fill="currentcolor" d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 0 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 1 0-1.42-1.42Zm8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 0 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 1 0 1.42 1.42l3.88-3.89a4.49 4.49 0 0 0 0-6.33ZM8.83 15.17a1 1 0 0 0 1.1.22 1 1 0 0 0 .32-.22l4.92-4.92a1 1 0 0 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42Z"></path></svg></span><span class="sr-only">Section titled “XPath”</span></a></div>
<p>XPath reaches where CSS cannot. Use it for:</p>
<ul>
<li>Text matching: <code dir="auto">//button[contains(., 'Save changes')]</code></li>
<li>Axis navigation: <code dir="auto">ancestor</code>, <code dir="auto">following-sibling</code>, <code dir="auto">preceding-sibling</code></li>
<li>Positional selection deep in a table or list</li>
</ul>
<div class="expressive-code"><figure class="frame not-content"><figcaption class="header"></figcaption><pre data-language="js"><code><div class="ec-line"><div class="code"><span style="--0:#db2777;--0fw:bold;--1:#db2777;--1fw:bold">I</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">click</span><span style="--0:#9CA3AF;--1:#4B5563">({</span><span style="--0:#C9D1D9;--1:#1F2937"> xpath</span><span style="--0:#9CA3AF;--1:#4B5563">:</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">"//tr[td[text()='Acme Corp']]//button[contains(., 'Edit')]"</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#9CA3AF;--1:#4B5563">})</span></div></div></code></pre><div class="copy"><button title="Copy to clipboard" data-copied="Copied!" data-code="I.click({ xpath: "//tr[td[text()='Acme Corp']]//button[contains(., 'Edit')]" })"><div></div></button></div></figure></div>
<p>Long XPath expressions become unreadable fast. The <a href="#combining-locators"><code dir="auto">locate()</code> builder</a> produces the same XPath with a fluent syntax — prefer it for anything beyond two conditions.</p>
<div class="sl-heading-wrapper level-h2"><h2 id="semantic-locators">Semantic locators</h2><a class="sl-anchor-link" href="#semantic-locators"><span aria-hidden="true" class="sl-anchor-icon"><svg width="16" height="16" viewBox="0 0 24 24"><path fill="currentcolor" d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 0 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 1 0-1.42-1.42Zm8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 0 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 1 0 1.42 1.42l3.88-3.89a4.49 4.49 0 0 0 0-6.33ZM8.83 15.17a1 1 0 0 0 1.1.22 1 1 0 0 0 .32-.22l4.92-4.92a1 1 0 0 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42Z"></path></svg></span><span class="sr-only">Section titled “Semantic locators”</span></a></div>
<p>A plain string is a semantic locator. CodeceptJS reads it the way a user would: as a button label, a link, a field name, a placeholder, or an <code dir="auto">aria-label</code>.</p>
<div class="expressive-code"><figure class="frame not-content"><figcaption class="header"></figcaption><pre data-language="js"><code><div class="ec-line"><div class="code"><span style="--0:#db2777;--0fw:bold;--1:#db2777;--1fw:bold">I</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">click</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'Sign In'</span><span style="--0:#9CA3AF;--1:#4B5563">)</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#8B949E;--0fs:italic;--1:#636976;--1fs:italic">// matches <a>, <button>, or <input type="submit"></span></div></div><div class="ec-line"><div class="code"><span style="--0:#db2777;--0fw:bold;--1:#db2777;--1fw:bold">I</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">fillField</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'Email'</span><span style="--0:#9CA3AF;--1:#4B5563">,</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'u@t.com'</span><span style="--0:#9CA3AF;--1:#4B5563">)</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#8B949E;--0fs:italic;--1:#636976;--1fs:italic">// matches label, placeholder, name, or aria-label</span></div></div><div class="ec-line"><div class="code"><span style="--0:#db2777;--0fw:bold;--1:#db2777;--1fw:bold">I</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">checkOption</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'</span><span style="--0:#db2777;--0fw:bold;--1:#db2777;--1fw:bold">I</span><span style="--0:#7DD3FC;--1:#0369A1"> accept the terms'</span><span style="--0:#9CA3AF;--1:#4B5563">)</span></div></div></code></pre><div class="copy"><button title="Copy to clipboard" data-copied="Copied!" data-code="I.click('Sign In') // matches <a>, <button>, or <input type="submit">I.fillField('Email', 'u@t.com') // matches label, placeholder, name, or aria-labelI.checkOption('I accept the terms')"><div></div></button></div></figure></div>
<div class="sl-heading-wrapper level-h3"><h3 id="pair-semantic-locators-with-a-context">Pair semantic locators with a context</h3><a class="sl-anchor-link" href="#pair-semantic-locators-with-a-context"><span aria-hidden="true" class="sl-anchor-icon"><svg width="16" height="16" viewBox="0 0 24 24"><path fill="currentcolor" d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 0 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 1 0-1.42-1.42Zm8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 0 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 1 0 1.42 1.42l3.88-3.89a4.49 4.49 0 0 0 0-6.33ZM8.83 15.17a1 1 0 0 0 1.1.22 1 1 0 0 0 .32-.22l4.92-4.92a1 1 0 0 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42Z"></path></svg></span><span class="sr-only">Section titled “Pair semantic locators with a context”</span></a></div>
<p>The same label often appears in more than one place — a “Save” button in the toolbar, the modal, and the inline editor. <strong>Pass a context as the last argument</strong> and the lookup is unambiguous, fast, and still readable:</p>
<div class="expressive-code"><figure class="frame not-content"><figcaption class="header"></figcaption><pre data-language="js"><code><div class="ec-line"><div class="code"><span style="--0:#db2777;--0fw:bold;--1:#db2777;--1fw:bold">I</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">click</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'Save'</span><span style="--0:#9CA3AF;--1:#4B5563">,</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'.toolbar'</span><span style="--0:#9CA3AF;--1:#4B5563">)</span></div></div><div class="ec-line"><div class="code"><span style="--0:#db2777;--0fw:bold;--1:#db2777;--1fw:bold">I</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">fillField</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'Search'</span><span style="--0:#9CA3AF;--1:#4B5563">,</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'Item 1'</span><span style="--0:#9CA3AF;--1:#4B5563">,</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'.topbar'</span><span style="--0:#9CA3AF;--1:#4B5563">)</span></div></div><div class="ec-line"><div class="code"><span style="--0:#db2777;--0fw:bold;--1:#db2777;--1fw:bold">I</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">click</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'Edit'</span><span style="--0:#9CA3AF;--1:#4B5563">,</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#9CA3AF;--1:#4B5563">{</span><span style="--0:#C9D1D9;--1:#1F2937"> css</span><span style="--0:#9CA3AF;--1:#4B5563">:</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'tr.acme'</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#9CA3AF;--1:#4B5563">})</span></div></div><div class="ec-line"><div class="code"><span style="--0:#db2777;--0fw:bold;--1:#db2777;--1fw:bold">I</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">see</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'Welcome'</span><span style="--0:#9CA3AF;--1:#4B5563">,</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'.header'</span><span style="--0:#9CA3AF;--1:#4B5563">)</span></div></div></code></pre><div class="copy"><button title="Copy to clipboard" data-copied="Copied!" data-code="I.click('Save', '.toolbar')I.fillField('Search', 'Item 1', '.topbar')I.click('Edit', { css: 'tr.acme' })I.see('Welcome', '.header')"><div></div></button></div></figure></div>
<p>The context can be any locator (CSS, XPath, ARIA, <a href="#locate-builder-compose-css-and-xpath"><code dir="auto">locate()</code> chain</a>). The action runs only inside it, so duplicate labels elsewhere on the page no longer cause flaky matches. This is the recommended default for stable scenarios — production-grade, not a prototyping shortcut.</p>
<div class="sl-heading-wrapper level-h3"><h3 id="how-matching-works">How matching works</h3><a class="sl-anchor-link" href="#how-matching-works"><span aria-hidden="true" class="sl-anchor-icon"><svg width="16" height="16" viewBox="0 0 24 24"><path fill="currentcolor" d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 0 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 1 0-1.42-1.42Zm8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 0 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 1 0 1.42 1.42l3.88-3.89a4.49 4.49 0 0 0 0-6.33ZM8.83 15.17a1 1 0 0 0 1.1.22 1 1 0 0 0 .32-.22l4.92-4.92a1 1 0 0 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42Z"></path></svg></span><span class="sr-only">Section titled “How matching works”</span></a></div>
<p>For <code dir="auto">fillField</code> and similar actions, CodeceptJS resolves the locator in this order:</p>
<ol>
<li>ARIA role locator (<code dir="auto">{ role: 'textbox', name: 'Email' }</code>) — resolved through the accessibility tree.</li>
<li>Strict locator (<code dir="auto">{ css: ... }</code>, <code dir="auto">{ xpath: ... }</code>, <code dir="auto">{ id: ... }</code>, …) — run directly.</li>
<li>Plain string treated as semantic, tried in order:
<ol>
<li>Field whose <code dir="auto">name</code>, <code dir="auto">id</code>+<code dir="auto">label[for]</code>, or <code dir="auto">placeholder</code> <strong>equals</strong> the string — or a <code dir="auto"><label></code> with that exact text wrapping an input.</li>
<li>The same match with <strong>contains</strong>, extended to <code dir="auto">aria-label</code>, <code dir="auto">aria-labelledby</code>, and <code dir="auto">title</code>.</li>
<li>An input with that <code dir="auto">name</code> attribute.</li>
<li>The string as a CSS selector.</li>
</ol>
</li>
<li>Nothing matched? Throw <code dir="auto">ElementNotFound</code>.</li>
</ol>
<p>A semantic lookup runs several queries, but each query is cheap and the second argument (context) prunes the search space dramatically.</p>
<div class="sl-heading-wrapper level-h2"><h2 id="id-locators">ID locators</h2><a class="sl-anchor-link" href="#id-locators"><span aria-hidden="true" class="sl-anchor-icon"><svg width="16" height="16" viewBox="0 0 24 24"><path fill="currentcolor" d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 0 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 1 0-1.42-1.42Zm8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 0 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 1 0 1.42 1.42l3.88-3.89a4.49 4.49 0 0 0 0-6.33ZM8.83 15.17a1 1 0 0 0 1.1.22 1 1 0 0 0 .32-.22l4.92-4.92a1 1 0 0 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42Z"></path></svg></span><span class="sr-only">Section titled “ID locators”</span></a></div>
<p>Three short forms cover id-based matching:</p>
<ul>
<li><code dir="auto">#user</code> or <code dir="auto">{ id: 'user' }</code> — element with <code dir="auto">id="user"</code></li>
<li><code dir="auto">{ name: 'email' }</code> — form field with <code dir="auto">name="email"</code></li>
<li><code dir="auto">~login-button</code> — accessibility id (mobile) or <code dir="auto">aria-label</code> (web)</li>
</ul>
<div class="expressive-code"><figure class="frame not-content"><figcaption class="header"></figcaption><pre data-language="js"><code><div class="ec-line"><div class="code"><span style="--0:#db2777;--0fw:bold;--1:#db2777;--1fw:bold">I</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">fillField</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'#email'</span><span style="--0:#9CA3AF;--1:#4B5563">,</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'user@test.com'</span><span style="--0:#9CA3AF;--1:#4B5563">)</span></div></div><div class="ec-line"><div class="code"><span style="--0:#db2777;--0fw:bold;--1:#db2777;--1fw:bold">I</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">seeElement</span><span style="--0:#9CA3AF;--1:#4B5563">({</span><span style="--0:#C9D1D9;--1:#1F2937"> id</span><span style="--0:#9CA3AF;--1:#4B5563">:</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'confirmation'</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#9CA3AF;--1:#4B5563">})</span></div></div><div class="ec-line"><div class="code"><span style="--0:#db2777;--0fw:bold;--1:#db2777;--1fw:bold">I</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">tap</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'~submit'</span><span style="--0:#9CA3AF;--1:#4B5563">)</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#8B949E;--0fs:italic;--1:#636976;--1fs:italic">// mobile</span></div></div></code></pre><div class="copy"><button title="Copy to clipboard" data-copied="Copied!" data-code="I.fillField('#email', 'user@test.com')I.seeElement({ id: 'confirmation' })I.tap('~submit') // mobile"><div></div></button></div></figure></div>
<div class="sl-heading-wrapper level-h2"><h2 id="picking-a-specific-element">Picking a specific element</h2><a class="sl-anchor-link" href="#picking-a-specific-element"><span aria-hidden="true" class="sl-anchor-icon"><svg width="16" height="16" viewBox="0 0 24 24"><path fill="currentcolor" d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 0 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 1 0-1.42-1.42Zm8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 0 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 1 0 1.42 1.42l3.88-3.89a4.49 4.49 0 0 0 0-6.33ZM8.83 15.17a1 1 0 0 0 1.1.22 1 1 0 0 0 .32-.22l4.92-4.92a1 1 0 0 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42Z"></path></svg></span><span class="sr-only">Section titled “Picking a specific element”</span></a></div>
<p>When a locator matches several elements on the page, CodeceptJS acts on the first one by default. To target a different match, pass <code dir="auto">elementIndex</code> via <code dir="auto">step.opts()</code>:</p>
<div class="expressive-code"><figure class="frame not-content"><figcaption class="header"></figcaption><pre data-language="js"><code><div class="ec-line"><div class="code"><span style="--0:#D8B4FE;--1:#7C3AED">import</span><span style="--0:#C9D1D9;--1:#1F2937"> step </span><span style="--0:#D8B4FE;--1:#7C3AED">from</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'codeceptjs/steps'</span></div></div><div class="ec-line"><div class="code">
</div></div><div class="ec-line"><div class="code"><span style="--0:#db2777;--0fw:bold;--1:#db2777;--1fw:bold">I</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">click</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'a'</span><span style="--0:#9CA3AF;--1:#4B5563">,</span><span style="--0:#C9D1D9;--1:#1F2937"> step</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">opts</span><span style="--0:#9CA3AF;--1:#4B5563">({</span><span style="--0:#C9D1D9;--1:#1F2937"> elementIndex</span><span style="--0:#9CA3AF;--1:#4B5563">:</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#FBBF24;--1:#A94E08">2</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#9CA3AF;--1:#4B5563">}))</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#8B949E;--0fs:italic;--1:#636976;--1fs:italic">// the 2nd link</span></div></div><div class="ec-line"><div class="code"><span style="--0:#db2777;--0fw:bold;--1:#db2777;--1fw:bold">I</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">click</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'a'</span><span style="--0:#9CA3AF;--1:#4B5563">,</span><span style="--0:#C9D1D9;--1:#1F2937"> step</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">opts</span><span style="--0:#9CA3AF;--1:#4B5563">({</span><span style="--0:#C9D1D9;--1:#1F2937"> elementIndex</span><span style="--0:#9CA3AF;--1:#4B5563">:</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'last'</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#9CA3AF;--1:#4B5563">}))</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#8B949E;--0fs:italic;--1:#636976;--1fs:italic">// the last link</span></div></div><div class="ec-line"><div class="code"><span style="--0:#db2777;--0fw:bold;--1:#db2777;--1fw:bold">I</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">fillField</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'.email-input'</span><span style="--0:#9CA3AF;--1:#4B5563">,</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'u@t.com'</span><span style="--0:#9CA3AF;--1:#4B5563">,</span><span style="--0:#C9D1D9;--1:#1F2937"> step</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">opts</span><span style="--0:#9CA3AF;--1:#4B5563">({</span><span style="--0:#C9D1D9;--1:#1F2937"> elementIndex</span><span style="--0:#9CA3AF;--1:#4B5563">:</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#9CA3AF;--1:#4B5563">-</span><span style="--0:#FBBF24;--1:#A94E08">1</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#9CA3AF;--1:#4B5563">}))</span></div></div></code></pre><div class="copy"><button title="Copy to clipboard" data-copied="Copied!" data-code="import step from 'codeceptjs/steps'I.click('a', step.opts({ elementIndex: 2 })) // the 2nd linkI.click('a', step.opts({ elementIndex: 'last' })) // the last linkI.fillField('.email-input', 'u@t.com', step.opts({ elementIndex: -1 }))"><div></div></button></div></figure></div>
<p><code dir="auto">elementIndex</code> accepts positive numbers (1-based), negative numbers (<code dir="auto">-1</code> is last), or the aliases <code dir="auto">'first'</code> and <code dir="auto">'last'</code>. It works with <code dir="auto">click</code>, <code dir="auto">fillField</code>, <code dir="auto">selectOption</code>, <code dir="auto">checkOption</code>, and other single-element actions.</p>
<p>To catch ambiguous locators during development rather than silently using the first match, enable <code dir="auto">strict: true</code> in the helper config, or pass <code dir="auto">step.opts({ exact: true })</code> on a single step:</p>
<div class="expressive-code"><figure class="frame not-content"><figcaption class="header"></figcaption><pre data-language="js"><code><div class="ec-line"><div class="code"><span style="--0:#db2777;--0fw:bold;--1:#db2777;--1fw:bold">I</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">click</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'a'</span><span style="--0:#9CA3AF;--1:#4B5563">,</span><span style="--0:#C9D1D9;--1:#1F2937"> step</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">opts</span><span style="--0:#9CA3AF;--1:#4B5563">({</span><span style="--0:#C9D1D9;--1:#1F2937"> exact</span><span style="--0:#9CA3AF;--1:#4B5563">:</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#D8B4FE;--1:#7C3AED">true</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#9CA3AF;--1:#4B5563">}))</span></div></div><div class="ec-line"><div class="code"><span style="--0:#8B949E;--0fs:italic;--1:#636976;--1fs:italic">// throws MultipleElementsFound if more than one link matches</span></div></div></code></pre><div class="copy"><button title="Copy to clipboard" data-copied="Copied!" data-code="I.click('a', step.opts({ exact: true }))// throws MultipleElementsFound if more than one link matches"><div></div></button></div></figure></div>
<p>See <a href="/element-selection">Element Selection</a> for full details on <code dir="auto">elementIndex</code>, strict mode, and iterating over matches with <code dir="auto">eachElement</code>.</p>
<div class="sl-heading-wrapper level-h2"><h2 id="combining-locators">Combining locators</h2><a class="sl-anchor-link" href="#combining-locators"><span aria-hidden="true" class="sl-anchor-icon"><svg width="16" height="16" viewBox="0 0 24 24"><path fill="currentcolor" d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 0 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 1 0-1.42-1.42Zm8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 0 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 1 0 1.42 1.42l3.88-3.89a4.49 4.49 0 0 0 0-6.33ZM8.83 15.17a1 1 0 0 0 1.1.22 1 1 0 0 0 .32-.22l4.92-4.92a1 1 0 0 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42Z"></path></svg></span><span class="sr-only">Section titled “Combining locators”</span></a></div>
<p>Two mechanisms narrow a locator to a region of the page:</p>
<ul>
<li><strong>Context</strong> — the last argument of most actions. Works with every locator type. In <code dir="auto">I.click('Save', '.toolbar')</code> it is the second argument; in <code dir="auto">I.fillField('Email', 'u@t.com', '#login-form')</code> it is the third.</li>
<li><strong><code dir="auto">locate()</code> builder</strong> — a fluent API that composes CSS and XPath into a single XPath expression. Does <strong>not</strong> accept ARIA role locators.</li>
</ul>
<div class="sl-heading-wrapper level-h3"><h3 id="context-scope-any-locator-to-a-region">Context: scope any locator to a region</h3><a class="sl-anchor-link" href="#context-scope-any-locator-to-a-region"><span aria-hidden="true" class="sl-anchor-icon"><svg width="16" height="16" viewBox="0 0 24 24"><path fill="currentcolor" d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 0 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 1 0-1.42-1.42Zm8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 0 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 1 0 1.42 1.42l3.88-3.89a4.49 4.49 0 0 0 0-6.33ZM8.83 15.17a1 1 0 0 0 1.1.22 1 1 0 0 0 .32-.22l4.92-4.92a1 1 0 0 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42Z"></path></svg></span><span class="sr-only">Section titled “Context: scope any locator to a region”</span></a></div>
<p>Every action that targets an element accepts a context locator as its last argument. The action searches only inside the context. <strong>Use it by default</strong> — even a one-line scenario reads better and survives more refactors when the lookup is scoped:</p>
<div class="expressive-code"><figure class="frame not-content"><figcaption class="header"></figcaption><pre data-language="js"><code><div class="ec-line"><div class="code"><span style="--0:#db2777;--0fw:bold;--1:#db2777;--1fw:bold">I</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">click</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'Login'</span><span style="--0:#9CA3AF;--1:#4B5563">,</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'#login-form'</span><span style="--0:#9CA3AF;--1:#4B5563">)</span></div></div><div class="ec-line"><div class="code"><span style="--0:#db2777;--0fw:bold;--1:#db2777;--1fw:bold">I</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">fillField</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'Email'</span><span style="--0:#9CA3AF;--1:#4B5563">,</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'u@t.com'</span><span style="--0:#9CA3AF;--1:#4B5563">,</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'.modal'</span><span style="--0:#9CA3AF;--1:#4B5563">)</span></div></div><div class="ec-line"><div class="code"><span style="--0:#db2777;--0fw:bold;--1:#db2777;--1fw:bold">I</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">seeElement</span><span style="--0:#9CA3AF;--1:#4B5563">({</span><span style="--0:#C9D1D9;--1:#1F2937"> role</span><span style="--0:#9CA3AF;--1:#4B5563">:</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'button'</span><span style="--0:#9CA3AF;--1:#4B5563">,</span><span style="--0:#C9D1D9;--1:#1F2937"> name</span><span style="--0:#9CA3AF;--1:#4B5563">:</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'Delete'</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#9CA3AF;--1:#4B5563">},</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'.toolbar'</span><span style="--0:#9CA3AF;--1:#4B5563">)</span></div></div></code></pre><div class="copy"><button title="Copy to clipboard" data-copied="Copied!" data-code="I.click('Login', '#login-form')I.fillField('Email', 'u@t.com', '.modal')I.seeElement({ role: 'button', name: 'Delete' }, '.toolbar')"><div></div></button></div></figure></div>
<p>Why scope every action:</p>
<ul>
<li>Duplicate labels stop being a problem (“Save” in the toolbar vs. the modal).</li>
<li>The semantic locator stays semantic — no need to rewrite as <code dir="auto">[data-testid="save-toolbar"]</code> to disambiguate.</li>
<li>The lookup is faster: each strategy queries only inside the context, not the whole DOM.</li>
<li>Tests read like a sentence about the page: “click Save in the header”.</li>
</ul>
<p>The two sides can be any combination — semantic+CSS, ARIA+CSS, semantic+<code dir="auto">locate()</code>. Mix freely.</p>
<p><strong>Example: a dropdown inside a top bar</strong></p>
<p>A complex app often has several menus on screen at once: the top navigation bar, a left sidebar, a right-click context menu. Each may contain a “Settings” item. Without scoping, <code dir="auto">I.click('Settings')</code> is a coin toss.</p>
<div class="expressive-code"><figure class="frame not-content"><figcaption class="header"></figcaption><pre data-language="js"><code><div class="ec-line"><div class="code"><span style="--0:#8B949E;--0fs:italic;--1:#636976;--1fs:italic">// Open the user dropdown in the top bar, then pick Settings</span></div></div><div class="ec-line"><div class="code"><span style="--0:#db2777;--0fw:bold;--1:#db2777;--1fw:bold">I</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">click</span><span style="--0:#9CA3AF;--1:#4B5563">({</span><span style="--0:#C9D1D9;--1:#1F2937"> role</span><span style="--0:#9CA3AF;--1:#4B5563">:</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'button'</span><span style="--0:#9CA3AF;--1:#4B5563">,</span><span style="--0:#C9D1D9;--1:#1F2937"> name</span><span style="--0:#9CA3AF;--1:#4B5563">:</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'User menu'</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#9CA3AF;--1:#4B5563">},</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'.top-bar'</span><span style="--0:#9CA3AF;--1:#4B5563">)</span></div></div><div class="ec-line"><div class="code"><span style="--0:#db2777;--0fw:bold;--1:#db2777;--1fw:bold">I</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">click</span><span style="--0:#9CA3AF;--1:#4B5563">({</span><span style="--0:#C9D1D9;--1:#1F2937"> role</span><span style="--0:#9CA3AF;--1:#4B5563">:</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'menuitem'</span><span style="--0:#9CA3AF;--1:#4B5563">,</span><span style="--0:#C9D1D9;--1:#1F2937"> name</span><span style="--0:#9CA3AF;--1:#4B5563">:</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'Settings'</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#9CA3AF;--1:#4B5563">},</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'.top-bar'</span><span style="--0:#9CA3AF;--1:#4B5563">)</span></div></div><div class="ec-line"><div class="code">
</div></div><div class="ec-line"><div class="code"><span style="--0:#8B949E;--0fs:italic;--1:#636976;--1fs:italic">// The same label in the sidebar goes to a different screen</span></div></div><div class="ec-line"><div class="code"><span style="--0:#db2777;--0fw:bold;--1:#db2777;--1fw:bold">I</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">click</span><span style="--0:#9CA3AF;--1:#4B5563">({</span><span style="--0:#C9D1D9;--1:#1F2937"> role</span><span style="--0:#9CA3AF;--1:#4B5563">:</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'link'</span><span style="--0:#9CA3AF;--1:#4B5563">,</span><span style="--0:#C9D1D9;--1:#1F2937"> name</span><span style="--0:#9CA3AF;--1:#4B5563">:</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'Settings'</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#9CA3AF;--1:#4B5563">},</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'.sidebar'</span><span style="--0:#9CA3AF;--1:#4B5563">)</span></div></div></code></pre><div class="copy"><button title="Copy to clipboard" data-copied="Copied!" data-code="// Open the user dropdown in the top bar, then pick SettingsI.click({ role: 'button', name: 'User menu' }, '.top-bar')I.click({ role: 'menuitem', name: 'Settings' }, '.top-bar')// The same label in the sidebar goes to a different screenI.click({ role: 'link', name: 'Settings' }, '.sidebar')"><div></div></button></div></figure></div>
<p>The context itself accepts any locator type: a bare string, a strict object, or a <a href="#locate-builder-compose-css-and-xpath"><code dir="auto">locate()</code></a> chain.</p>
<div class="expressive-code"><figure class="frame not-content"><figcaption class="header"></figcaption><pre data-language="js"><code><div class="ec-line"><div class="code"><span style="--0:#db2777;--0fw:bold;--1:#db2777;--1fw:bold">I</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">click</span><span style="--0:#9CA3AF;--1:#4B5563">({</span><span style="--0:#C9D1D9;--1:#1F2937"> role</span><span style="--0:#9CA3AF;--1:#4B5563">:</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'menuitem'</span><span style="--0:#9CA3AF;--1:#4B5563">,</span><span style="--0:#C9D1D9;--1:#1F2937"> name</span><span style="--0:#9CA3AF;--1:#4B5563">:</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'Log out'</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#9CA3AF;--1:#4B5563">},</span><span style="--1:#1F2937"><span style="--0:#C9D1D9"> </span><span style="--0:#E5E7EB">locate</span></span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'.dropdown-menu'</span><span style="--0:#9CA3AF;--1:#4B5563">).</span><span style="--0:#E5E7EB;--1:#1F2937">inside</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'header'</span><span style="--0:#9CA3AF;--1:#4B5563">))</span></div></div></code></pre><div class="copy"><button title="Copy to clipboard" data-copied="Copied!" data-code="I.click({ role: 'menuitem', name: 'Log out' }, locate('.dropdown-menu').inside('header'))"><div></div></button></div></figure></div>
<div class="sl-heading-wrapper level-h3"><h3 id="locate-builder-compose-css-and-xpath"><code dir="auto">locate()</code> builder: compose CSS and XPath</h3><a class="sl-anchor-link" href="#locate-builder-compose-css-and-xpath"><span aria-hidden="true" class="sl-anchor-icon"><svg width="16" height="16" viewBox="0 0 24 24"><path fill="currentcolor" d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 0 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 1 0-1.42-1.42Zm8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 0 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 1 0 1.42 1.42l3.88-3.89a4.49 4.49 0 0 0 0-6.33ZM8.83 15.17a1 1 0 0 0 1.1.22 1 1 0 0 0 .32-.22l4.92-4.92a1 1 0 0 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42Z"></path></svg></span><span class="sr-only">Section titled “locate() builder: compose CSS and XPath”</span></a></div>
<p><code dir="auto">locate()</code> chains CSS and XPath conditions into a single XPath expression. Each method returns the builder so you keep composing.</p>
<div class="expressive-code"><figure class="frame not-content"><figcaption class="header"></figcaption><pre data-language="js"><code><div class="ec-line"><div class="code"><span style="--0:#E5E7EB;--1:#1F2937">locate</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'a'</span><span style="--0:#9CA3AF;--1:#4B5563">)</span></div></div><div class="ec-line"><div class="code"><span class="indent"> </span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">withAttr</span><span style="--0:#9CA3AF;--1:#4B5563">({</span><span style="--0:#C9D1D9;--1:#1F2937"> href</span><span style="--0:#9CA3AF;--1:#4B5563">:</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'#'</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#9CA3AF;--1:#4B5563">})</span></div></div><div class="ec-line"><div class="code"><span class="indent"> </span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">inside</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#E5E7EB;--1:#1F2937">locate</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'label'</span><span style="--0:#9CA3AF;--1:#4B5563">).</span><span style="--0:#E5E7EB;--1:#1F2937">withText</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'Hello'</span><span style="--0:#9CA3AF;--1:#4B5563">))</span></div></div><div class="ec-line"><div class="code"><span style="--0:#8B949E;--0fs:italic;--1:#636976;--1fs:italic">// .//a[@href = '#'][ancestor::label[contains(., 'Hello')]]</span></div></div></code></pre><div class="copy"><button title="Copy to clipboard" data-copied="Copied!" data-code="locate('a') .withAttr({ href: '#' }) .inside(locate('label').withText('Hello'))// .//a[@href = '#'][ancestor::label[contains(., 'Hello')]]"><div></div></button></div></figure></div>
<p>Give long chains a name for readable logs:</p>
<div class="expressive-code"><figure class="frame not-content"><figcaption class="header"></figcaption><pre data-language="js"><code><div class="ec-line"><div class="code"><span style="--0:#E5E7EB;--1:#1F2937">locate</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'//table'</span><span style="--0:#9CA3AF;--1:#4B5563">).</span><span style="--0:#E5E7EB;--1:#1F2937">find</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'a'</span><span style="--0:#9CA3AF;--1:#4B5563">).</span><span style="--0:#E5E7EB;--1:#1F2937">withText</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'Edit'</span><span style="--0:#9CA3AF;--1:#4B5563">).</span><span style="--0:#E5E7EB;--1:#1F2937">as</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'row edit button'</span><span style="--0:#9CA3AF;--1:#4B5563">)</span></div></div></code></pre><div class="copy"><button title="Copy to clipboard" data-copied="Copied!" data-code="locate('//table').find('a').withText('Edit').as('row edit button')"><div></div></button></div></figure></div>
<blockquote>
<p><strong><code dir="auto">locate()</code> does not wrap ARIA role locators.</strong> The builder produces XPath; ARIA role matching relies on the accessibility tree provided by the helper. To scope an ARIA locator to a region, pass the region as a <a href="#context-scope-any-locator-to-a-region"><strong>context</strong> argument</a> rather than wrapping it in <code dir="auto">locate()</code>.</p>
</blockquote>
<p><strong>Example: the dropdown from the top bar, expressed with <code dir="auto">locate()</code></strong></p>
<p>When menu items expose no useful ARIA role (custom components built from <code dir="auto"><div></code> elements and click handlers), fall back to CSS and XPath inside a <code dir="auto">locate()</code> chain:</p>
<div class="expressive-code"><figure class="frame not-content"><figcaption class="header"></figcaption><pre data-language="js"><code><div class="ec-line"><div class="code"><span style="--0:#D8B4FE;--1:#7C3AED">const</span><span style="--0:#C9D1D9;--1:#1F2937"> userMenu </span><span style="--0:#9CA3AF;--1:#4B5563">=</span><span style="--1:#1F2937"><span style="--0:#C9D1D9"> </span><span style="--0:#E5E7EB">locate</span></span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'.dropdown-menu'</span><span style="--0:#9CA3AF;--1:#4B5563">).</span><span style="--0:#E5E7EB;--1:#1F2937">inside</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'.top-bar'</span><span style="--0:#9CA3AF;--1:#4B5563">).</span><span style="--0:#E5E7EB;--1:#1F2937">as</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'user menu'</span><span style="--0:#9CA3AF;--1:#4B5563">)</span></div></div><div class="ec-line"><div class="code">
</div></div><div class="ec-line"><div class="code"><span style="--0:#db2777;--0fw:bold;--1:#db2777;--1fw:bold">I</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">click</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'.user-avatar'</span><span style="--0:#9CA3AF;--1:#4B5563">,</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'.top-bar'</span><span style="--0:#9CA3AF;--1:#4B5563">)</span></div></div><div class="ec-line"><div class="code"><span style="--0:#db2777;--0fw:bold;--1:#db2777;--1fw:bold">I</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">click</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#E5E7EB;--1:#1F2937">locate</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'a'</span><span style="--0:#9CA3AF;--1:#4B5563">).</span><span style="--0:#E5E7EB;--1:#1F2937">withText</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'Settings'</span><span style="--0:#9CA3AF;--1:#4B5563">).</span><span style="--0:#E5E7EB;--1:#1F2937">inside</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#C9D1D9;--1:#1F2937">userMenu</span><span style="--0:#9CA3AF;--1:#4B5563">))</span></div></div></code></pre><div class="copy"><button title="Copy to clipboard" data-copied="Copied!" data-code="const userMenu = locate('.dropdown-menu').inside('.top-bar').as('user menu')I.click('.user-avatar', '.top-bar')I.click(locate('a').withText('Settings').inside(userMenu))"><div></div></button></div></figure></div>
<p><strong>Example: the Edit button in a specific table row</strong></p>
<div class="expressive-code"><figure class="frame not-content"><figcaption class="header"></figcaption><pre data-language="js"><code><div class="ec-line"><div class="code"><span style="--0:#D8B4FE;--1:#7C3AED">const</span><span style="--0:#C9D1D9;--1:#1F2937"> editAcme </span><span style="--0:#9CA3AF;--1:#4B5563">=</span><span style="--1:#1F2937"><span style="--0:#C9D1D9"> </span><span style="--0:#E5E7EB">locate</span></span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'tr'</span><span style="--0:#9CA3AF;--1:#4B5563">)</span></div></div><div class="ec-line"><div class="code"><span class="indent"> </span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">withDescendant</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#E5E7EB;--1:#1F2937">locate</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'td'</span><span style="--0:#9CA3AF;--1:#4B5563">).</span><span style="--0:#E5E7EB;--1:#1F2937">withText</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'Acme Corp'</span><span style="--0:#9CA3AF;--1:#4B5563">))</span></div></div><div class="ec-line"><div class="code"><span class="indent"> </span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">find</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'button'</span><span style="--0:#9CA3AF;--1:#4B5563">)</span></div></div><div class="ec-line"><div class="code"><span class="indent"> </span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">withText</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'Edit'</span><span style="--0:#9CA3AF;--1:#4B5563">)</span></div></div><div class="ec-line"><div class="code"><span class="indent"> </span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">as</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'Edit button for Acme'</span><span style="--0:#9CA3AF;--1:#4B5563">)</span></div></div><div class="ec-line"><div class="code">
</div></div><div class="ec-line"><div class="code"><span style="--0:#db2777;--0fw:bold;--1:#db2777;--1fw:bold">I</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">click</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#C9D1D9;--1:#1F2937">editAcme</span><span style="--0:#9CA3AF;--1:#4B5563">)</span></div></div></code></pre><div class="copy"><button title="Copy to clipboard" data-copied="Copied!" data-code="const editAcme = locate('tr') .withDescendant(locate('td').withText('Acme Corp')) .find('button') .withText('Edit') .as('Edit button for Acme')I.click(editAcme)"><div></div></button></div></figure></div>
<div class="sl-heading-wrapper level-h4"><h4 id="builder-methods">Builder methods</h4><a class="sl-anchor-link" href="#builder-methods"><span aria-hidden="true" class="sl-anchor-icon"><svg width="16" height="16" viewBox="0 0 24 24"><path fill="currentcolor" d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 0 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 1 0-1.42-1.42Zm8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 0 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 1 0 1.42 1.42l3.88-3.89a4.49 4.49 0 0 0 0-6.33ZM8.83 15.17a1 1 0 0 0 1.1.22 1 1 0 0 0 .32-.22l4.92-4.92a1 1 0 0 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42Z"></path></svg></span><span class="sr-only">Section titled “Builder methods”</span></a></div>
<p>The <code dir="auto">with*</code> family filters elements positively; <code dir="auto">without*</code> excludes; <code dir="auto">and</code> / <code dir="auto">andNot</code> / <code dir="auto">or</code> compose raw predicates or union locators.</p>
<table><thead><tr><th>Method</th><th>Purpose</th><th>Example</th></tr></thead><tbody><tr><td><code dir="auto">find(loc)</code></td><td>Descendant lookup</td><td><code dir="auto">locate('table').find('td')</code></td></tr><tr><td><code dir="auto">withAttr(obj)</code></td><td>Match attributes</td><td><code dir="auto">locate('input').withAttr({ placeholder: 'Name' })</code></td></tr><tr><td><code dir="auto">withAttrContains(attr, str)</code></td><td>Attr value contains substring</td><td><code dir="auto">locate('a').withAttrContains('href', 'google')</code></td></tr><tr><td><code dir="auto">withAttrStartsWith(attr, str)</code></td><td>Attr value starts with</td><td><code dir="auto">locate('a').withAttrStartsWith('href', 'https://')</code></td></tr><tr><td><code dir="auto">withAttrEndsWith(attr, str)</code></td><td>Attr value ends with</td><td><code dir="auto">locate('a').withAttrEndsWith('href', '.pdf')</code></td></tr><tr><td><code dir="auto">withClass(...classes)</code></td><td>Has all classes (word-exact)</td><td><code dir="auto">locate('button').withClass('btn-primary', 'btn-lg')</code></td></tr><tr><td><code dir="auto">withClassAttr(str)</code></td><td>Class attribute contains substring (legacy — prefer <code dir="auto">withClass</code>)</td><td><code dir="auto">locate('div').withClassAttr('form')</code></td></tr><tr><td><code dir="auto">withText(str)</code></td><td>Visible text contains</td><td><code dir="auto">locate('span').withText('Warning')</code></td></tr><tr><td><code dir="auto">withTextEquals(str)</code></td><td>Visible text matches exactly</td><td><code dir="auto">locate('button').withTextEquals('Add')</code></td></tr><tr><td><code dir="auto">withChild(loc)</code></td><td>Has a direct child</td><td><code dir="auto">locate('form').withChild('select')</code></td></tr><tr><td><code dir="auto">withDescendant(loc)</code></td><td>Has a descendant anywhere below</td><td><code dir="auto">locate('tr').withDescendant('img.avatar')</code></td></tr><tr><td><code dir="auto">withoutClass(...classes)</code></td><td>None of these classes</td><td><code dir="auto">locate('tr').withoutClass('deleted')</code></td></tr><tr><td><code dir="auto">withoutText(str)</code></td><td>Visible text does not contain</td><td><code dir="auto">locate('li').withoutText('Archived')</code></td></tr><tr><td><code dir="auto">withoutAttr(obj)</code></td><td>None of these attr/value pairs</td><td><code dir="auto">locate('button').withoutAttr({ disabled: '' })</code></td></tr><tr><td><code dir="auto">withoutChild(loc)</code></td><td>No direct child matching</td><td><code dir="auto">locate('form').withoutChild('input[type=submit]')</code></td></tr><tr><td><code dir="auto">withoutDescendant(loc)</code></td><td>No descendant matching</td><td><code dir="auto">locate('button').withoutDescendant('svg')</code></td></tr><tr><td><code dir="auto">inside(loc)</code></td><td>Sits inside an ancestor</td><td><code dir="auto">locate('select').inside('form#user')</code></td></tr><tr><td><code dir="auto">before(loc)</code></td><td>Appears before another element</td><td><code dir="auto">locate('button').before('.btn-cancel')</code></td></tr><tr><td><code dir="auto">after(loc)</code></td><td>Appears after another element</td><td><code dir="auto">locate('button').after('.btn-cancel')</code></td></tr><tr><td><code dir="auto">or(loc)</code></td><td>Union of two locators</td><td><code dir="auto">locate('button.submit').or('input[type=submit]')</code></td></tr><tr><td><code dir="auto">and(expr)</code></td><td>Append raw XPath predicate</td><td><code dir="auto">locate('input').and('@type="text" or @type="email"')</code></td></tr><tr><td><code dir="auto">andNot(expr)</code></td><td>Append negated raw XPath predicate</td><td><code dir="auto">locate('button').andNot('.//svg')</code></td></tr><tr><td><code dir="auto">first()</code> / <code dir="auto">last()</code></td><td>Bound position</td><td><code dir="auto">locate('#table td').first()</code></td></tr><tr><td><code dir="auto">at(n)</code></td><td>Pick nth element (negative counts from end)</td><td><code dir="auto">locate('#table td').at(-2)</code></td></tr><tr><td><code dir="auto">as(name)</code></td><td>Rename in logs</td><td><code dir="auto">locate('//table').as('orders table')</code></td></tr></tbody></table>
<div class="sl-heading-wrapper level-h4"><h4 id="translating-complex-xpath">Translating complex XPath</h4><a class="sl-anchor-link" href="#translating-complex-xpath"><span aria-hidden="true" class="sl-anchor-icon"><svg width="16" height="16" viewBox="0 0 24 24"><path fill="currentcolor" d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 0 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 1 0-1.42-1.42Zm8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 0 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 1 0 1.42 1.42l3.88-3.89a4.49 4.49 0 0 0 0-6.33ZM8.83 15.17a1 1 0 0 0 1.1.22 1 1 0 0 0 .32-.22l4.92-4.92a1 1 0 0 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42Z"></path></svg></span><span class="sr-only">Section titled “Translating complex XPath”</span></a></div>
<p>Long XPath expressions become readable with the DSL. For example:</p>
<div class="expressive-code"><figure class="frame not-content"><figcaption class="header"></figcaption><pre data-language="plaintext"><code><div class="ec-line"><div class="code"><span style="--0:#c9d1d9;--1:#1f2937">//*[self::button</span></div></div><div class="ec-line"><div class="code"><span class="indent"><span style="--0:#c9d1d9;--1:#1f2937"> </span></span><span style="--0:#c9d1d9;--1:#1f2937">and contains(@class,"red-btn")</span></div></div><div class="ec-line"><div class="code"><span class="indent"><span style="--0:#c9d1d9;--1:#1f2937"> </span></span><span style="--0:#c9d1d9;--1:#1f2937">and contains(@class,"btn-text-and-icon")</span></div></div><div class="ec-line"><div class="code"><span class="indent"><span style="--0:#c9d1d9;--1:#1f2937"> </span></span><span style="--0:#c9d1d9;--1:#1f2937">and contains(@class,"btn-lg")</span></div></div><div class="ec-line"><div class="code"><span class="indent"><span style="--0:#c9d1d9;--1:#1f2937"> </span></span><span style="--0:#c9d1d9;--1:#1f2937">and contains(@class,"btn-selected")</span></div></div><div class="ec-line"><div class="code"><span class="indent"><span style="--0:#c9d1d9;--1:#1f2937"> </span></span><span style="--0:#c9d1d9;--1:#1f2937">and normalize-space(.)="Button selected"</span></div></div><div class="ec-line"><div class="code"><span class="indent"><span style="--0:#c9d1d9;--1:#1f2937"> </span></span><span style="--0:#c9d1d9;--1:#1f2937">and not(.//svg)]</span></div></div></code></pre><div class="copy"><button title="Copy to clipboard" data-copied="Copied!" data-code="//*[self::button and contains(@class,"red-btn") and contains(@class,"btn-text-and-icon") and contains(@class,"btn-lg") and contains(@class,"btn-selected") and normalize-space(.)="Button selected" and not(.//svg)]"><div></div></button></div></figure></div>
<p>becomes:</p>
<div class="expressive-code"><figure class="frame not-content"><figcaption class="header"></figcaption><pre data-language="js"><code><div class="ec-line"><div class="code"><span style="--0:#E5E7EB;--1:#1F2937">locate</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'button'</span><span style="--0:#9CA3AF;--1:#4B5563">)</span></div></div><div class="ec-line"><div class="code"><span class="indent"> </span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">withClass</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'red-btn'</span><span style="--0:#9CA3AF;--1:#4B5563">,</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'btn-text-and-icon'</span><span style="--0:#9CA3AF;--1:#4B5563">,</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'btn-lg'</span><span style="--0:#9CA3AF;--1:#4B5563">,</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'btn-selected'</span><span style="--0:#9CA3AF;--1:#4B5563">)</span></div></div><div class="ec-line"><div class="code"><span class="indent"> </span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">withText</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'Button selected'</span><span style="--0:#9CA3AF;--1:#4B5563">)</span></div></div><div class="ec-line"><div class="code"><span class="indent"> </span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">withoutDescendant</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'svg'</span><span style="--0:#9CA3AF;--1:#4B5563">)</span></div></div></code></pre><div class="copy"><button title="Copy to clipboard" data-copied="Copied!" data-code="locate('button') .withClass('red-btn', 'btn-text-and-icon', 'btn-lg', 'btn-selected') .withText('Button selected') .withoutDescendant('svg')"><div></div></button></div></figure></div>
<blockquote>
<p><code dir="auto">withClass</code> uses word-exact matching (same as CSS <code dir="auto">.foo</code>), so <code dir="auto">.withClass('btn')</code> will not accidentally match <code dir="auto">class="btn-lg"</code>. Use <code dir="auto">withAttrContains('class', …)</code> if you need the old substring behavior.</p>
</blockquote>
<div class="sl-heading-wrapper level-h2"><h2 id="custom-locators">Custom locators</h2><a class="sl-anchor-link" href="#custom-locators"><span aria-hidden="true" class="sl-anchor-icon"><svg width="16" height="16" viewBox="0 0 24 24"><path fill="currentcolor" d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 0 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 1 0-1.42-1.42Zm8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 0 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 1 0 1.42 1.42l3.88-3.89a4.49 4.49 0 0 0 0-6.33ZM8.83 15.17a1 1 0 0 0 1.1.22 1 1 0 0 0 .32-.22l4.92-4.92a1 1 0 0 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42Z"></path></svg></span><span class="sr-only">Section titled “Custom locators”</span></a></div>
<p>Teams that tag elements with <code dir="auto">data-qa</code>, <code dir="auto">data-test</code>, or similar attributes can register a short-form syntax instead of typing <code dir="auto">{ css: '[data-qa-id=register_button]' }</code> every time.</p>
<p>The <a href="/plugins#customlocator"><code dir="auto">customLocator</code> plugin</a> maps a prefix to an attribute:</p>
<div class="expressive-code"><figure class="frame not-content"><figcaption class="header"></figcaption><pre data-language="js"><code><div class="ec-line"><div class="code"><span style="--0:#8B949E;--0fs:italic;--1:#636976;--1fs:italic">// with plugin enabled: $name → [data-qa=name]</span></div></div><div class="ec-line"><div class="code"><span style="--0:#db2777;--0fw:bold;--1:#db2777;--1fw:bold">I</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">click</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'$register_button'</span><span style="--0:#9CA3AF;--1:#4B5563">)</span></div></div><div class="ec-line"><div class="code"><span style="--0:#db2777;--0fw:bold;--1:#db2777;--1fw:bold">I</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">fillField</span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#7DD3FC;--1:#0369A1">'$email'</span><span style="--0:#9CA3AF;--1:#4B5563">,</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'user@test.com'</span><span style="--0:#9CA3AF;--1:#4B5563">)</span></div></div></code></pre><div class="copy"><button title="Copy to clipboard" data-copied="Copied!" data-code="// with plugin enabled: $name → [data-qa=name]I.click('$register_button')I.fillField('$email', 'user@test.com')"><div></div></button></div></figure></div>
<p>For more control, register a filter from a bootstrap script or plugin:</p>
<div class="expressive-code"><figure class="frame not-content"><figcaption class="header"></figcaption><pre data-language="js"><code><div class="ec-line"><div class="code"><span style="--0:#C9D1D9;--1:#1F2937">codeceptjs</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#C9D1D9;--1:#1F2937">locator</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">addFilter</span><span style="--0:#9CA3AF;--1:#4B5563">((</span><span style="--0:#C9D1D9;--1:#1F2937">providedLocator</span><span style="--0:#9CA3AF;--1:#4B5563">,</span><span style="--0:#C9D1D9;--1:#1F2937"> locatorObj</span><span style="--0:#9CA3AF;--1:#4B5563">)</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#D8B4FE;--1:#7C3AED">=></span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#9CA3AF;--1:#4B5563">{</span></div></div><div class="ec-line"><div class="code"><span class="indent"> </span><span style="--0:#D8B4FE;--1:#7C3AED">if</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#9CA3AF;--1:#4B5563">(</span><span style="--0:#C9D1D9;--1:#1F2937">providedLocator</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#C9D1D9;--1:#1F2937">data</span><span style="--0:#9CA3AF;--1:#4B5563">)</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#9CA3AF;--1:#4B5563">{</span></div></div><div class="ec-line"><div class="code"><span class="indent"><span style="--0:#C9D1D9;--1:#1F2937"> </span></span><span style="--0:#C9D1D9;--1:#1F2937">locatorObj</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#C9D1D9;--1:#1F2937">type </span><span style="--0:#9CA3AF;--1:#4B5563">=</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'css'</span></div></div><div class="ec-line"><div class="code"><span class="indent"><span style="--0:#C9D1D9;--1:#1F2937"> </span></span><span style="--0:#C9D1D9;--1:#1F2937">locatorObj</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#C9D1D9;--1:#1F2937">value </span><span style="--0:#9CA3AF;--1:#4B5563">=</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">`[data-element=</span><span style="--0:#9CA3AF;--1:#4B5563">${</span><span style="--0:#7DD3FC;--1:#0369A1">providedLocator</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#C9D1D9;--1:#1F2937">data</span><span style="--0:#9CA3AF;--1:#4B5563">}</span><span style="--0:#7DD3FC;--1:#0369A1">]`</span></div></div><div class="ec-line"><div class="code"><span class="indent"> </span><span style="--0:#9CA3AF;--1:#4B5563">}</span></div></div><div class="ec-line"><div class="code"><span style="--0:#9CA3AF;--1:#4B5563">})</span></div></div></code></pre><div class="copy"><button title="Copy to clipboard" data-copied="Copied!" data-code="codeceptjs.locator.addFilter((providedLocator, locatorObj) => { if (providedLocator.data) { locatorObj.type = 'css' locatorObj.value = `[data-element=${providedLocator.data}]` }})"><div></div></button></div></figure></div>
<p>After registration, <code dir="auto">{ data: 'user-login' }</code> is a valid strict locator:</p>
<div class="expressive-code"><figure class="frame not-content"><figcaption class="header"></figcaption><pre data-language="js"><code><div class="ec-line"><div class="code"><span style="--0:#db2777;--0fw:bold;--1:#db2777;--1fw:bold">I</span><span style="--0:#9CA3AF;--1:#4B5563">.</span><span style="--0:#E5E7EB;--1:#1F2937">click</span><span style="--0:#9CA3AF;--1:#4B5563">({</span><span style="--0:#C9D1D9;--1:#1F2937"> data</span><span style="--0:#9CA3AF;--1:#4B5563">:</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#7DD3FC;--1:#0369A1">'user-login'</span><span style="--0:#C9D1D9;--1:#1F2937"> </span><span style="--0:#9CA3AF;--1:#4B5563">})</span></div></div></code></pre><div class="copy"><button title="Copy to clipboard" data-copied="Copied!" data-code="I.click({ data: 'user-login' })"><div></div></button></div></figure></div>
<p>Further reading: Mozilla’s <a href="https://blog.mozilla.org/webqa/2013/09/26/writing-reliable-locators-for-selenium-and-webdriver-tests/">Writing reliable locators for Selenium and WebDriver tests</a> and the <a href="https://davertmik.github.io/locator/">Locator Advicer</a>.</p> </div> <footer class="sl-flex astro-4qzcips2"> <div class="meta sl-flex astro-4qzcips2"> </div> <div class="pagination-links print:hidden astro-c6pzuqbq" dir="ltr"> <a href="/test-structure" rel="prev" class="astro-c6pzuqbq"> <svg aria-hidden="true" class="astro-c6pzuqbq astro-cbi3kmoi" width="16" height="16" viewBox="0 0 24 24" fill="currentColor" style="--sl-icon-size: 1.5rem;"><path d="M17 11H9.41l3.3-3.29a1.004 1.004 0 1 0-1.42-1.42l-5 5a1 1 0 0 0-.21.33 1 1 0 0 0 0 .76 1 1 0 0 0 .21.33l5 5a1.002 1.002 0 0 0 1.639-.325 1 1 0 0 0-.219-1.095L9.41 13H17a1 1 0 0 0 0-2Z"/></svg> <span class="astro-c6pzuqbq"> Previous <br class="astro-c6pzuqbq"> <span class="link-title astro-c6pzuqbq">Test Structure</span> </span> </a> <a href="/assertions" rel="next" class="astro-c6pzuqbq"> <svg aria-hidden="true" class="astro-c6pzuqbq astro-cbi3kmoi" width="16" height="16" viewBox="0 0 24 24" fill="currentColor" style="--sl-icon-size: 1.5rem;"><path d="M17.92 11.62a1.001 1.001 0 0 0-.21-.33l-5-5a1.003 1.003 0 1 0-1.42 1.42l3.3 3.29H7a1 1 0 0 0 0 2h7.59l-3.3 3.29a1.002 1.002 0 0 0 .325 1.639 1 1 0 0 0 1.095-.219l5-5a1 1 0 0 0 .21-.33 1 1 0 0 0 0-.76Z"/></svg> <span class="astro-c6pzuqbq"> Next <br class="astro-c6pzuqbq"> <span class="link-title astro-c6pzuqbq">Assertions</span> </span> </a> </div> </footer> </div> </div> </main> </div> </div> </div> <footer class="cc-footer !mt-0 py-16 relative overflow-hidden"> <div class="cc-footer-grain" aria-hidden="true"></div> <div class="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 relative"> <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-5 gap-8 mb-12"> <div class="lg:col-span-1"> <a href="/" class="inline-flex items-center mb-6" aria-label="CodeceptJS home"> <img src="/logo/logo-violet-dark.svg" alt="CodeceptJS" width="205" height="40" class="h-10 w-auto"> </a> <p class="cc-footer-body leading-relaxed mb-6">
Modern end-to-end testing framework that makes your tests readable, maintainable, and reliable.
</p> <div class="flex space-x-3"> <a href="https://github.com/codeceptjs/CodeceptJS" aria-label="GitHub" class="cc-footer-social"> <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round"><path d="M15 22v-4a4.8 4.8 0 0 0-1-3.5c3 0 6-2 6-5.5.08-1.25-.27-2.48-1-3.5.28-1.15.28-2.35 0-3.5 0 0-1 0-3 1.5-2.64-.5-5.36-.5-8 0C6 2 5 2 5 2c-.3 1.15-.3 2.35 0 3.5A5.403 5.403 0 0 0 4 9c0 3.5 3 5.5 6 5.5-.39.49-.68 1.05-.85 1.65-.17.6-.22 1.23-.15 1.85v4"></path><path d="M9 18c-4.51 2-5-2-7-2"></path></svg> </a> <a href="https://x.com/codeceptjs" aria-label="Twitter / X" class="cc-footer-social"> <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round"><path d="M22 4s-.7 2.1-2 3.4c1.6 10-9.4 17.3-18 11.6 2.2.1 4.4-.6 6-2C3 15.5.5 9.6 3 5c2.2 2.6 5.6 4.1 9 4-.9-4.2 4-6.6 7-3.8 1.1 0 3-1.2 3-1.2z"></path></svg> </a> <a href="https://bit.ly/chat-codeceptjs" aria-label="Slack" class="cc-footer-social"> <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round"><rect width="3" height="8" x="13" y="2" rx="1.5"></rect><path d="M19 8.5V10h1.5A1.5 1.5 0 1 0 19 8.5"></path><rect width="3" height="8" x="8" y="14" rx="1.5"></rect><path d="M5 15.5V14H3.5A1.5 1.5 0 1 0 5 15.5"></path><rect width="8" height="3" x="14" y="13" rx="1.5"></rect><path d="M15.5 19H14v1.5a1.5 1.5 0 1 0 1.5-1.5"></path><rect width="8" height="3" x="2" y="8" rx="1.5"></rect><path d="M8.5 5H10V3.5A1.5 1.5 0 1 0 8.5 5"></path></svg> </a> </div> </div> <div> <h3 class="cc-footer-heading">Get Started</h3> <ul class="space-y-3"> <li><a href="/quickstart" class="cc-footer-link">Quickstart</a></li> <li><a href="/basics" class="cc-footer-link">Web Basics</a></li> <li><a href="/mobile" class="cc-footer-link">Mobile Testing</a></li> <li><a href="/playwright" class="cc-footer-link">Playwright</a></li> <li><a href="/webdriver" class="cc-footer-link">WebDriver</a></li> <li><a href="/best" class="cc-footer-link">Best Practices</a></li> </ul> </div> <div> <h3 class="cc-footer-heading">Reference</h3> <ul class="space-y-3"> <li><a href="/web-api" class="cc-footer-link">Web API</a></li> <li><a href="/mobile-api" class="cc-footer-link">Mobile API</a></li> <li><a href="/locators" class="cc-footer-link">Locators</a></li> <li><a href="/pageobjects" class="cc-footer-link">Page Objects</a></li> <li><a href="/configuration" class="cc-footer-link">Configuration</a></li> <li><a href="/plugins" class="cc-footer-link">Plugins</a></li> </ul> </div> <div> <h3 class="cc-footer-heading">Community</h3> <ul class="space-y-3"> <li><a rel="nofollow" href="https://github.com/codeceptjs/CodeceptJS" class="cc-footer-link">GitHub</a></li> <li><a rel="nofollow" href="https://github.com/codeceptjs/CodeceptJS/discussions" class="cc-footer-link">GitHub Discussions</a></li> <li><a rel="nofollow" href="https://bit.ly/chat-codeceptjs" class="cc-footer-link">Slack Chat</a></li> <li><a rel="nofollow" href="https://github.com/codeceptjs/CodeceptJS/issues" class="cc-footer-link">Issues</a></li> <li><a rel="nofollow" href="https://x.com/codeceptjs" class="cc-footer-link">Twitter</a></li> <li><a href="/media-kit" class="cc-footer-link">Media Kit</a></li> </ul> </div> <div> <h3 class="cc-footer-heading">Try Testomat.io</h3> <a href="https://testomat.io" class="cc-footer-card no-underline"> <div class="cc-footer-card-head"> <span class="cc-footer-card-badge">T</span> <div> <div class="cc-footer-card-title">Testomat.io</div> <div class="cc-footer-card-meta">by CodeceptJS authors</div> </div> </div> <p class="cc-footer-card-body">
Test Case Management for CodeceptJS — built by the team behind it.
</p> <span class="cc-footer-card-cta">
Learn More
<span class="cc-footer-card-arrow" aria-hidden="true">→</span> </span> </a> </div> </div> <div class="cc-footer-bottom"> <div class="flex flex-col md:flex-row justify-between items-center gap-4"> <div class="cc-footer-copy">
© 2026 CodeceptJS · MIT licensed · built by people who actually test things.
</div> <div class="flex items-center gap-6 text-sm"> <a href="#" class="cc-footer-link">Privacy</a> <a href="#" class="cc-footer-link">Terms</a> <a href="https://github.com/codeceptjs/CodeceptJS/blob/4.x/LICENSE" class="cc-footer-link">License</a> </div> </div> </div> </div> </footer> </div> <script is:client="load">
const threshold = 64;
const activeClass = 'scrolled';
const homeClass = 'home-page';
let header;
const sidebarSelector = '#starlight__sidebar .sidebar-content a';
function normalizePath(pathname) {
if (!pathname || pathname === '/') return '/';
return pathname.endsWith('/') ? pathname.slice(0, -1) : pathname;
}
function syncSidebarCurrentLink() {
const links = document.querySelectorAll(sidebarSelector);
if (!links.length) return;
const currentPath = normalizePath(window.location.pathname);
let matched = null;
links.forEach((link) => {
if (!(link instanceof HTMLAnchorElement)) return;
link.removeAttribute('aria-current');
const linkPath = normalizePath(new URL(link.href, window.location.origin).pathname);
if (linkPath === currentPath) matched = link;
});
if (matched) matched.setAttribute('aria-current', 'page');
}
function update() {
if (!header) return;
if (window.scrollY > threshold) {
header.classList.add(activeClass);
} else {
header.classList.remove(activeClass);
}
}
function tagHeaderlessTables() {
// Markdown often produces tables with empty <th> cells when authors
// want a plain N-column grid. Tag those so the stylesheet can hide
// the empty band and force equal column widths.
const tables = document.querySelectorAll('.sl-markdown-content table');
tables.forEach((t) => {
const ths = t.querySelectorAll('thead th');
if (!ths.length) return;
const allEmpty = Array.from(ths).every((th) => !th.textContent || !th.textContent.trim());
t.classList.toggle('cc-table-no-header', allEmpty);
if (allEmpty) {
// Expose the column count so CSS can split width equally.
const firstRow = t.querySelector('tbody tr');
if (firstRow) t.style.setProperty('--col-count', String(firstRow.children.length));
}
});
}
function wrapTablesForScroll() {
// Wrap each docs table in a horizontal-scroll container so wide tables
// scroll inside their own box instead of overflowing the viewport on
// mobile. Idempotent — skips tables already wrapped (re-runs on nav).
const tables = document.querySelectorAll('.sl-markdown-content table');
tables.forEach((table) => {
const parent = table.parentElement;
if (parent && parent.classList.contains('cc-table-scroll')) return;
const wrapper = document.createElement('div');
wrapper.className = 'cc-table-scroll';
table.replaceWith(wrapper);
wrapper.appendChild(table);
});
}
let footerOverlapRaf = 0;
function updateFooterOverlap() {
footerOverlapRaf = 0;
const footer = document.querySelector('.cc-footer');
if (!footer) {
document.documentElement.style.setProperty('--cc-footer-overlap', '0px');
return;
}
const rect = footer.getBoundingClientRect();
const overlap = Math.max(0, window.innerHeight - rect.top);
document.documentElement.style.setProperty('--cc-footer-overlap', overlap + 'px');
}
function scheduleFooterOverlap() {
if (footerOverlapRaf) return;
footerOverlapRaf = requestAnimationFrame(updateFooterOverlap);
}
function setup() {
header = document.querySelector('#site-header');
wrapTablesForScroll();
tagHeaderlessTables();
updateFooterOverlap();
window.removeEventListener('scroll', scheduleFooterOverlap);
window.removeEventListener('resize', scheduleFooterOverlap);
window.addEventListener('scroll', scheduleFooterOverlap, { passive: true });
window.addEventListener('resize', scheduleFooterOverlap);
if (!header) return;
const isHome = window.location.pathname === '/';
// Always toggle home-page class on header
header.classList.toggle(homeClass, isHome);
// If home page → disable scroll behavior
if (isHome) {
header.classList.remove(activeClass);
window.removeEventListener('scroll', update);
return;
}
// Non-home pages
update();
syncSidebarCurrentLink();
// Prevent duplicate listeners
window.removeEventListener('scroll', update);
window.addEventListener('scroll', update);
}
// Initial load
setup();
// Re-run after Astro navigation
document.addEventListener('astro:after-swap', () => {
setup();
});
</script> </body></html>