webship-js 2.0.1 → 2.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/bin/generate-reports.js +191 -0
  2. package/bin/init-webship.js +343 -0
  3. package/bin/postinstall.js +8 -74
  4. package/cucumber.js +59 -1
  5. package/examples/diffy/baseline.html +54 -0
  6. package/examples/diffy/changed.html +63 -0
  7. package/examples/diffy/index.html +52 -0
  8. package/examples/index.html +6 -0
  9. package/examples/test--when--i-additionally-select.html +27 -0
  10. package/package.json +10 -4
  11. package/tests/features/diffy/test--diffy-01-example-demo.feature +22 -0
  12. package/tests/features/diffy/test--diffy-02-all-steps.feature +52 -0
  13. package/tests/features/diffy/test--diffy-03-real-api.feature +21 -0
  14. package/tests/features/test--then--i-save-screenshot.feature +33 -0
  15. package/tests/features/test--then--i-see-locator.feature +320 -0
  16. package/tests/features/test--then--i-should-see-n-elements.feature +24 -0
  17. package/tests/features/test--then--print-current-url-and-response.feature +21 -0
  18. package/tests/features/test--when--i-additionally-select.feature +30 -0
  19. package/tests/features/test--when--i-follow.feature +22 -0
  20. package/tests/selectors/back-end-selectors.json +13 -0
  21. package/tests/selectors/front-end-selectors.json +16 -0
  22. package/tests/selectors/homepage-selectors.json +13 -0
  23. package/tests/step-definitions/webship-api.js +234 -41
  24. package/tests/step-definitions/webship-screenshot.js +427 -0
  25. package/tests/step-definitions/webship-selectors.js +961 -0
  26. package/tests/step-definitions/webship.js +829 -230
  27. package/tests/step-definitions-diffy/README.md +329 -0
  28. package/tests/step-definitions-diffy/mock-diffy-api/server.js +84 -0
  29. package/tests/step-definitions-diffy/webship-diffy-mock.js +31 -0
  30. package/tests/step-definitions-diffy/webship-diffy.js +472 -0
  31. package/generate-reports.js +0 -22
  32. package/required/cucumber.js +0 -37
  33. package/required/generate-reports.js +0 -22
  34. package/required/package.json +0 -18
  35. package/required/playwright.config.ts +0 -37
  36. package/required/tests/features/README.md +0 -1
  37. package/required/tests/features/check-homepage.feature +0 -8
  38. package/required/tests/reports/README.md +0 -1
  39. package/required/tests/step-definitions/README.md +0 -1
  40. package/required/tests/step-definitions/custom.js +0 -4
  41. package/required/tsconfig.json +0 -12
@@ -7,6 +7,25 @@ const assert = require('assert');
7
7
  const axios = require('axios');
8
8
  const path = require('path');
9
9
 
10
+ // ---------------------------------------------------------------------------
11
+ // Auto HTML report on cucumber-js process exit.
12
+ // Disable: WEBSHIP_REPORT_DISABLE=1. Extra flags: WEBSHIP_REPORT_ARGS="--theme hierarchy --layout 2".
13
+ // Registered once per process.
14
+ // ---------------------------------------------------------------------------
15
+ if (!global.__WEBSHIP_AUTO_REPORT__) {
16
+ global.__WEBSHIP_AUTO_REPORT__ = true;
17
+ process.on('exit', () => {
18
+ if (process.env.WEBSHIP_REPORT_DISABLE) return;
19
+ try {
20
+ const { run } = require(path.join(__dirname, '..', '..', 'bin', 'generate-reports'));
21
+ const extra = (process.env.WEBSHIP_REPORT_ARGS || '').split(/\s+/).filter(Boolean);
22
+ run(extra);
23
+ } catch (err) {
24
+ console.error('[webship-js] Report generation failed:', err.message);
25
+ }
26
+ });
27
+ }
28
+
10
29
  // ---------------------------------------------------------------------------
11
30
  // World
12
31
  // ---------------------------------------------------------------------------
@@ -189,20 +208,35 @@ async function isAnyModalVisible(page) {
189
208
  );
190
209
  }
191
210
 
192
- // ---------------------------------------------------------------------------
193
- // Given I am an anonymous user
194
- // Captures: (pronounCase) = 1
195
- // ---------------------------------------------------------------------------
211
+ /**
212
+ * Clear cookies and navigate to the launch URL as an anonymous visitor.
213
+ *
214
+ * Example #1: Given I am an anonymous user
215
+ * Example #2: Given we are an anonymous user
216
+ * Example #3: Given an anonymous user
217
+ *
218
+ */
196
219
  Given(/^(I am |we are )?an anonymous user$/, async function (pronounCase) {
197
220
  await this.context.clearCookies();
198
221
  await gotoUrl(this.page, this.launchUrl);
199
222
  await waitForPageLoad(this.page, this.minWaitTime.page || 3000);
200
223
  });
201
224
 
202
- // ---------------------------------------------------------------------------
203
- // Given I am on homepage / frontpage
204
- // Captures: (pronounCase, theCase, pageCase) = 3
205
- // ---------------------------------------------------------------------------
225
+ /**
226
+ * Open the homepage.
227
+ *
228
+ * Example #1: Given I am on homepage
229
+ * Example #2: Given I am on the homepage
230
+ * Example #3: Given I am on frontpage
231
+ * Example #4: Given I am on the frontpage
232
+ * Example #5: Given we are on homepage
233
+ * Example #6: Given we are on the frontpage
234
+ * Example #7: Given on homepage
235
+ * Example #8: Given on the homepage
236
+ * Example #9: Given on frontpage
237
+ * Example #10: Given on the frontpage
238
+ *
239
+ */
206
240
  Given(/^(I am |we are )?on( the)* (homepage|frontpage)$/, async function (pronounCase, theCase, pageCase) {
207
241
  const defaultTime = this.minWaitTime.page || 3000;
208
242
  await gotoUrl(this.page, this.launchUrl);
@@ -210,20 +244,37 @@ Given(/^(I am |we are )?on( the)* (homepage|frontpage)$/, async function (pronou
210
244
  await waitForPageLoad(this.page, defaultTime);
211
245
  });
212
246
 
213
- // ---------------------------------------------------------------------------
214
- // Given I am on "/about-us.html"
215
- // Captures: (pronounCase, theCase, url, pageCase) = 4
216
- // ---------------------------------------------------------------------------
247
+ /**
248
+ * Open a specific page under the launch URL.
249
+ *
250
+ * Example #1: Given I am on "/about-us.html"
251
+ * Example #2: Given I am on the "/about-us.html" page
252
+ * Example #3: Given we are on "/user/login"
253
+ * Example #4: Given we are on the "/contact-us.html" page
254
+ * Example #5: Given on "/about-us.html"
255
+ * Example #6: Given on the "/about-us.html" page
256
+ * Example #7: Given I am on "https://un.org"
257
+ *
258
+ */
217
259
  Given(/^(I am |we are )*on( the)* "([^"]*)?"( page)*$/, async function (pronounCase, theCase, url, pageCase) {
218
260
  await gotoUrl(this.page, this.launchUrl + url);
219
261
  await this.page.waitForSelector('body', { state: 'attached', timeout: 10000 });
220
262
  await waitForPageLoad(this.page);
221
263
  });
222
264
 
223
- // ---------------------------------------------------------------------------
224
- // When I go to homepage / frontpage
225
- // Captures: (pronounCase, theCase, pageCase) = 3
226
- // ---------------------------------------------------------------------------
265
+ /**
266
+ * Navigate to the homepage.
267
+ *
268
+ * Example #1: When I go to homepage
269
+ * Example #2: When I go to the homepage
270
+ * Example #3: When I navigate to the homepage
271
+ * Example #4: When navigating to the homepage
272
+ * Example #5: When navigating to homepage
273
+ * Example #6: When navigating to the frontpage
274
+ * Example #7: When we go to the homepage
275
+ * Example #8: When we navigate to the homepage
276
+ *
277
+ */
227
278
  When(/^(I go |I navigate |we go |we navigate |navigating )?to( the)* (homepage|frontpage)$/, async function (pronounCase, theCase, pageCase) {
228
279
  const defaultTime = this.minWaitTime.page || 3000;
229
280
  await gotoUrl(this.page, this.launchUrl);
@@ -231,10 +282,17 @@ When(/^(I go |I navigate |we go |we navigate |navigating )?to( the)* (homepage|f
231
282
  await waitForPageLoad(this.page, defaultTime);
232
283
  });
233
284
 
234
- // ---------------------------------------------------------------------------
235
- // When I go to "/contact-us.html"
236
- // Captures: (pronounCase, url) = 2
237
- // ---------------------------------------------------------------------------
285
+ /**
286
+ * Navigate to a specific page.
287
+ *
288
+ * Example #1: When I go to "/contact-us.html"
289
+ * Example #2: When I go to "/user/login"
290
+ * Example #3: When I navigate to "/admin/dashboard"
291
+ * Example #4: When navigating to "/products"
292
+ * Example #5: When we go to "/products"
293
+ * Example #6: When we navigate to "/terms"
294
+ *
295
+ */
238
296
  When(/^(I go |I navigate |we go |we navigate |navigating )?to "([^"]*)?"$/, async function (pronounCase, url) {
239
297
  const defaultTime = this.minWaitTime.page || 3000;
240
298
  await gotoUrl(this.page, this.launchUrl + url);
@@ -242,10 +300,15 @@ When(/^(I go |I navigate |we go |we navigate |navigating )?to "([^"]*)?"$/, asyn
242
300
  await waitForPageLoad(this.page, defaultTime);
243
301
  });
244
302
 
245
- // ---------------------------------------------------------------------------
246
- // Then I should see "text" / Then I should not see "text"
247
- // Captures: (pronounCase, notCase, expectedText) = 3
248
- // ---------------------------------------------------------------------------
303
+ /**
304
+ * Assert that text is or is not present on the page.
305
+ *
306
+ * Example #1: Then I should see "Welcome"
307
+ * Example #2: Then we should see "Your accounts for the group is public"
308
+ * Example #3: Then I should not see "Access denied"
309
+ * Example #4: Then we should not see "Edit layout"
310
+ *
311
+ */
249
312
  Then(/^(I |we )*should( not)* see "([^"]*)?"$/, async function (pronounCase, notCase, expectedText) {
250
313
  if (notCase) {
251
314
  const text = await this.page.locator('body').textContent() || '';
@@ -255,26 +318,40 @@ Then(/^(I |we )*should( not)* see "([^"]*)?"$/, async function (pronounCase, not
255
318
  }
256
319
  });
257
320
 
258
- // ---------------------------------------------------------------------------
259
- // When I move forward one page
260
- // Captures: (pronounCase) = 1
261
- // ---------------------------------------------------------------------------
321
+ /**
322
+ * Moves forward one page in browser history.
323
+ *
324
+ * Example #1: When I move forward one page
325
+ * Example #2: When we move forward one page
326
+ * Example #3: And move forward one page
327
+ *
328
+ */
262
329
  When(/^(I |we )*move forward one page$/, async function (pronounCase) {
263
330
  await this.page.goForward();
264
331
  });
265
332
 
266
- // ---------------------------------------------------------------------------
267
- // When I move backward one page
268
- // Captures: (pronounCase) = 1
269
- // ---------------------------------------------------------------------------
333
+ /**
334
+ * Moves backward one page in browser history.
335
+ *
336
+ * Example #1: When I move backward one page
337
+ * Example #2: When we move backward one page
338
+ * Example #3: And move backward one page
339
+ *
340
+ */
270
341
  When(/^(I |we )*move backward one page$/, async function (pronounCase) {
271
342
  await this.page.goBack();
272
343
  });
273
344
 
274
- // ---------------------------------------------------------------------------
275
- // When I press "Log In" button
276
- // Captures: (pronounCase, theCase, element, buttonCase) = 4
277
- // ---------------------------------------------------------------------------
345
+ /**
346
+ * Press a button, submit input, or link by its visible text.
347
+ *
348
+ * Example #1: When I press "Log In"
349
+ * Example #2: And I press the "Log In" button
350
+ * Example #3: And I press the "Save as" button
351
+ * Example #4: When we press "Submit"
352
+ * Example #5: And press "Cancel"
353
+ *
354
+ */
278
355
  When(/^(I |we )*press( the)* "([^"]*)?"( button)*$/, async function (pronounCase, theCase, element, buttonCase) {
279
356
  const esc = element.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
280
357
  await this.page.locator('button, input[type="button"], input[type="submit"], [role="button"], .btn, a')
@@ -283,18 +360,29 @@ When(/^(I |we )*press( the)* "([^"]*)?"( button)*$/, async function (pronounCase
283
360
  .click();
284
361
  });
285
362
 
286
- // ---------------------------------------------------------------------------
287
- // When I press "btn-pressid" by attr / attribute
288
- // Captures: (pronounCase, attrValue, itsCase, attr, attrWord) = 5
289
- // ---------------------------------------------------------------------------
363
+ /**
364
+ * Press a button by its attribute (id, class, name, placeholder, data-*).
365
+ *
366
+ * Example #1: When I press "btn-pressid" by attr
367
+ * Example #2: When I press "btn-pressid" by attribute
368
+ * Example #3: And I press "Your full name" by "placeholder" attribute
369
+ * Example #4: And I press "Your full name" by its "placeholder" attribute
370
+ * Example #5: And I press "save-name" by "data-selector" attr
371
+ *
372
+ */
290
373
  When(/^(I |we )*press "([^"]*)?" by( its)*(?: "([^"]*)?")* (attribute|attr)$/, async function (pronounCase, attrValue, itsCase, attr, attrWord) {
291
374
  await this.page.locator(buildSelector(attrValue, attr)).first().click();
292
375
  });
293
376
 
294
- // ---------------------------------------------------------------------------
295
- // When I click "Contact Us"
296
- // Captures: (pronounCase, item) = 2
297
- // ---------------------------------------------------------------------------
377
+ /**
378
+ * Click a link or button by its visible text.
379
+ *
380
+ * Example #1: When I click "Contact Us"
381
+ * Example #2: And I click "aboutUs"
382
+ * Example #3: When we click "Read more"
383
+ * Example #4: And click "Home"
384
+ *
385
+ */
298
386
  When(/^(I |we )*click "([^"]*)?"$/, async function (pronounCase, item) {
299
387
  const esc = item.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
300
388
  await this.page.locator('a, button, [role="button"], .btn, input[type="button"], input[type="submit"]')
@@ -303,18 +391,28 @@ When(/^(I |we )*click "([^"]*)?"$/, async function (pronounCase, item) {
303
391
  .click();
304
392
  });
305
393
 
306
- // ---------------------------------------------------------------------------
307
- // When I click "#about-us-id" by attr / attribute
308
- // Captures: (pronounCase, attrValue, itsCase, attr, attrWord) = 5
309
- // ---------------------------------------------------------------------------
394
+ /**
395
+ * Click a link or button by its attribute (id, class, name, data-*).
396
+ *
397
+ * Example #1: When I click "#about-us-id" by attr
398
+ * Example #2: When I click "data-selector-about" by attribute
399
+ * Example #3: And I click "about-us-css" by "class" attr
400
+ * Example #4: And I click "about-us-id" by its "id" attribute
401
+ *
402
+ */
310
403
  When(/^(I |we )*click "([^"]*)?" by( its)*(?: "([^"]*)?")* (attribute|attr)$/, async function (pronounCase, attrValue, itsCase, attr, attrWord) {
311
404
  await this.page.locator(buildSelector(attrValue, attr)).first().click();
312
405
  });
313
406
 
314
- // ---------------------------------------------------------------------------
315
- // When I click "Edit" in the "John Smith" row
316
- // Captures: (pronounCase, clickText, theCase, rowIdentifier) = 4
317
- // ---------------------------------------------------------------------------
407
+ /**
408
+ * Click a clickable element inside a table row identified by text.
409
+ *
410
+ * Example #1: When I click "Edit" in the "John Smith" row
411
+ * Example #2: When I click "Delete" in the "Product A" row
412
+ * Example #3: When we click "View Details" in the "Order #12345" row
413
+ * Example #4: And I click "Download" in the "Report 2024" row
414
+ *
415
+ */
318
416
  When(/^(I |we )*click "([^"]*)?" in( the)* "([^"]*)?" row$/, async function (pronounCase, clickText, theCase, rowIdentifier) {
319
417
  const esc = clickText.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
320
418
  const row = this.page.locator('tr').filter({ hasText: rowIdentifier }).first();
@@ -327,10 +425,18 @@ When(/^(I |we )*click "([^"]*)?" in( the)* "([^"]*)?" row$/, async function (pro
327
425
  }
328
426
  });
329
427
 
330
- // ---------------------------------------------------------------------------
331
- // Then I should see "Active" in the "John Smith" row
332
- // Captures: (pronounCase, notCase, expectedText, theCase, rowIdentifier) = 5
333
- // ---------------------------------------------------------------------------
428
+ /**
429
+ * Assert text is or is not visible inside a table row identified by text.
430
+ *
431
+ * Example #1: Then I should see "Active" in the "John Smith" row
432
+ * Example #2: Then I should see "In Stock" in the "Product A" row
433
+ * Example #3: Then we should see "Processing" in the "Order #12345" row
434
+ * Example #4: And I should see "Admin" in the "john.smith@example.com" row
435
+ * Example #5: Then I should not see "Admin" in the "Jane Doe" row
436
+ * Example #6: Then I should not see "Out of Stock" in the "Product A" row
437
+ * Example #7: And I should not see "Inactive" in the "john.smith@example.com" row
438
+ *
439
+ */
334
440
  Then(/^(I |we )*should( not)* see "([^"]*)?" in( the)* "([^"]*)?" row$/, async function (pronounCase, notCase, expectedText, theCase, rowIdentifier) {
335
441
  const found = await this.page.evaluate(({ id, text }) => {
336
442
  const rows = Array.from(document.querySelectorAll('tr'));
@@ -343,86 +449,138 @@ Then(/^(I |we )*should( not)* see "([^"]*)?" in( the)* "([^"]*)?" row$/, async f
343
449
  }
344
450
  });
345
451
 
346
- // ---------------------------------------------------------------------------
347
- // When I reload the page
348
- // Captures: (pronounCase, theCase, pageCase) = 3
349
- // ---------------------------------------------------------------------------
452
+ /**
453
+ * Reloads the current page.
454
+ *
455
+ * Example #1: When I reload
456
+ * Example #2: And I reload the page
457
+ * Example #3: And we reload page
458
+ * Example #4: And we reload the page
459
+ *
460
+ */
350
461
  When(/^(I |we )*reload( the)*( page)*$/, async function (pronounCase, theCase, pageCase) {
351
462
  await this.page.reload();
352
463
  });
353
464
 
354
- // ---------------------------------------------------------------------------
355
- // When I fill in "Username" with "John Smith"
356
- // Captures: (pronounCase, field, value) = 3
357
- // ---------------------------------------------------------------------------
465
+ /**
466
+ * Fill an input field located by its label, placeholder, or name.
467
+ *
468
+ * Example #1: When I fill in "Username" with "John Smith"
469
+ * Example #2: When I fill in "Email" with "jon@example.com"
470
+ * Example #3: And we fill in "Organization" with "Webship.co"
471
+ * Example #4: And I fill in "Password" with "1234"
472
+ *
473
+ */
358
474
  When(/^(I |we )*fill in "([^"]*)?" with "([^"]*)?"$/, async function (pronounCase, field, value) {
359
475
  await fillField(this.page, field, value);
360
476
  });
361
477
 
362
- // ---------------------------------------------------------------------------
363
- // When I fill in "uname" with "John Smith" by attr
364
- // Captures: (pronounCase, attrValue, txtValue, itsCase, attr, attrWord) = 6
365
- // ---------------------------------------------------------------------------
478
+ /**
479
+ * Fill an input field located by its attribute.
480
+ *
481
+ * Example #1: When I fill in "#uname" with "John Smith" by attr
482
+ * Example #2: When I fill in "uname" with "John Smith" by attr
483
+ * Example #3: And I fill in "pwordcss" with "1234" by "class" attr
484
+ * Example #4: And I fill in "Your full name" with "John Smith" by its "placeholder" attribute
485
+ *
486
+ */
366
487
  When(/^(I |we )*fill in "([^"]*)?" with "([^"]*)?" by( its)*(?: "([^"]*)?")* (attribute|attr)$/, async function (pronounCase, attrValue, txtValue, itsCase, attr, attrWord) {
367
488
  await this.page.locator(buildSelector(attrValue, attr)).first().fill(txtValue);
368
489
  });
369
490
 
370
- // ---------------------------------------------------------------------------
371
- // When I fill in "Username" with: (empty)
372
- // Captures: (pronounCase, field) = 2
373
- // ---------------------------------------------------------------------------
491
+ /**
492
+ * Clear an input field located by its label.
493
+ *
494
+ * Example #1: When I fill in "Username" with:
495
+ * Example #2: And we fill in "Email" with:
496
+ * Example #3: And I fill in "Password" with:
497
+ *
498
+ */
374
499
  When(/^(I |we )*fill in "([^"]*)?" with:$/, async function (pronounCase, field) {
375
500
  await fillField(this.page, field, '');
376
501
  });
377
502
 
378
- // ---------------------------------------------------------------------------
379
- // When I fill in "uname" with: by attr (empty by attr)
380
- // Captures: (pronounCase, attrValue, itsCase, attr, attrWord) = 5
381
- // ---------------------------------------------------------------------------
503
+ /**
504
+ * Clear an input field located by its attribute.
505
+ *
506
+ * Example #1: When I fill in "#uname" with: by attr
507
+ * Example #2: When I fill in "uname" with: by attr
508
+ * Example #3: And I fill in "pwordcss" with: by "class" attr
509
+ * Example #4: And I fill in "Your full name" with: by its "placeholder" attribute
510
+ *
511
+ */
382
512
  When(/^(I |we )*fill in "([^"]*)?" with: by( its)*(?: "([^"]*)?")* (attribute|attr)$/, async function (pronounCase, attrValue, itsCase, attr, attrWord) {
383
513
  await this.page.locator(buildSelector(attrValue, attr)).first().fill('');
384
514
  });
385
515
 
386
- // ---------------------------------------------------------------------------
387
- // When I fill in "John Smith" for "Username"
388
- // Captures: (pronounCase, value, field) = 3
389
- // ---------------------------------------------------------------------------
516
+ /**
517
+ * Fill an input field located by label (reverse syntax).
518
+ *
519
+ * Example #1: When I fill in "jon-smith" for "Username"
520
+ * Example #2: When we fill in "Testing" for "Organization options"
521
+ * Example #3: And I fill in "1234" for "Password"
522
+ *
523
+ */
390
524
  When(/^(I |we )*fill in "([^"]*)?" for "([^"]*)?"$/, async function (pronounCase, value, field) {
391
525
  await fillField(this.page, field, value);
392
526
  });
393
527
 
394
- // ---------------------------------------------------------------------------
395
- // When I fill in "John Smith" for "uname" by attr
396
- // Captures: (pronounCase, txtValue, attrValue, itsCase, attr, attrWord) = 6
397
- // ---------------------------------------------------------------------------
528
+ /**
529
+ * Fill an input field located by attribute (reverse syntax).
530
+ *
531
+ * Example #1: When I fill in "John Smith" for "#uname" by attr
532
+ * Example #2: When I fill in "John Smith" for "uname" by attr
533
+ * Example #3: And I fill in "1234" for "password" by "class" attr
534
+ * Example #4: And I fill in "John Smith" for "Your full name" by its "placeholder" attribute
535
+ *
536
+ */
398
537
  When(/^(I |we )*fill in "([^"]*)?" for "([^"]*)?" by( its)*(?: "([^"]*)?")* (attribute|attr)$/, async function (pronounCase, txtValue, attrValue, itsCase, attr, attrWord) {
399
538
  await this.page.locator(buildSelector(attrValue, attr)).first().fill(txtValue);
400
539
  });
401
540
 
402
- // ---------------------------------------------------------------------------
403
- // When I fill in the following: (table by label)
404
- // Captures: (pronounCase, theCase) = 2
405
- // ---------------------------------------------------------------------------
541
+ /**
542
+ * Fills multiple form fields from a data table, located by their labels.
543
+ *
544
+ * Example #1: When I fill in the following:
545
+ * | Username | webshipco |
546
+ * | Password | 1234 |
547
+ * Example #2: And we fill in the following:
548
+ * | Email | jon@example.com |
549
+ * | Organization | Webship.co |
550
+ *
551
+ */
406
552
  When(/^(I |we )*fill in( the)* following:$/, async function (pronounCase, theCase, table) {
407
553
  for (const [field, value] of table.raw()) {
408
554
  await fillField(this.page, field, value);
409
555
  }
410
556
  });
411
557
 
412
- // ---------------------------------------------------------------------------
413
- // When I fill in the following: by attr (table by attribute)
414
- // Captures: (pronounCase, theCase, itsCase, attr, attrWord) = 5
415
- // ---------------------------------------------------------------------------
558
+ /**
559
+ * Fills multiple form fields from a data table, located by their attributes.
560
+ *
561
+ * Example #1: When I fill in the following: by attr
562
+ * | #uname | John Smith |
563
+ * | password | 1234 |
564
+ * Example #2: When I fill in the following: by its "placeholder" attribute
565
+ * | Your full name | John Smith |
566
+ * | Your Password | 1234 |
567
+ *
568
+ */
416
569
  When(/^(I |we )*fill in( the)* following: by( its)*(?: "([^"]*)?")* (attribute|attr)$/, async function (pronounCase, theCase, itsCase, attr, attrWord, table) {
417
570
  for (const [attrValue, value] of table.raw()) {
418
571
  await this.page.locator(buildSelector(attrValue, attr)).first().fill(value);
419
572
  }
420
573
  });
421
574
 
422
- // ---------------------------------------------------------------------------
423
- // When I select "Mercedes" from "Cars"
424
- // Captures: (pronounCase, option, selectList) = 3
425
- // ---------------------------------------------------------------------------
575
+ /**
576
+ * Select an option from a dropdown by label, id, class, or name.
577
+ *
578
+ * Example #1: When I select "Mercedes" from "Cars"
579
+ * Example #2: When I select "saab" from "#cars"
580
+ * Example #3: When I select "Mercedes" from "cars"
581
+ * Example #4: And we select "English" from "Language"
582
+ *
583
+ */
426
584
  When(/^(I |we )*select "([^"]*)?" from "([^"]*)?"$/, async function (pronounCase, option, selectList) {
427
585
  let loc;
428
586
  if (selectList.startsWith('#') || selectList.startsWith('.')) {
@@ -439,10 +597,65 @@ When(/^(I |we )*select "([^"]*)?" from "([^"]*)?"$/, async function (pronounCase
439
597
  }
440
598
  });
441
599
 
442
- // ---------------------------------------------------------------------------
443
- // When I check "Remember me"
444
- // Captures: (pronounCase, item) = 2
445
- // ---------------------------------------------------------------------------
600
+ /**
601
+ * Add an option to a <select multiple> without clearing the existing selection.
602
+ * Resolves the select by label, then by [name]/#id fallback.
603
+ *
604
+ * Example #1: When I additionally select "Red" from "Colors"
605
+ * Example #2: When I additionally select "Blue" from "Colors"
606
+ * Example #3: When we additionally select "Green" from "Colors"
607
+ * Example #4: And additionally select "Yellow" from "Colors"
608
+ * Example #5: When I additionally select "Admin" from "Roles"
609
+ * Example #6: When we additionally select "Editor" from "Roles"
610
+ * Example #7: When I additionally select "Viewer" from "Roles"
611
+ * Example #8: And I additionally select "EN" from "Languages"
612
+ * Example #9: When I additionally select "FR" from "Languages"
613
+ * Example #10: When we additionally select "ES" from "Languages"
614
+ *
615
+ * Advanced:
616
+ * Example #11: Build a full multi-selection in sequence:
617
+ * When I select "Red" from "Colors"
618
+ * And I additionally select "Blue" from "Colors"
619
+ * And I additionally select "Green" from "Colors"
620
+ * Example #12: Works against a [name] select:
621
+ * When I additionally select "tag-a" from "tags"
622
+ * And I additionally select "tag-b" from "tags"
623
+ * Example #13: Confirm the select stays multi-valued after adds:
624
+ * When I select "One" from "Items"
625
+ * And I additionally select "Two" from "Items"
626
+ */
627
+ When(/^(I |we )*additionally select "([^"]*)" from "([^"]*)"$/, async function (pronounCase, option, select) {
628
+ const loc = this.page.getByLabel(select).or(
629
+ this.page.locator(`select[name="${select}"], select#${select}`)
630
+ ).first();
631
+
632
+ const currentValues = await loc.evaluate((el) => {
633
+ if (!el || !el.selectedOptions) return [];
634
+ return Array.from(el.selectedOptions).map((o) => o.value);
635
+ });
636
+
637
+ const nextValueForLabel = await loc.evaluate((el, label) => {
638
+ const opt = Array.from(el.options || []).find((o) => o.label === label || o.text === label);
639
+ return opt ? opt.value : null;
640
+ }, option);
641
+
642
+ if (nextValueForLabel === null) {
643
+ throw new Error(`Option "${option}" not found in select "${select}".`);
644
+ }
645
+
646
+ const combined = Array.from(new Set([...currentValues, nextValueForLabel]));
647
+ await loc.selectOption(combined);
648
+ });
649
+
650
+ /**
651
+ * Checks the specified checkbox by label, id, class, or name.
652
+ *
653
+ * Example #1: When I check "Remember me"
654
+ * Example #2: When we check "Put site into maintenance mode"
655
+ * Example #3: And I check "#newsletter"
656
+ * Example #4: And we check ".terms-and-conditions"
657
+ *
658
+ */
446
659
  When(/^(I |we )*check "([^"]*)?"$/, async function (pronounCase, item) {
447
660
  if (item.startsWith('#') || item.startsWith('.')) {
448
661
  await this.page.locator(item).check();
@@ -456,10 +669,15 @@ When(/^(I |we )*check "([^"]*)?"$/, async function (pronounCase, item) {
456
669
  }
457
670
  });
458
671
 
459
- // ---------------------------------------------------------------------------
460
- // When I uncheck "Remember me"
461
- // Captures: (pronounCase, item) = 2
462
- // ---------------------------------------------------------------------------
672
+ /**
673
+ * Unchecks the specified checkbox by label, id, class, or name.
674
+ *
675
+ * Example #1: When I uncheck "Remember me"
676
+ * Example #2: When we uncheck "Put site into maintenance mode"
677
+ * Example #3: And I uncheck "#newsletter"
678
+ * Example #4: And we uncheck ".terms-and-conditions"
679
+ *
680
+ */
463
681
  When(/^(I |we )*uncheck "([^"]*)?"$/, async function (pronounCase, item) {
464
682
  if (item.startsWith('#') || item.startsWith('.')) {
465
683
  await this.page.locator(item).uncheck();
@@ -473,10 +691,15 @@ When(/^(I |we )*uncheck "([^"]*)?"$/, async function (pronounCase, item) {
473
691
  }
474
692
  });
475
693
 
476
- // ---------------------------------------------------------------------------
477
- // When I select radio button "Male"
478
- // Captures: (pronounCase, item) = 2
479
- // ---------------------------------------------------------------------------
694
+ /**
695
+ * Selects a radio button by label, value, id, or class.
696
+ *
697
+ * Example #1: When I select radio button "Male"
698
+ * Example #2: When I select radio button "female"
699
+ * Example #3: When I select radio button "#gender-male"
700
+ * Example #4: When we select radio button "option1"
701
+ *
702
+ */
480
703
  When(/^(I |we )*select radio button "([^"]*)?"$/, async function (pronounCase, item) {
481
704
  if (item.startsWith('#') || item.startsWith('.')) {
482
705
  await this.page.locator(item).check();
@@ -490,10 +713,21 @@ When(/^(I |we )*select radio button "([^"]*)?"$/, async function (pronounCase, i
490
713
  }
491
714
  });
492
715
 
493
- // ---------------------------------------------------------------------------
494
- // Then I should be on homepage / frontpage
495
- // Captures: (pronounCase, notCase, theCase, pageCase) = 4
496
- // ---------------------------------------------------------------------------
716
+ /**
717
+ * Assert that the current page is or is not the homepage.
718
+ *
719
+ * Example #1: Then I should be on homepage
720
+ * Example #2: And I should be on the homepage
721
+ * Example #3: Then I should be on frontpage
722
+ * Example #4: And should be on the homepage
723
+ * Example #5: Then should be on homepage
724
+ * Example #6: And we should be on homepage
725
+ * Example #7: Then should be on frontpage
726
+ * Example #8: And we should be on the homepage
727
+ * Example #9: Then I should not be on homepage
728
+ * Example #10: And I should not be on the homepage
729
+ *
730
+ */
497
731
  Then(/^(I |we )*should( not)* be on( the)* (homepage|frontpage)$/, async function (pronounCase, notCase, theCase, pageCase) {
498
732
  const currentUrl = this.page.url();
499
733
  if (notCase) {
@@ -505,10 +739,21 @@ Then(/^(I |we )*should( not)* be on( the)* (homepage|frontpage)$/, async functio
505
739
  }
506
740
  });
507
741
 
508
- // ---------------------------------------------------------------------------
509
- // Then I should be on "/user/login"
510
- // Captures: (pronounCase, notCase, theCase, url, pageCase) = 5
511
- // ---------------------------------------------------------------------------
742
+ /**
743
+ * Assert that the current path is or is not equal to the specified path.
744
+ *
745
+ * Example #1: Then I should be on "/"
746
+ * Example #2: And I should be on "/user/login"
747
+ * Example #3: And I should be on "https://un.org"
748
+ * Example #4: Then we should be on the "/" page
749
+ * Example #5: And we should be on "/user/login"
750
+ * Example #6: Then should be on the "/user/reset" page
751
+ * Example #7: Then I should not be on "/"
752
+ * Example #8: And I should not be on "/user/login"
753
+ * Example #9: And I should not be on "https://un.org"
754
+ * Example #10: And we should not be on the "https://un.org" page
755
+ *
756
+ */
512
757
  Then(/^(I |we )*should( not)* be on( the)* "([^"]*)?"( page)*$/, async function (pronounCase, notCase, theCase, url, pageCase) {
513
758
  const currentUrl = this.page.url();
514
759
  if (notCase) {
@@ -518,10 +763,14 @@ Then(/^(I |we )*should( not)* be on( the)* "([^"]*)?"( page)*$/, async function
518
763
  }
519
764
  });
520
765
 
521
- // ---------------------------------------------------------------------------
522
- // Then the "Login" link should contain "/log-in"
523
- // Captures: (theCase, element, url) = 3
524
- // ---------------------------------------------------------------------------
766
+ /**
767
+ * Assert that a link (located by its visible text) contains the given URL.
768
+ *
769
+ * Example #1: Then the "Login" link should contain "/log-in"
770
+ * Example #2: And the "About Us" link should contain "/about"
771
+ * Example #3: Then "Home" link should contain "/"
772
+ *
773
+ */
525
774
  Then(/^(the )*"([^"]*)?" link should contain "([^"]*)?"$/, async function (theCase, element, url) {
526
775
  const loc = this.page.getByText(element, { exact: true }).first();
527
776
  await loc.waitFor({ timeout: 5000 });
@@ -529,10 +778,14 @@ Then(/^(the )*"([^"]*)?" link should contain "([^"]*)?"$/, async function (theCa
529
778
  assert.ok(href.includes(url), `Expected link "${element}" href to contain "${url}" but got "${href}"`);
530
779
  });
531
780
 
532
- // ---------------------------------------------------------------------------
533
- // Then the "#about-us-id" link should contain "about" by attr
534
- // Captures: (theCase, attrValue, url, itsCase, attr, attrWord) = 6
535
- // ---------------------------------------------------------------------------
781
+ /**
782
+ * Assert that a link located by its attribute contains the given URL.
783
+ *
784
+ * Example #1: Then the "#about-us-id" link should contain "about" by attr
785
+ * Example #2: And the "aboutUs" link should contain "about" by its "class" attribute
786
+ * Example #3: And the ".contactUs" link should contain "/contact-" by attr
787
+ *
788
+ */
536
789
  Then(/^(the )*"([^"]*)?" link should contain "([^"]*)?" by( its)*(?: "([^"]*)?")* (attribute|attr)$/, async function (theCase, attrValue, url, itsCase, attr, attrWord) {
537
790
  const loc = this.page.locator(buildSelector(attrValue, attr)).first();
538
791
  await loc.waitFor({ timeout: 5000 });
@@ -540,10 +793,13 @@ Then(/^(the )*"([^"]*)?" link should contain "([^"]*)?" by( its)*(?: "([^"]*)?")
540
793
  assert.ok(href.includes(url), `Expected element href to contain "${url}" but got "${href}"`);
541
794
  });
542
795
 
543
- // ---------------------------------------------------------------------------
544
- // Then the response should contain "text"
545
- // Captures: (theCase, notCase, expectedText) = 3
546
- // ---------------------------------------------------------------------------
796
+ /**
797
+ * Assert that HTML response contains or does not contain specific text.
798
+ *
799
+ * Example #1: Then the response should contain "Welcome visitor, How can I help you?"
800
+ * Example #2: Then the response should not contain "Access denied"
801
+ *
802
+ */
547
803
  Then(/^(the )*response should( not)* contain "([^"]*)?"$/, async function (theCase, notCase, expectedText) {
548
804
  const text = await this.page.locator('html').textContent() || '';
549
805
  if (notCase) {
@@ -553,10 +809,14 @@ Then(/^(the )*response should( not)* contain "([^"]*)?"$/, async function (theCa
553
809
  }
554
810
  });
555
811
 
556
- // ---------------------------------------------------------------------------
557
- // Then I should see "John Smith" in the "Username" element
558
- // Captures: (pronounCase, notCase, expectedText, theCase, element) = 5
559
- // ---------------------------------------------------------------------------
812
+ /**
813
+ * Assert that an element (found by its label) contains or does not contain text.
814
+ *
815
+ * Example #1: Then I should see "John Smith" in the "Username" element
816
+ * Example #2: Then I should not see "Joe Smith" in the "Username" element
817
+ * Example #3: And we should see "1234" in the "Password" element
818
+ *
819
+ */
560
820
  Then(/^(I |we )*should( not)* see "([^"]*)?" in( the)* "([^"]*)?" element$/, async function (pronounCase, notCase, expectedText, theCase, element) {
561
821
  const forAttr = await this.page.getByText(element, { exact: true }).getAttribute('for').catch(() => null);
562
822
  const loc = this.page.locator(forAttr ? '#' + forAttr : element).first();
@@ -569,10 +829,15 @@ Then(/^(I |we )*should( not)* see "([^"]*)?" in( the)* "([^"]*)?" element$/, asy
569
829
  }
570
830
  });
571
831
 
572
- // ---------------------------------------------------------------------------
573
- // Then I should see "John Smith" in the "uname" element by attr
574
- // Captures: (pronounCase, notCase, expectedText, theCase, attrValue, itsCase, attr, attrWord) = 8
575
- // ---------------------------------------------------------------------------
832
+ /**
833
+ * Assert that an element (found by its attribute) contains or does not contain text.
834
+ *
835
+ * Example #1: Then I should see "John Smith" in the "uname" element by its "id" attr
836
+ * Example #2: Then I should see "1234" in the "pwordcss" element by attr
837
+ * Example #3: Then I should not see "John Smith" in the "uname" element by its "id" attr
838
+ * Example #4: Then I should not see "1234" in the "pwordcss" element by attr
839
+ *
840
+ */
576
841
  Then(/^(I |we )*should( not)* see "([^"]*)?" in( the)* "([^"]*)?" element by( its)*(?: "([^"]*)?")* (attribute|attr)$/, async function (pronounCase, notCase, expectedText, theCase, attrValue, itsCase, attr, attrWord) {
577
842
  const loc = this.page.locator(buildSelector(attrValue, attr)).first();
578
843
  await loc.waitFor({ timeout: 10000 });
@@ -584,10 +849,14 @@ Then(/^(I |we )*should( not)* see "([^"]*)?" in( the)* "([^"]*)?" element by( it
584
849
  }
585
850
  });
586
851
 
587
- // ---------------------------------------------------------------------------
588
- // Then I should see a "Username" element
589
- // Captures: (pronounCase, notCase, aAnCase, element) = 4
590
- // ---------------------------------------------------------------------------
852
+ /**
853
+ * Assert that an element with a given label exists (or does not) on the page.
854
+ *
855
+ * Example #1: Then I should see a "Username" element
856
+ * Example #2: Then I should not see a "Username" element
857
+ * Example #3: And we should see an "Email" element
858
+ *
859
+ */
591
860
  Then(/^(I |we )*should( not)* see (a|an) "([^"]*)?" element$/, async function (pronounCase, notCase, aAnCase, element) {
592
861
  if (notCase) {
593
862
  const text = await this.page.locator('body').textContent() || '';
@@ -603,10 +872,15 @@ Then(/^(I |we )*should( not)* see (a|an) "([^"]*)?" element$/, async function (p
603
872
  }
604
873
  });
605
874
 
606
- // ---------------------------------------------------------------------------
607
- // Then I should see a "uname" element by attr
608
- // Captures: (pronounCase, notCase, aAnCase, attrValue, itsCase, attr, attrWord) = 7
609
- // ---------------------------------------------------------------------------
875
+ /**
876
+ * Assert that an element, identified by attribute, exists (or does not) on the page.
877
+ *
878
+ * Example #1: Then I should see a "uname" element by its "id" attr
879
+ * Example #2: Then I should see a "pwordcss" element by attr
880
+ * Example #3: Then I should not see an "emailId" element by its "id" attr
881
+ * Example #4: And I should not see a "countryCss" element by attr
882
+ *
883
+ */
610
884
  Then(/^(I |we )*should( not)* see (a|an) "([^"]*)?" element by( its)*(?: "([^"]*)?")* (attribute|attr)$/, async function (pronounCase, notCase, aAnCase, attrValue, itsCase, attr, attrWord) {
611
885
  const loc = this.page.locator(buildSelector(attrValue, attr));
612
886
  if (notCase) {
@@ -616,10 +890,15 @@ Then(/^(I |we )*should( not)* see (a|an) "([^"]*)?" element by( its)*(?: "([^"]*
616
890
  }
617
891
  });
618
892
 
619
- // ---------------------------------------------------------------------------
620
- // Then the "body" element should contain "color:white;"
621
- // Captures: (theCase, selectorRaw, notCase, elementCss) = 4
622
- // ---------------------------------------------------------------------------
893
+ /**
894
+ * Assert that an element has or does not have a specific CSS property.
895
+ *
896
+ * Example #1: Then the "body" element should contain "color:white;"
897
+ * Example #2: Then the "body" element should not contain "color:white;"
898
+ * Example #3: Then the "#uname" element should not contain "border:solid 5px red;"
899
+ * Example #4: Then the "pword" element should not contain "font-size: 26px;"
900
+ *
901
+ */
623
902
  Then(/^(the )*"([^"]*)?" element should( not)* contain "([^"]*)?"$/, async function (theCase, selectorRaw, notCase, elementCss) {
624
903
  const cssClean = elementCss.replace(/;$/, '');
625
904
  const colonIdx = cssClean.indexOf(':');
@@ -662,10 +941,14 @@ Then(/^(the )*"([^"]*)?" element should( not)* contain "([^"]*)?"$/, async funct
662
941
  }
663
942
  });
664
943
 
665
- // ---------------------------------------------------------------------------
666
- // Then the "Username" field should contain "John Smith"
667
- // Captures: (theCase, field, notCase, expectedText) = 4
668
- // ---------------------------------------------------------------------------
944
+ /**
945
+ * Assert that a form field contains or does not contain specific text.
946
+ *
947
+ * Example #1: Then the "Username" field should contain "John Smith"
948
+ * Example #2: Then the "#username" field should not contain "John Smith"
949
+ * Example #3: And the "Email" field should contain "jon@example.com"
950
+ *
951
+ */
669
952
  Then(/^(the )*"([^"]*)?" field should( not)* contain "([^"]*)?"$/, async function (theCase, field, notCase, expectedText) {
670
953
  let selector = field;
671
954
  if (!field.startsWith('#') && !field.startsWith('.')) {
@@ -682,10 +965,13 @@ Then(/^(the )*"([^"]*)?" field should( not)* contain "([^"]*)?"$/, async functio
682
965
  }
683
966
  });
684
967
 
685
- // ---------------------------------------------------------------------------
686
- // Then the "#PrivacyPolicy" checkbox should be checked
687
- // Captures: (theCase, checkbox, notCase) = 3
688
- // ---------------------------------------------------------------------------
968
+ /**
969
+ * Assert that a checkbox should or should not be checked.
970
+ *
971
+ * Example #1: Then the "#PrivacyPolicy" checkbox should be checked
972
+ * Example #2: Then the "#PrivacyPolicy" checkbox should not be checked
973
+ *
974
+ */
689
975
  Then(/^(the )*"([^"]*)?" checkbox should( not)* be checked$/, async function (theCase, checkbox, notCase) {
690
976
  const isChecked = await this.page.locator(checkbox).isChecked();
691
977
  if (notCase) {
@@ -695,10 +981,13 @@ Then(/^(the )*"([^"]*)?" checkbox should( not)* be checked$/, async function (th
695
981
  }
696
982
  });
697
983
 
698
- // ---------------------------------------------------------------------------
699
- // Then the "#rememberMe" checkbox is checked
700
- // Captures: (theCase, checkbox, notCase) = 3
701
- // ---------------------------------------------------------------------------
984
+ /**
985
+ * Assert that a checkbox is or is not checked.
986
+ *
987
+ * Example #1: Then the "#rememberMe" checkbox is checked
988
+ * Example #2: Then the "#rememberMe" checkbox is not checked
989
+ *
990
+ */
702
991
  Then(/^(the )*"([^"]*)?" checkbox is( not)* checked$/, async function (theCase, checkbox, notCase) {
703
992
  const isChecked = await this.page.locator(checkbox).isChecked();
704
993
  if (notCase) {
@@ -708,10 +997,13 @@ Then(/^(the )*"([^"]*)?" checkbox is( not)* checked$/, async function (theCase,
708
997
  }
709
998
  });
710
999
 
711
- // ---------------------------------------------------------------------------
712
- // Then the checkbox "#PrivacyPolicy" should be checked
713
- // Captures: (theCase, checkbox, notCase) = 3
714
- // ---------------------------------------------------------------------------
1000
+ /**
1001
+ * Assert that a named checkbox should or should not be checked.
1002
+ *
1003
+ * Example #1: Then the checkbox "#PrivacyPolicy" should be checked
1004
+ * Example #2: Then the checkbox "#PrivacyPolicy" should not be checked
1005
+ *
1006
+ */
715
1007
  Then(/^(the )*checkbox "([^"]*)?" should( not)* be checked$/, async function (theCase, checkbox, notCase) {
716
1008
  const isChecked = await this.page.locator(checkbox).isChecked();
717
1009
  if (notCase) {
@@ -721,10 +1013,13 @@ Then(/^(the )*checkbox "([^"]*)?" should( not)* be checked$/, async function (th
721
1013
  }
722
1014
  });
723
1015
 
724
- // ---------------------------------------------------------------------------
725
- // Then the checkbox "#rememberMe" is checked
726
- // Captures: (theCase, checkbox, notCase) = 3
727
- // ---------------------------------------------------------------------------
1016
+ /**
1017
+ * Assert that a named checkbox is or is not checked.
1018
+ *
1019
+ * Example #1: Then the checkbox "#rememberMe" is checked
1020
+ * Example #2: Then the checkbox "#rememberMe" is not checked
1021
+ *
1022
+ */
728
1023
  Then(/^(the )*checkbox "([^"]*)?" is( not)* checked$/, async function (theCase, checkbox, notCase) {
729
1024
  const isChecked = await this.page.locator(checkbox).isChecked();
730
1025
  if (notCase) {
@@ -734,10 +1029,14 @@ Then(/^(the )*checkbox "([^"]*)?" is( not)* checked$/, async function (theCase,
734
1029
  }
735
1030
  });
736
1031
 
737
- // ---------------------------------------------------------------------------
738
- // Then the radio button "#gender-male" should be selected
739
- // Captures: (theCase, radioButton, notCase) = 3
740
- // ---------------------------------------------------------------------------
1032
+ /**
1033
+ * Assert that a radio button should or should not be selected.
1034
+ *
1035
+ * Example #1: Then the radio button "#gender-male" should be selected
1036
+ * Example #2: Then the radio button "#gender-female" should not be selected
1037
+ * Example #3: Then the radio button ".option-1" should be selected
1038
+ *
1039
+ */
741
1040
  Then(/^(the )*radio button "([^"]*)?" should( not)* be selected$/, async function (theCase, radioButton, notCase) {
742
1041
  const isChecked = await this.page.locator(radioButton).isChecked();
743
1042
  if (notCase) {
@@ -747,10 +1046,13 @@ Then(/^(the )*radio button "([^"]*)?" should( not)* be selected$/, async functio
747
1046
  }
748
1047
  });
749
1048
 
750
- // ---------------------------------------------------------------------------
751
- // Then the radio button with value "male" should be selected
752
- // Captures: (theCase, radioValue, notCase) = 3
753
- // ---------------------------------------------------------------------------
1049
+ /**
1050
+ * Assert that a radio button with a given value should or should not be selected.
1051
+ *
1052
+ * Example #1: Then the radio button with value "male" should be selected
1053
+ * Example #2: Then the radio button with value "female" should not be selected
1054
+ *
1055
+ */
754
1056
  Then(/^(the )*radio button with value "([^"]*)?" should( not)* be selected$/, async function (theCase, radioValue, notCase) {
755
1057
  const isChecked = await this.page.locator(`input[type="radio"][value="${radioValue}"]`).first().isChecked();
756
1058
  if (notCase) {
@@ -760,10 +1062,13 @@ Then(/^(the )*radio button with value "([^"]*)?" should( not)* be selected$/, as
760
1062
  }
761
1063
  });
762
1064
 
763
- // ---------------------------------------------------------------------------
764
- // Then the "#gender-male" radio button is selected
765
- // Captures: (theCase, radioButton, notCase) = 3
766
- // ---------------------------------------------------------------------------
1065
+ /**
1066
+ * Assert that the radio button is or is not selected.
1067
+ *
1068
+ * Example #1: Then the "#gender-male" radio button is selected
1069
+ * Example #2: Then the "#gender-female" radio button is not selected
1070
+ *
1071
+ */
767
1072
  Then(/^(the )*"([^"]*)?" radio button is( not)* selected$/, async function (theCase, radioButton, notCase) {
768
1073
  const isChecked = await this.page.locator(radioButton).isChecked();
769
1074
  if (notCase) {
@@ -773,10 +1078,14 @@ Then(/^(the )*"([^"]*)?" radio button is( not)* selected$/, async function (theC
773
1078
  }
774
1079
  });
775
1080
 
776
- // ---------------------------------------------------------------------------
777
- // Then the response status code should be 200
778
- // Captures: (theCase, notCase, expectedStatusCode) = 3
779
- // ---------------------------------------------------------------------------
1081
+ /**
1082
+ * Assert that the current page's response status is or is not a given code.
1083
+ *
1084
+ * Example #1: Then the response status code should be 200
1085
+ * Example #2: And the response status code should not be 404
1086
+ * Example #3: Then the response status code should be 301
1087
+ *
1088
+ */
780
1089
  Then(/^(the )*response status code should( not)* be (\d+)$/, async function (theCase, notCase, expectedStatusCode) {
781
1090
  const currentURL = this.page.url();
782
1091
  try {
@@ -797,10 +1106,14 @@ Then(/^(the )*response status code should( not)* be (\d+)$/, async function (the
797
1106
  }
798
1107
  });
799
1108
 
800
- // ---------------------------------------------------------------------------
801
- // Then I should see text matching "^T\w+"
802
- // Captures: (pronounCase, notCase, textPattern) = 3
803
- // ---------------------------------------------------------------------------
1109
+ /**
1110
+ * Assert that page contains or does not contain text matching a regex pattern.
1111
+ *
1112
+ * Example #1: Then I should see text matching "^T\w+"
1113
+ * Example #2: Then I should not see text matching "^O\w+"
1114
+ * Example #3: And we should see text matching "\d{4}"
1115
+ *
1116
+ */
804
1117
  Then(/^(I |we )*should( not)* see text matching "([^"]*)?"$/, async function (pronounCase, notCase, textPattern) {
805
1118
  const bodyText = await this.page.evaluate(() => document.body.innerText || '');
806
1119
  const regex = new RegExp(textPattern);
@@ -811,10 +1124,13 @@ Then(/^(I |we )*should( not)* see text matching "([^"]*)?"$/, async function (pr
811
1124
  }
812
1125
  });
813
1126
 
814
- // ---------------------------------------------------------------------------
815
- // Then I should see text matching "..." in the "#date" element
816
- // Captures: (pronounCase, notCase, textPattern, theCase, element) = 5
817
- // ---------------------------------------------------------------------------
1127
+ /**
1128
+ * Assert that an element contains or does not contain text matching a pattern.
1129
+ *
1130
+ * Example #1: Then I should see text matching "(0?[1-9]|[12][0-9]|3[01])[\/\-](0?[1-9]|1[012])[\/\-]\d{4}" in the "#date" element
1131
+ * Example #2: Then I should not see text matching "(0?[1-9]|[12][0-9]|3[01])[\/\-](0?[1-9]|1[012])[\/\-]\d{4}" in the "#date" element
1132
+ *
1133
+ */
818
1134
  Then(/^(I |we )*should( not)* see text matching "([^"]*)?" in( the)* "([^"]*)?" element$/, async function (pronounCase, notCase, textPattern, theCase, element) {
819
1135
  const loc = this.page.locator(element).first();
820
1136
  await loc.waitFor({ timeout: 5000 });
@@ -827,10 +1143,14 @@ Then(/^(I |we )*should( not)* see text matching "([^"]*)?" in( the)* "([^"]*)?"
827
1143
  }
828
1144
  });
829
1145
 
830
- // ---------------------------------------------------------------------------
831
- // Then the url should match "/contact-us.html"
832
- // Captures: (theCase, notCase, pattern) = 3
833
- // ---------------------------------------------------------------------------
1146
+ /**
1147
+ * Assert that the current URL matches or does not match a regex pattern.
1148
+ *
1149
+ * Example #1: Then the url should match "/contact-us.html"
1150
+ * Example #2: Then the url should not match "/contact-us.html"
1151
+ * Example #3: And the url should match "^https://"
1152
+ *
1153
+ */
834
1154
  Then(/^(the )*url should( not)* match "([^"]*)?"$/, async function (theCase, notCase, pattern) {
835
1155
  const currentUrl = this.page.url();
836
1156
  const regex = new RegExp(pattern);
@@ -841,77 +1161,152 @@ Then(/^(the )*url should( not)* match "([^"]*)?"$/, async function (theCase, not
841
1161
  }
842
1162
  });
843
1163
 
844
- // ---------------------------------------------------------------------------
845
- // When I attach the file "profileIcon.jpg" to "#profile-icon-upload"
846
- // Captures: (pronounCase, theCase, fileName, element) = 4
847
- // ---------------------------------------------------------------------------
1164
+ /**
1165
+ * Attach a file from tests/assets/ to a file input.
1166
+ *
1167
+ * Example #1: When I attach the file "profileIcon.jpg" to "#profile-icon-upload"
1168
+ * Example #2: And we attach file "resume.pdf" to "#resume"
1169
+ *
1170
+ */
848
1171
  When(/^(I |we )*attach( the)* file "([^"]*)?" to "([^"]*)?"$/, async function (pronounCase, theCase, fileName, element) {
849
1172
  await this.page.locator(element).setInputFiles(path.resolve(this.assetsFolder, fileName));
850
1173
  });
851
1174
 
852
- // ---------------------------------------------------------------------------
853
- // When I wait 1 second / 5 seconds
854
- // Captures: (pronounCase, number, withSecondWord) = 3
855
- // ---------------------------------------------------------------------------
1175
+ /**
1176
+ * Wait a specific number of seconds.
1177
+ *
1178
+ * Example #1: When I wait 1 second
1179
+ * Example #2: When I wait 5 seconds
1180
+ * Example #3: When we wait 3s
1181
+ * Example #4: And wait 2s
1182
+ * Example #5: And wait 2 seconds
1183
+ * Example #6: When we wait 1 second
1184
+ * Example #7: When we wait 5 seconds
1185
+ * Example #8: When we wait 4s
1186
+ *
1187
+ */
856
1188
  When(/^(I |we )*wait (\d*)( second| seconds|s)?$/, async function (pronounCase, number, withSecondWord) {
857
1189
  await this.page.waitForTimeout(parseInt(number) * 1000);
858
1190
  });
859
1191
 
860
- // ---------------------------------------------------------------------------
861
- // When I wait max of 5 seconds
862
- // Captures: (pronounCase, number, withSecondWord) = 3
863
- // ---------------------------------------------------------------------------
1192
+ /**
1193
+ * Wait a max number of seconds until the page body is present.
1194
+ *
1195
+ * Example #1: When I wait max of 1 second
1196
+ * Example #2: When I wait max of 5 seconds
1197
+ * Example #3: When we wait max of 3s
1198
+ * Example #4: And wait max of 2s
1199
+ * Example #5: And wait max of 2 seconds
1200
+ * Example #6: When we wait max of 1 second
1201
+ * Example #7: When we wait max of 5 seconds
1202
+ * Example #8: When we wait max of 4s
1203
+ *
1204
+ */
864
1205
  When(/^(I |we )*wait max of (\d*)( second| seconds|s)?$/, async function (pronounCase, number, withSecondWord) {
865
1206
  await this.page.waitForTimeout(parseInt(number) * 1000);
866
1207
  });
867
1208
 
868
- // ---------------------------------------------------------------------------
869
- // When I wait 1 minute
870
- // Captures: (pronounCase, number, withMinuteWord) = 3
871
- // ---------------------------------------------------------------------------
1209
+ /**
1210
+ * Wait a specific number of minutes.
1211
+ *
1212
+ * Example #1: When I wait 1 minute
1213
+ * Example #2: When I wait 10 minutes
1214
+ * Example #3: When we wait 1m
1215
+ * Example #4: And wait 2m
1216
+ * Example #5: And wait 2 minutes
1217
+ * Example #6: When we wait 1 minute
1218
+ * Example #7: When we wait 10 minutes
1219
+ *
1220
+ */
872
1221
  When(/^(I |we )*wait (\d*)( minute| minutes|m)?$/, async function (pronounCase, number, withMinuteWord) {
873
1222
  await this.page.waitForTimeout(parseInt(number) * 1000 * 60);
874
1223
  });
875
1224
 
876
- // ---------------------------------------------------------------------------
877
- // When I wait max of 1 minute
878
- // Captures: (pronounCase, number, withMinuteWord) = 3
879
- // ---------------------------------------------------------------------------
1225
+ /**
1226
+ * Wait a max number of minutes until the page body is present.
1227
+ *
1228
+ * Example #1: When I wait max of 1 minute
1229
+ * Example #2: When I wait max of 10 minutes
1230
+ * Example #3: When we wait max of 1m
1231
+ * Example #4: And wait max of 2m
1232
+ * Example #5: And wait max of 2 minutes
1233
+ *
1234
+ */
880
1235
  When(/^(I |we )*wait max of (\d*)( minute| minutes|m)?$/, async function (pronounCase, number, withMinuteWord) {
881
1236
  await this.page.waitForTimeout(parseInt(number) * 1000 * 60);
882
1237
  });
883
1238
 
884
- // ---------------------------------------------------------------------------
885
- // When I wait until the page is loaded
886
- // Captures: (pronounCase, theCase, withIs) = 3
887
- // ---------------------------------------------------------------------------
1239
+ /**
1240
+ * Wait until the page is loaded.
1241
+ *
1242
+ * Example #1: When I wait until the page is loaded
1243
+ * Example #2: When we wait until the page is loaded
1244
+ * Example #3: When wait until page loaded
1245
+ *
1246
+ */
888
1247
  When(/^(I |we )*wait until( the)* page( is)* loaded*$/, async function (pronounCase, theCase, withIs) {
889
1248
  await waitForPageLoad(this.page, 10000);
890
1249
  });
891
1250
 
892
- // ---------------------------------------------------------------------------
893
- // When I wait for AJAX to finish
894
- // Captures: (pronounCase) = 1
895
- // ---------------------------------------------------------------------------
1251
+ /**
1252
+ * Wait for active XHR/fetch requests to complete.
1253
+ *
1254
+ * Example #1: When I wait for AJAX to finish
1255
+ * Example #2: And I wait for AJAX to finish
1256
+ * Example #3: When we wait for AJAX to finish
1257
+ * Example #4: And wait for AJAX to finish
1258
+ *
1259
+ */
896
1260
  When(/^(I |we )*wait for AJAX to finish$/, async function (pronounCase) {
897
1261
  await this.page.waitForLoadState('networkidle', { timeout: 10000 }).catch(() => {});
898
1262
  });
899
1263
 
900
- // ---------------------------------------------------------------------------
901
- // Scroll steps
902
- // ---------------------------------------------------------------------------
1264
+ /**
1265
+ * Scrolls the page down by a custom number of pixels (default 350).
1266
+ *
1267
+ * Example #1: And I scroll down
1268
+ * Example #2: When I scroll down 800
1269
+ * Example #3: And we scroll down 500
1270
+ * Example #4: When scrolling down 1200
1271
+ *
1272
+ */
903
1273
  When(/^(I scroll|we scroll|scrolling)? down(?: (\d+))?$/, async function (pronounCase, numValue) {
904
1274
  await this.page.evaluate((v) => window.scrollBy(0, v), numValue ? parseInt(numValue, 10) : 350);
905
1275
  });
906
1276
 
1277
+ /**
1278
+ * Scrolls the page up by a custom number of pixels (default 350).
1279
+ *
1280
+ * Example #1: And I scroll up
1281
+ * Example #2: When I scroll up 1000
1282
+ * Example #3: And we scroll up 300
1283
+ * Example #4: When scrolling up 750
1284
+ *
1285
+ */
907
1286
  When(/^(I scroll|we scroll|scrolling)? up(?: (\d+))?$/, async function (pronounCase, numValue) {
908
1287
  await this.page.evaluate((v) => window.scrollBy(0, -v), numValue ? parseInt(numValue, 10) : 350);
909
1288
  });
910
1289
 
1290
+ /**
1291
+ * Scrolls to the very top of the current page.
1292
+ *
1293
+ * Example #1: When I scroll to top
1294
+ * Example #2: And we scroll to the top
1295
+ * Example #3: When scrolling to the top of the page
1296
+ *
1297
+ */
911
1298
  When(/^(I scroll|we scroll|scrolling)? to( the)* top( of the page)*$/, async function (pronounCase, theCase, pageCase) {
912
1299
  await this.page.evaluate(() => window.scrollTo(0, 0));
913
1300
  });
914
1301
 
1302
+ /**
1303
+ * Scrolls to the bottom of the current page.
1304
+ *
1305
+ * Example #1: When I scroll to the bottom
1306
+ * Example #2: And we scroll to bottom
1307
+ * Example #3: When scrolling to the bottom of the page
1308
+ *
1309
+ */
915
1310
  When(/^(I scroll|we scroll|scrolling)? to( the)* bottom( of the page)*$/, async function (pronounCase, theCase, pageCase) {
916
1311
  await this.page.evaluate(() => {
917
1312
  window.scrollTo(0, document.body.scrollHeight);
@@ -925,6 +1320,14 @@ When(/^(I scroll|we scroll|scrolling)? to( the)* bottom( of the page)*$/, async
925
1320
  });
926
1321
  });
927
1322
 
1323
+ /**
1324
+ * Scrolls to the top of a specific element identified by a CSS selector.
1325
+ *
1326
+ * Example #1: When I scroll to top of "#off-canvas"
1327
+ * Example #2: And we scroll to top of "#sidebar"
1328
+ * Example #3: When scrolling to top of "#main-container"
1329
+ *
1330
+ */
928
1331
  When(/^(I scroll|we scroll|scrolling)? to top of "([^"]*)"$/, async function (pronounCase, selector) {
929
1332
  await this.page.locator(selector).evaluate(el => {
930
1333
  el.scrollTop = 0;
@@ -932,6 +1335,14 @@ When(/^(I scroll|we scroll|scrolling)? to top of "([^"]*)"$/, async function (pr
932
1335
  });
933
1336
  });
934
1337
 
1338
+ /**
1339
+ * Scrolls to the bottom of a specific element identified by a CSS selector.
1340
+ *
1341
+ * Example #1: When I scroll to bottom of "#off-canvas"
1342
+ * Example #2: And we scroll to bottom of "#sidebar"
1343
+ * Example #3: When scrolling to bottom of "#main-container"
1344
+ *
1345
+ */
935
1346
  When(/^(I scroll|we scroll|scrolling)? to bottom of "([^"]*)"$/, async function (pronounCase, selector) {
936
1347
  await this.page.locator(selector).evaluate(el => {
937
1348
  el.scrollTop = el.scrollHeight;
@@ -939,33 +1350,90 @@ When(/^(I scroll|we scroll|scrolling)? to bottom of "([^"]*)"$/, async function
939
1350
  });
940
1351
  });
941
1352
 
1353
+ /**
1354
+ * Scrolls the page right by a custom number of pixels (default 350).
1355
+ *
1356
+ * Example #1: And I scroll right
1357
+ * Example #2: When I scroll right 1000
1358
+ * Example #3: And we scroll right 300
1359
+ * Example #4: When scrolling right 750
1360
+ *
1361
+ */
942
1362
  When(/^(I scroll|we scroll|scrolling)? right(?: (\d+))?$/, async function (pronounCase, numValue) {
943
1363
  await this.page.evaluate((v) => window.scrollBy(v, 0), numValue ? parseInt(numValue, 10) : 350);
944
1364
  });
945
1365
 
1366
+ /**
1367
+ * Scrolls the page left by a custom number of pixels (default 350).
1368
+ *
1369
+ * Example #1: And I scroll left
1370
+ * Example #2: When I scroll left 800
1371
+ * Example #3: And we scroll left 500
1372
+ * Example #4: When scrolling left 1200
1373
+ *
1374
+ */
946
1375
  When(/^(I scroll|we scroll|scrolling)? left(?: (\d+))?$/, async function (pronounCase, numValue) {
947
1376
  await this.page.evaluate((v) => window.scrollBy(-v, 0), numValue ? parseInt(numValue, 10) : 350);
948
1377
  });
949
1378
 
1379
+ /**
1380
+ * Scrolls to the start (horizontal origin) of the page.
1381
+ *
1382
+ * Example #1: When I scroll to start
1383
+ * Example #2: And we scroll to the start
1384
+ * Example #3: When scrolling to the start of the page
1385
+ *
1386
+ */
950
1387
  When(/^(I scroll|we scroll|scrolling)? to( the)* start( of the page)*$/, async function (pronounCase, theCase, pageCase) {
951
1388
  await this.page.evaluate(() => window.scrollTo(0, window.scrollY));
952
1389
  });
953
1390
 
1391
+ /**
1392
+ * Scrolls to the end (horizontal maximum) of the page.
1393
+ *
1394
+ * Example #1: When I scroll to the end
1395
+ * Example #2: And we scroll to end
1396
+ * Example #3: When scrolling to the end of the page
1397
+ *
1398
+ */
954
1399
  When(/^(I scroll|we scroll|scrolling)? to( the)* end( of the page)*$/, async function (pronounCase, theCase, pageCase) {
955
1400
  await this.page.evaluate(() => window.scrollTo(document.body.scrollWidth, window.scrollY));
956
1401
  });
957
1402
 
1403
+ /**
1404
+ * Scrolls to the start of a specific element identified by a CSS selector.
1405
+ *
1406
+ * Example #1: When I scroll to start of "#off-canvas"
1407
+ * Example #2: And we scroll to start of "#sidebar"
1408
+ * Example #3: When scrolling to start of "#main-container"
1409
+ *
1410
+ */
958
1411
  When(/^(I scroll|we scroll|scrolling)? to start of "([^"]*)"$/, async function (pronounCase, selector) {
959
1412
  await this.page.locator(selector).evaluate(el => { el.scrollLeft = 0; });
960
1413
  });
961
1414
 
1415
+ /**
1416
+ * Scrolls to the end of a specific element identified by a CSS selector.
1417
+ *
1418
+ * Example #1: When I scroll to end of "#off-canvas"
1419
+ * Example #2: And we scroll to end of "#sidebar"
1420
+ * Example #3: When scrolling to end of "#main-container"
1421
+ *
1422
+ */
962
1423
  When(/^(I scroll|we scroll|scrolling)? to end of "([^"]*)"$/, async function (pronounCase, selector) {
963
1424
  await this.page.locator(selector).evaluate(el => { el.scrollLeft = el.scrollWidth; });
964
1425
  });
965
1426
 
966
- // ---------------------------------------------------------------------------
967
- // Modal steps
968
- // ---------------------------------------------------------------------------
1427
+ /**
1428
+ * Assert that a modal dialog is visible or not visible on the page.
1429
+ *
1430
+ * Example #1: Then I should see a modal
1431
+ * Example #2: Then I should see the modal
1432
+ * Example #3: Then we should see a modal dialog
1433
+ * Example #4: Then I should not see a modal
1434
+ * Example #5: Then I should not see the modal dialog
1435
+ *
1436
+ */
969
1437
  Then(/^(I |we )*should( not)* see (a |the )*modal( dialog)*$/, async function (pronounCase, notCase, aTheCase, dialogCase) {
970
1438
  const visible = await isAnyModalVisible(this.page);
971
1439
  if (notCase) {
@@ -975,6 +1443,16 @@ Then(/^(I |we )*should( not)* see (a |the )*modal( dialog)*$/, async function (p
975
1443
  }
976
1444
  });
977
1445
 
1446
+ /**
1447
+ * Assert that a modal dialog with a given title is visible or not visible.
1448
+ *
1449
+ * Example #1: Then I should see a modal with title "Confirm Action"
1450
+ * Example #2: Then I should see the modal with title "Welcome"
1451
+ * Example #3: Then we should see a modal with title "Welcome Message"
1452
+ * Example #4: Then I should not see a modal with title "Error"
1453
+ * Example #5: Then I should not see the modal with title "Validation Error"
1454
+ *
1455
+ */
978
1456
  Then(/^(I |we )*should( not)* see (a |the )*modal with title "([^"]*)?"$/, async function (pronounCase, notCase, aTheCase, title) {
979
1457
  const modal = this.page.locator(MODAL_SELECTOR);
980
1458
  const byHeading = modal.locator('.modal-title, .dialog-title, h1, h2, h3').filter({ hasText: title });
@@ -987,6 +1465,16 @@ Then(/^(I |we )*should( not)* see (a |the )*modal with title "([^"]*)?"$/, async
987
1465
  }
988
1466
  });
989
1467
 
1468
+ /**
1469
+ * Assert that a specific modal by id/class/data-modal is visible or not.
1470
+ *
1471
+ * Example #1: Then I should see a "confirmation-modal" modal
1472
+ * Example #2: Then I should see the "#delete-modal" modal
1473
+ * Example #3: Then we should see a "settings-modal" modal
1474
+ * Example #4: Then I should not see a "error-modal" modal
1475
+ * Example #5: Then I should not see the "#success-modal" modal
1476
+ *
1477
+ */
990
1478
  Then(/^(I |we )*should( not)* see (a |the )*"([^"]*)?" modal$/, async function (pronounCase, notCase, aTheCase, identifier) {
991
1479
  const selector = (identifier.startsWith('#') || identifier.startsWith('.'))
992
1480
  ? identifier
@@ -999,6 +1487,15 @@ Then(/^(I |we )*should( not)* see (a |the )*"([^"]*)?" modal$/, async function (
999
1487
  }
1000
1488
  });
1001
1489
 
1490
+ /**
1491
+ * Assert that a modal contains or does not contain specific text.
1492
+ *
1493
+ * Example #1: Then I should see "Are you sure?" in the modal
1494
+ * Example #2: Then I should see "Delete this item" in the modal
1495
+ * Example #3: Then we should see "Confirmation required" in the modal dialog
1496
+ * Example #4: Then I should not see "Error occurred" in the modal
1497
+ *
1498
+ */
1002
1499
  Then(/^(I |we )*should( not)* see "([^"]*)?" in( the)* modal( dialog)*$/, async function (pronounCase, notCase, expectedText, theCase, dialogCase) {
1003
1500
  const found = await this.page.locator(MODAL_SELECTOR).filter({ hasText: expectedText }).count() > 0;
1004
1501
  if (notCase) {
@@ -1008,6 +1505,15 @@ Then(/^(I |we )*should( not)* see "([^"]*)?" in( the)* modal( dialog)*$/, async
1008
1505
  }
1009
1506
  });
1010
1507
 
1508
+ /**
1509
+ * Click a button or link inside a modal dialog.
1510
+ *
1511
+ * Example #1: When I click "Confirm" in the modal
1512
+ * Example #2: When I click "Cancel" in the modal dialog
1513
+ * Example #3: When we click "OK" button in the modal
1514
+ * Example #4: And I click "Close" in the modal
1515
+ *
1516
+ */
1011
1517
  When(/^(I |we )*click "([^"]*)?"( button)* in( the)* modal( dialog)*$/, async function (pronounCase, buttonText, buttonCase, theCase, dialogCase) {
1012
1518
  await waitForModalState(this.page, 'visible', 10000);
1013
1519
  const modal = await findVisibleModal(this.page);
@@ -1017,6 +1523,15 @@ When(/^(I |we )*click "([^"]*)?"( button)* in( the)* modal( dialog)*$/, async fu
1017
1523
  .click();
1018
1524
  });
1019
1525
 
1526
+ /**
1527
+ * Close or dismiss a modal dialog (uses close button, or Escape fallback).
1528
+ *
1529
+ * Example #1: When I close the modal
1530
+ * Example #2: When I dismiss the modal dialog
1531
+ * Example #3: When we close the modal
1532
+ * Example #4: And I dismiss the modal
1533
+ *
1534
+ */
1020
1535
  When(/^(I |we )*(close|dismiss)( the)* modal( dialog)*$/, async function (pronounCase, closeOrDismiss, theCase, dialogCase) {
1021
1536
  await waitForModalState(this.page, 'visible', 10000);
1022
1537
  const modal = await findVisibleModal(this.page);
@@ -1028,7 +1543,91 @@ When(/^(I |we )*(close|dismiss)( the)* modal( dialog)*$/, async function (pronou
1028
1543
  }
1029
1544
  });
1030
1545
 
1546
+ /**
1547
+ * Wait for a modal dialog to appear or disappear.
1548
+ *
1549
+ * Example #1: When I wait for the modal to appear
1550
+ * Example #2: When I wait for the modal to disappear
1551
+ * Example #3: When we wait for modal to appear
1552
+ * Example #4: And I wait for the modal dialog to disappear
1553
+ *
1554
+ */
1031
1555
  When(/^(I |we )*wait for( the)* modal( dialog)* to (appear|disappear)$/, async function (pronounCase, theCase, dialogCase, appearOrDisappear) {
1032
1556
  const state = appearOrDisappear === 'appear' ? 'visible' : 'hidden';
1033
1557
  await waitForModalState(this.page, state, 10000);
1034
1558
  });
1559
+
1560
+ // ===========================================================================
1561
+ // STEP DEFINITIONS — Follow link, count elements, debug helpers.
1562
+ // ===========================================================================
1563
+
1564
+ /**
1565
+ * Follow a link by its visible text.
1566
+ * Uses Playwright's accessibility-first `getByRole('link', { name })` with a
1567
+ * text-match fallback.
1568
+ *
1569
+ * Example #1: When I follow "Contact Us"
1570
+ * Example #2: When I follow "About"
1571
+ * Example #3: When we follow "Home"
1572
+ * Example #4: And follow "Read more"
1573
+ * Example #5: When I follow "Documentation"
1574
+ * Example #6: When we follow "Sign in"
1575
+ * Example #7: When I follow "Log out"
1576
+ * Example #8: When I follow "Download report"
1577
+ * Example #9: And I follow "Previous"
1578
+ * Example #10: When I follow "Next"
1579
+ */
1580
+ When(/^(I |we )*follow "([^"]*)"$/, async function (pronounCase, link) {
1581
+ const esc = link.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
1582
+ const loc = this.page.getByRole('link', { name: link, exact: true }).or(
1583
+ this.page.locator('a').filter({ hasText: new RegExp('^' + esc + '$') })
1584
+ ).first();
1585
+ await loc.click();
1586
+ });
1587
+
1588
+ /**
1589
+ * Assert the exact number of elements matching a CSS selector.
1590
+ *
1591
+ * Example #1: Then I should see 3 "li" elements
1592
+ * Example #2: Then I should see 1 "h1" element
1593
+ * Example #3: Then we should see 5 ".card" elements
1594
+ * Example #4: Then I should see 0 ".error" elements
1595
+ * Example #5: And I should see 10 "table tr" elements
1596
+ * Example #6: Then I should see 2 "nav a" elements
1597
+ * Example #7: Then we should see 4 "ul li" elements
1598
+ * Example #8: Then I should see 1 "form" element
1599
+ * Example #9: And should see 6 ".product" elements
1600
+ * Example #10: Then I should see 8 "[data-testid='row']" elements
1601
+ */
1602
+ Then(/^(I |we )*should see (\d+) "([^"]*)" elements?$/, async function (pronounCase, num, selector) {
1603
+ const expected = parseInt(num, 10);
1604
+ const actual = await this.page.locator(selector).count();
1605
+ if (actual !== expected) {
1606
+ throw new Error(`Expected ${expected} "${selector}" element(s), got ${actual}.`);
1607
+ }
1608
+ });
1609
+
1610
+ /**
1611
+ * Print the current page URL to console (debug).
1612
+ *
1613
+ * Example #1: Then print current URL
1614
+ * Example #2: When print current URL
1615
+ * Example #3: And print current URL
1616
+ */
1617
+ Then(/^print current URL$/, function () {
1618
+ console.log('\n--- Current URL ---');
1619
+ console.log(` ${this.page.url()}`);
1620
+ });
1621
+
1622
+ /**
1623
+ * Print the full page HTML (last response) to console (debug).
1624
+ *
1625
+ * Example #1: Then print last response
1626
+ * Example #2: When print last response
1627
+ * Example #3: And print last response
1628
+ */
1629
+ Then(/^print last response$/, async function () {
1630
+ const html = await this.page.content();
1631
+ console.log('\n--- Last Response (HTML) ---');
1632
+ console.log(html);
1633
+ });