webship-js 2.0.0 → 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 (34) hide show
  1. package/README.md +1 -7
  2. package/bin/generate-reports.js +191 -0
  3. package/bin/init-webship.js +343 -0
  4. package/bin/postinstall.js +26 -0
  5. package/cucumber.js +59 -1
  6. package/examples/account.html +32 -0
  7. package/examples/diffy/baseline.html +54 -0
  8. package/examples/diffy/changed.html +63 -0
  9. package/examples/diffy/index.html +52 -0
  10. package/examples/index.html +6 -0
  11. package/examples/test--when--i-additionally-select.html +27 -0
  12. package/package.json +11 -4
  13. package/tests/features/diffy/test--diffy-01-example-demo.feature +22 -0
  14. package/tests/features/diffy/test--diffy-02-all-steps.feature +52 -0
  15. package/tests/features/diffy/test--diffy-03-real-api.feature +21 -0
  16. package/tests/features/test--given--i-am-an-anonymous-user.feature +10 -0
  17. package/tests/features/test--then--i-save-screenshot.feature +33 -0
  18. package/tests/features/test--then--i-see-locator.feature +320 -0
  19. package/tests/features/test--then--i-should-see-n-elements.feature +24 -0
  20. package/tests/features/test--then--print-current-url-and-response.feature +21 -0
  21. package/tests/features/test--when--i-additionally-select.feature +30 -0
  22. package/tests/features/test--when--i-follow.feature +22 -0
  23. package/tests/selectors/back-end-selectors.json +13 -0
  24. package/tests/selectors/front-end-selectors.json +16 -0
  25. package/tests/selectors/homepage-selectors.json +13 -0
  26. package/tests/step-definitions/webship-api.js +234 -41
  27. package/tests/step-definitions/webship-screenshot.js +427 -0
  28. package/tests/step-definitions/webship-selectors.js +961 -0
  29. package/tests/step-definitions/webship.js +835 -226
  30. package/tests/step-definitions-diffy/README.md +329 -0
  31. package/tests/step-definitions-diffy/mock-diffy-api/server.js +84 -0
  32. package/tests/step-definitions-diffy/webship-diffy-mock.js +31 -0
  33. package/tests/step-definitions-diffy/webship-diffy.js +472 -0
  34. package/generate-reports.js +0 -22
@@ -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,10 +208,35 @@ async function isAnyModalVisible(page) {
189
208
  );
190
209
  }
191
210
 
192
- // ---------------------------------------------------------------------------
193
- // Given I am on homepage / frontpage
194
- // Captures: (pronounCase, theCase, pageCase) = 3
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
+ */
219
+ Given(/^(I am |we are )?an anonymous user$/, async function (pronounCase) {
220
+ await this.context.clearCookies();
221
+ await gotoUrl(this.page, this.launchUrl);
222
+ await waitForPageLoad(this.page, this.minWaitTime.page || 3000);
223
+ });
224
+
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
+ */
196
240
  Given(/^(I am |we are )?on( the)* (homepage|frontpage)$/, async function (pronounCase, theCase, pageCase) {
197
241
  const defaultTime = this.minWaitTime.page || 3000;
198
242
  await gotoUrl(this.page, this.launchUrl);
@@ -200,20 +244,37 @@ Given(/^(I am |we are )?on( the)* (homepage|frontpage)$/, async function (pronou
200
244
  await waitForPageLoad(this.page, defaultTime);
201
245
  });
202
246
 
203
- // ---------------------------------------------------------------------------
204
- // Given I am on "/about-us.html"
205
- // Captures: (pronounCase, theCase, url, pageCase) = 4
206
- // ---------------------------------------------------------------------------
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
+ */
207
259
  Given(/^(I am |we are )*on( the)* "([^"]*)?"( page)*$/, async function (pronounCase, theCase, url, pageCase) {
208
260
  await gotoUrl(this.page, this.launchUrl + url);
209
261
  await this.page.waitForSelector('body', { state: 'attached', timeout: 10000 });
210
262
  await waitForPageLoad(this.page);
211
263
  });
212
264
 
213
- // ---------------------------------------------------------------------------
214
- // When I go to homepage / frontpage
215
- // Captures: (pronounCase, theCase, pageCase) = 3
216
- // ---------------------------------------------------------------------------
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
+ */
217
278
  When(/^(I go |I navigate |we go |we navigate |navigating )?to( the)* (homepage|frontpage)$/, async function (pronounCase, theCase, pageCase) {
218
279
  const defaultTime = this.minWaitTime.page || 3000;
219
280
  await gotoUrl(this.page, this.launchUrl);
@@ -221,10 +282,17 @@ When(/^(I go |I navigate |we go |we navigate |navigating )?to( the)* (homepage|f
221
282
  await waitForPageLoad(this.page, defaultTime);
222
283
  });
223
284
 
224
- // ---------------------------------------------------------------------------
225
- // When I go to "/contact-us.html"
226
- // Captures: (pronounCase, url) = 2
227
- // ---------------------------------------------------------------------------
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
+ */
228
296
  When(/^(I go |I navigate |we go |we navigate |navigating )?to "([^"]*)?"$/, async function (pronounCase, url) {
229
297
  const defaultTime = this.minWaitTime.page || 3000;
230
298
  await gotoUrl(this.page, this.launchUrl + url);
@@ -232,10 +300,15 @@ When(/^(I go |I navigate |we go |we navigate |navigating )?to "([^"]*)?"$/, asyn
232
300
  await waitForPageLoad(this.page, defaultTime);
233
301
  });
234
302
 
235
- // ---------------------------------------------------------------------------
236
- // Then I should see "text" / Then I should not see "text"
237
- // Captures: (pronounCase, notCase, expectedText) = 3
238
- // ---------------------------------------------------------------------------
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
+ */
239
312
  Then(/^(I |we )*should( not)* see "([^"]*)?"$/, async function (pronounCase, notCase, expectedText) {
240
313
  if (notCase) {
241
314
  const text = await this.page.locator('body').textContent() || '';
@@ -245,26 +318,40 @@ Then(/^(I |we )*should( not)* see "([^"]*)?"$/, async function (pronounCase, not
245
318
  }
246
319
  });
247
320
 
248
- // ---------------------------------------------------------------------------
249
- // When I move forward one page
250
- // Captures: (pronounCase) = 1
251
- // ---------------------------------------------------------------------------
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
+ */
252
329
  When(/^(I |we )*move forward one page$/, async function (pronounCase) {
253
330
  await this.page.goForward();
254
331
  });
255
332
 
256
- // ---------------------------------------------------------------------------
257
- // When I move backward one page
258
- // Captures: (pronounCase) = 1
259
- // ---------------------------------------------------------------------------
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
+ */
260
341
  When(/^(I |we )*move backward one page$/, async function (pronounCase) {
261
342
  await this.page.goBack();
262
343
  });
263
344
 
264
- // ---------------------------------------------------------------------------
265
- // When I press "Log In" button
266
- // Captures: (pronounCase, theCase, element, buttonCase) = 4
267
- // ---------------------------------------------------------------------------
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
+ */
268
355
  When(/^(I |we )*press( the)* "([^"]*)?"( button)*$/, async function (pronounCase, theCase, element, buttonCase) {
269
356
  const esc = element.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
270
357
  await this.page.locator('button, input[type="button"], input[type="submit"], [role="button"], .btn, a')
@@ -273,18 +360,29 @@ When(/^(I |we )*press( the)* "([^"]*)?"( button)*$/, async function (pronounCase
273
360
  .click();
274
361
  });
275
362
 
276
- // ---------------------------------------------------------------------------
277
- // When I press "btn-pressid" by attr / attribute
278
- // Captures: (pronounCase, attrValue, itsCase, attr, attrWord) = 5
279
- // ---------------------------------------------------------------------------
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
+ */
280
373
  When(/^(I |we )*press "([^"]*)?" by( its)*(?: "([^"]*)?")* (attribute|attr)$/, async function (pronounCase, attrValue, itsCase, attr, attrWord) {
281
374
  await this.page.locator(buildSelector(attrValue, attr)).first().click();
282
375
  });
283
376
 
284
- // ---------------------------------------------------------------------------
285
- // When I click "Contact Us"
286
- // Captures: (pronounCase, item) = 2
287
- // ---------------------------------------------------------------------------
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
+ */
288
386
  When(/^(I |we )*click "([^"]*)?"$/, async function (pronounCase, item) {
289
387
  const esc = item.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
290
388
  await this.page.locator('a, button, [role="button"], .btn, input[type="button"], input[type="submit"]')
@@ -293,18 +391,28 @@ When(/^(I |we )*click "([^"]*)?"$/, async function (pronounCase, item) {
293
391
  .click();
294
392
  });
295
393
 
296
- // ---------------------------------------------------------------------------
297
- // When I click "#about-us-id" by attr / attribute
298
- // Captures: (pronounCase, attrValue, itsCase, attr, attrWord) = 5
299
- // ---------------------------------------------------------------------------
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
+ */
300
403
  When(/^(I |we )*click "([^"]*)?" by( its)*(?: "([^"]*)?")* (attribute|attr)$/, async function (pronounCase, attrValue, itsCase, attr, attrWord) {
301
404
  await this.page.locator(buildSelector(attrValue, attr)).first().click();
302
405
  });
303
406
 
304
- // ---------------------------------------------------------------------------
305
- // When I click "Edit" in the "John Smith" row
306
- // Captures: (pronounCase, clickText, theCase, rowIdentifier) = 4
307
- // ---------------------------------------------------------------------------
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
+ */
308
416
  When(/^(I |we )*click "([^"]*)?" in( the)* "([^"]*)?" row$/, async function (pronounCase, clickText, theCase, rowIdentifier) {
309
417
  const esc = clickText.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
310
418
  const row = this.page.locator('tr').filter({ hasText: rowIdentifier }).first();
@@ -317,10 +425,18 @@ When(/^(I |we )*click "([^"]*)?" in( the)* "([^"]*)?" row$/, async function (pro
317
425
  }
318
426
  });
319
427
 
320
- // ---------------------------------------------------------------------------
321
- // Then I should see "Active" in the "John Smith" row
322
- // Captures: (pronounCase, notCase, expectedText, theCase, rowIdentifier) = 5
323
- // ---------------------------------------------------------------------------
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
+ */
324
440
  Then(/^(I |we )*should( not)* see "([^"]*)?" in( the)* "([^"]*)?" row$/, async function (pronounCase, notCase, expectedText, theCase, rowIdentifier) {
325
441
  const found = await this.page.evaluate(({ id, text }) => {
326
442
  const rows = Array.from(document.querySelectorAll('tr'));
@@ -333,86 +449,138 @@ Then(/^(I |we )*should( not)* see "([^"]*)?" in( the)* "([^"]*)?" row$/, async f
333
449
  }
334
450
  });
335
451
 
336
- // ---------------------------------------------------------------------------
337
- // When I reload the page
338
- // Captures: (pronounCase, theCase, pageCase) = 3
339
- // ---------------------------------------------------------------------------
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
+ */
340
461
  When(/^(I |we )*reload( the)*( page)*$/, async function (pronounCase, theCase, pageCase) {
341
462
  await this.page.reload();
342
463
  });
343
464
 
344
- // ---------------------------------------------------------------------------
345
- // When I fill in "Username" with "John Smith"
346
- // Captures: (pronounCase, field, value) = 3
347
- // ---------------------------------------------------------------------------
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
+ */
348
474
  When(/^(I |we )*fill in "([^"]*)?" with "([^"]*)?"$/, async function (pronounCase, field, value) {
349
475
  await fillField(this.page, field, value);
350
476
  });
351
477
 
352
- // ---------------------------------------------------------------------------
353
- // When I fill in "uname" with "John Smith" by attr
354
- // Captures: (pronounCase, attrValue, txtValue, itsCase, attr, attrWord) = 6
355
- // ---------------------------------------------------------------------------
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
+ */
356
487
  When(/^(I |we )*fill in "([^"]*)?" with "([^"]*)?" by( its)*(?: "([^"]*)?")* (attribute|attr)$/, async function (pronounCase, attrValue, txtValue, itsCase, attr, attrWord) {
357
488
  await this.page.locator(buildSelector(attrValue, attr)).first().fill(txtValue);
358
489
  });
359
490
 
360
- // ---------------------------------------------------------------------------
361
- // When I fill in "Username" with: (empty)
362
- // Captures: (pronounCase, field) = 2
363
- // ---------------------------------------------------------------------------
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
+ */
364
499
  When(/^(I |we )*fill in "([^"]*)?" with:$/, async function (pronounCase, field) {
365
500
  await fillField(this.page, field, '');
366
501
  });
367
502
 
368
- // ---------------------------------------------------------------------------
369
- // When I fill in "uname" with: by attr (empty by attr)
370
- // Captures: (pronounCase, attrValue, itsCase, attr, attrWord) = 5
371
- // ---------------------------------------------------------------------------
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
+ */
372
512
  When(/^(I |we )*fill in "([^"]*)?" with: by( its)*(?: "([^"]*)?")* (attribute|attr)$/, async function (pronounCase, attrValue, itsCase, attr, attrWord) {
373
513
  await this.page.locator(buildSelector(attrValue, attr)).first().fill('');
374
514
  });
375
515
 
376
- // ---------------------------------------------------------------------------
377
- // When I fill in "John Smith" for "Username"
378
- // Captures: (pronounCase, value, field) = 3
379
- // ---------------------------------------------------------------------------
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
+ */
380
524
  When(/^(I |we )*fill in "([^"]*)?" for "([^"]*)?"$/, async function (pronounCase, value, field) {
381
525
  await fillField(this.page, field, value);
382
526
  });
383
527
 
384
- // ---------------------------------------------------------------------------
385
- // When I fill in "John Smith" for "uname" by attr
386
- // Captures: (pronounCase, txtValue, attrValue, itsCase, attr, attrWord) = 6
387
- // ---------------------------------------------------------------------------
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
+ */
388
537
  When(/^(I |we )*fill in "([^"]*)?" for "([^"]*)?" by( its)*(?: "([^"]*)?")* (attribute|attr)$/, async function (pronounCase, txtValue, attrValue, itsCase, attr, attrWord) {
389
538
  await this.page.locator(buildSelector(attrValue, attr)).first().fill(txtValue);
390
539
  });
391
540
 
392
- // ---------------------------------------------------------------------------
393
- // When I fill in the following: (table by label)
394
- // Captures: (pronounCase, theCase) = 2
395
- // ---------------------------------------------------------------------------
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
+ */
396
552
  When(/^(I |we )*fill in( the)* following:$/, async function (pronounCase, theCase, table) {
397
553
  for (const [field, value] of table.raw()) {
398
554
  await fillField(this.page, field, value);
399
555
  }
400
556
  });
401
557
 
402
- // ---------------------------------------------------------------------------
403
- // When I fill in the following: by attr (table by attribute)
404
- // Captures: (pronounCase, theCase, itsCase, attr, attrWord) = 5
405
- // ---------------------------------------------------------------------------
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
+ */
406
569
  When(/^(I |we )*fill in( the)* following: by( its)*(?: "([^"]*)?")* (attribute|attr)$/, async function (pronounCase, theCase, itsCase, attr, attrWord, table) {
407
570
  for (const [attrValue, value] of table.raw()) {
408
571
  await this.page.locator(buildSelector(attrValue, attr)).first().fill(value);
409
572
  }
410
573
  });
411
574
 
412
- // ---------------------------------------------------------------------------
413
- // When I select "Mercedes" from "Cars"
414
- // Captures: (pronounCase, option, selectList) = 3
415
- // ---------------------------------------------------------------------------
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
+ */
416
584
  When(/^(I |we )*select "([^"]*)?" from "([^"]*)?"$/, async function (pronounCase, option, selectList) {
417
585
  let loc;
418
586
  if (selectList.startsWith('#') || selectList.startsWith('.')) {
@@ -429,10 +597,65 @@ When(/^(I |we )*select "([^"]*)?" from "([^"]*)?"$/, async function (pronounCase
429
597
  }
430
598
  });
431
599
 
432
- // ---------------------------------------------------------------------------
433
- // When I check "Remember me"
434
- // Captures: (pronounCase, item) = 2
435
- // ---------------------------------------------------------------------------
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
+ */
436
659
  When(/^(I |we )*check "([^"]*)?"$/, async function (pronounCase, item) {
437
660
  if (item.startsWith('#') || item.startsWith('.')) {
438
661
  await this.page.locator(item).check();
@@ -446,10 +669,15 @@ When(/^(I |we )*check "([^"]*)?"$/, async function (pronounCase, item) {
446
669
  }
447
670
  });
448
671
 
449
- // ---------------------------------------------------------------------------
450
- // When I uncheck "Remember me"
451
- // Captures: (pronounCase, item) = 2
452
- // ---------------------------------------------------------------------------
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
+ */
453
681
  When(/^(I |we )*uncheck "([^"]*)?"$/, async function (pronounCase, item) {
454
682
  if (item.startsWith('#') || item.startsWith('.')) {
455
683
  await this.page.locator(item).uncheck();
@@ -463,10 +691,15 @@ When(/^(I |we )*uncheck "([^"]*)?"$/, async function (pronounCase, item) {
463
691
  }
464
692
  });
465
693
 
466
- // ---------------------------------------------------------------------------
467
- // When I select radio button "Male"
468
- // Captures: (pronounCase, item) = 2
469
- // ---------------------------------------------------------------------------
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
+ */
470
703
  When(/^(I |we )*select radio button "([^"]*)?"$/, async function (pronounCase, item) {
471
704
  if (item.startsWith('#') || item.startsWith('.')) {
472
705
  await this.page.locator(item).check();
@@ -480,10 +713,21 @@ When(/^(I |we )*select radio button "([^"]*)?"$/, async function (pronounCase, i
480
713
  }
481
714
  });
482
715
 
483
- // ---------------------------------------------------------------------------
484
- // Then I should be on homepage / frontpage
485
- // Captures: (pronounCase, notCase, theCase, pageCase) = 4
486
- // ---------------------------------------------------------------------------
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
+ */
487
731
  Then(/^(I |we )*should( not)* be on( the)* (homepage|frontpage)$/, async function (pronounCase, notCase, theCase, pageCase) {
488
732
  const currentUrl = this.page.url();
489
733
  if (notCase) {
@@ -495,10 +739,21 @@ Then(/^(I |we )*should( not)* be on( the)* (homepage|frontpage)$/, async functio
495
739
  }
496
740
  });
497
741
 
498
- // ---------------------------------------------------------------------------
499
- // Then I should be on "/user/login"
500
- // Captures: (pronounCase, notCase, theCase, url, pageCase) = 5
501
- // ---------------------------------------------------------------------------
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
+ */
502
757
  Then(/^(I |we )*should( not)* be on( the)* "([^"]*)?"( page)*$/, async function (pronounCase, notCase, theCase, url, pageCase) {
503
758
  const currentUrl = this.page.url();
504
759
  if (notCase) {
@@ -508,10 +763,14 @@ Then(/^(I |we )*should( not)* be on( the)* "([^"]*)?"( page)*$/, async function
508
763
  }
509
764
  });
510
765
 
511
- // ---------------------------------------------------------------------------
512
- // Then the "Login" link should contain "/log-in"
513
- // Captures: (theCase, element, url) = 3
514
- // ---------------------------------------------------------------------------
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
+ */
515
774
  Then(/^(the )*"([^"]*)?" link should contain "([^"]*)?"$/, async function (theCase, element, url) {
516
775
  const loc = this.page.getByText(element, { exact: true }).first();
517
776
  await loc.waitFor({ timeout: 5000 });
@@ -519,10 +778,14 @@ Then(/^(the )*"([^"]*)?" link should contain "([^"]*)?"$/, async function (theCa
519
778
  assert.ok(href.includes(url), `Expected link "${element}" href to contain "${url}" but got "${href}"`);
520
779
  });
521
780
 
522
- // ---------------------------------------------------------------------------
523
- // Then the "#about-us-id" link should contain "about" by attr
524
- // Captures: (theCase, attrValue, url, itsCase, attr, attrWord) = 6
525
- // ---------------------------------------------------------------------------
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
+ */
526
789
  Then(/^(the )*"([^"]*)?" link should contain "([^"]*)?" by( its)*(?: "([^"]*)?")* (attribute|attr)$/, async function (theCase, attrValue, url, itsCase, attr, attrWord) {
527
790
  const loc = this.page.locator(buildSelector(attrValue, attr)).first();
528
791
  await loc.waitFor({ timeout: 5000 });
@@ -530,10 +793,13 @@ Then(/^(the )*"([^"]*)?" link should contain "([^"]*)?" by( its)*(?: "([^"]*)?")
530
793
  assert.ok(href.includes(url), `Expected element href to contain "${url}" but got "${href}"`);
531
794
  });
532
795
 
533
- // ---------------------------------------------------------------------------
534
- // Then the response should contain "text"
535
- // Captures: (theCase, notCase, expectedText) = 3
536
- // ---------------------------------------------------------------------------
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
+ */
537
803
  Then(/^(the )*response should( not)* contain "([^"]*)?"$/, async function (theCase, notCase, expectedText) {
538
804
  const text = await this.page.locator('html').textContent() || '';
539
805
  if (notCase) {
@@ -543,10 +809,14 @@ Then(/^(the )*response should( not)* contain "([^"]*)?"$/, async function (theCa
543
809
  }
544
810
  });
545
811
 
546
- // ---------------------------------------------------------------------------
547
- // Then I should see "John Smith" in the "Username" element
548
- // Captures: (pronounCase, notCase, expectedText, theCase, element) = 5
549
- // ---------------------------------------------------------------------------
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
+ */
550
820
  Then(/^(I |we )*should( not)* see "([^"]*)?" in( the)* "([^"]*)?" element$/, async function (pronounCase, notCase, expectedText, theCase, element) {
551
821
  const forAttr = await this.page.getByText(element, { exact: true }).getAttribute('for').catch(() => null);
552
822
  const loc = this.page.locator(forAttr ? '#' + forAttr : element).first();
@@ -559,10 +829,15 @@ Then(/^(I |we )*should( not)* see "([^"]*)?" in( the)* "([^"]*)?" element$/, asy
559
829
  }
560
830
  });
561
831
 
562
- // ---------------------------------------------------------------------------
563
- // Then I should see "John Smith" in the "uname" element by attr
564
- // Captures: (pronounCase, notCase, expectedText, theCase, attrValue, itsCase, attr, attrWord) = 8
565
- // ---------------------------------------------------------------------------
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
+ */
566
841
  Then(/^(I |we )*should( not)* see "([^"]*)?" in( the)* "([^"]*)?" element by( its)*(?: "([^"]*)?")* (attribute|attr)$/, async function (pronounCase, notCase, expectedText, theCase, attrValue, itsCase, attr, attrWord) {
567
842
  const loc = this.page.locator(buildSelector(attrValue, attr)).first();
568
843
  await loc.waitFor({ timeout: 10000 });
@@ -574,10 +849,14 @@ Then(/^(I |we )*should( not)* see "([^"]*)?" in( the)* "([^"]*)?" element by( it
574
849
  }
575
850
  });
576
851
 
577
- // ---------------------------------------------------------------------------
578
- // Then I should see a "Username" element
579
- // Captures: (pronounCase, notCase, aAnCase, element) = 4
580
- // ---------------------------------------------------------------------------
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
+ */
581
860
  Then(/^(I |we )*should( not)* see (a|an) "([^"]*)?" element$/, async function (pronounCase, notCase, aAnCase, element) {
582
861
  if (notCase) {
583
862
  const text = await this.page.locator('body').textContent() || '';
@@ -593,10 +872,15 @@ Then(/^(I |we )*should( not)* see (a|an) "([^"]*)?" element$/, async function (p
593
872
  }
594
873
  });
595
874
 
596
- // ---------------------------------------------------------------------------
597
- // Then I should see a "uname" element by attr
598
- // Captures: (pronounCase, notCase, aAnCase, attrValue, itsCase, attr, attrWord) = 7
599
- // ---------------------------------------------------------------------------
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
+ */
600
884
  Then(/^(I |we )*should( not)* see (a|an) "([^"]*)?" element by( its)*(?: "([^"]*)?")* (attribute|attr)$/, async function (pronounCase, notCase, aAnCase, attrValue, itsCase, attr, attrWord) {
601
885
  const loc = this.page.locator(buildSelector(attrValue, attr));
602
886
  if (notCase) {
@@ -606,10 +890,15 @@ Then(/^(I |we )*should( not)* see (a|an) "([^"]*)?" element by( its)*(?: "([^"]*
606
890
  }
607
891
  });
608
892
 
609
- // ---------------------------------------------------------------------------
610
- // Then the "body" element should contain "color:white;"
611
- // Captures: (theCase, selectorRaw, notCase, elementCss) = 4
612
- // ---------------------------------------------------------------------------
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
+ */
613
902
  Then(/^(the )*"([^"]*)?" element should( not)* contain "([^"]*)?"$/, async function (theCase, selectorRaw, notCase, elementCss) {
614
903
  const cssClean = elementCss.replace(/;$/, '');
615
904
  const colonIdx = cssClean.indexOf(':');
@@ -652,10 +941,14 @@ Then(/^(the )*"([^"]*)?" element should( not)* contain "([^"]*)?"$/, async funct
652
941
  }
653
942
  });
654
943
 
655
- // ---------------------------------------------------------------------------
656
- // Then the "Username" field should contain "John Smith"
657
- // Captures: (theCase, field, notCase, expectedText) = 4
658
- // ---------------------------------------------------------------------------
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
+ */
659
952
  Then(/^(the )*"([^"]*)?" field should( not)* contain "([^"]*)?"$/, async function (theCase, field, notCase, expectedText) {
660
953
  let selector = field;
661
954
  if (!field.startsWith('#') && !field.startsWith('.')) {
@@ -672,10 +965,13 @@ Then(/^(the )*"([^"]*)?" field should( not)* contain "([^"]*)?"$/, async functio
672
965
  }
673
966
  });
674
967
 
675
- // ---------------------------------------------------------------------------
676
- // Then the "#PrivacyPolicy" checkbox should be checked
677
- // Captures: (theCase, checkbox, notCase) = 3
678
- // ---------------------------------------------------------------------------
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
+ */
679
975
  Then(/^(the )*"([^"]*)?" checkbox should( not)* be checked$/, async function (theCase, checkbox, notCase) {
680
976
  const isChecked = await this.page.locator(checkbox).isChecked();
681
977
  if (notCase) {
@@ -685,10 +981,13 @@ Then(/^(the )*"([^"]*)?" checkbox should( not)* be checked$/, async function (th
685
981
  }
686
982
  });
687
983
 
688
- // ---------------------------------------------------------------------------
689
- // Then the "#rememberMe" checkbox is checked
690
- // Captures: (theCase, checkbox, notCase) = 3
691
- // ---------------------------------------------------------------------------
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
+ */
692
991
  Then(/^(the )*"([^"]*)?" checkbox is( not)* checked$/, async function (theCase, checkbox, notCase) {
693
992
  const isChecked = await this.page.locator(checkbox).isChecked();
694
993
  if (notCase) {
@@ -698,10 +997,13 @@ Then(/^(the )*"([^"]*)?" checkbox is( not)* checked$/, async function (theCase,
698
997
  }
699
998
  });
700
999
 
701
- // ---------------------------------------------------------------------------
702
- // Then the checkbox "#PrivacyPolicy" should be checked
703
- // Captures: (theCase, checkbox, notCase) = 3
704
- // ---------------------------------------------------------------------------
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
+ */
705
1007
  Then(/^(the )*checkbox "([^"]*)?" should( not)* be checked$/, async function (theCase, checkbox, notCase) {
706
1008
  const isChecked = await this.page.locator(checkbox).isChecked();
707
1009
  if (notCase) {
@@ -711,10 +1013,13 @@ Then(/^(the )*checkbox "([^"]*)?" should( not)* be checked$/, async function (th
711
1013
  }
712
1014
  });
713
1015
 
714
- // ---------------------------------------------------------------------------
715
- // Then the checkbox "#rememberMe" is checked
716
- // Captures: (theCase, checkbox, notCase) = 3
717
- // ---------------------------------------------------------------------------
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
+ */
718
1023
  Then(/^(the )*checkbox "([^"]*)?" is( not)* checked$/, async function (theCase, checkbox, notCase) {
719
1024
  const isChecked = await this.page.locator(checkbox).isChecked();
720
1025
  if (notCase) {
@@ -724,10 +1029,14 @@ Then(/^(the )*checkbox "([^"]*)?" is( not)* checked$/, async function (theCase,
724
1029
  }
725
1030
  });
726
1031
 
727
- // ---------------------------------------------------------------------------
728
- // Then the radio button "#gender-male" should be selected
729
- // Captures: (theCase, radioButton, notCase) = 3
730
- // ---------------------------------------------------------------------------
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
+ */
731
1040
  Then(/^(the )*radio button "([^"]*)?" should( not)* be selected$/, async function (theCase, radioButton, notCase) {
732
1041
  const isChecked = await this.page.locator(radioButton).isChecked();
733
1042
  if (notCase) {
@@ -737,10 +1046,13 @@ Then(/^(the )*radio button "([^"]*)?" should( not)* be selected$/, async functio
737
1046
  }
738
1047
  });
739
1048
 
740
- // ---------------------------------------------------------------------------
741
- // Then the radio button with value "male" should be selected
742
- // Captures: (theCase, radioValue, notCase) = 3
743
- // ---------------------------------------------------------------------------
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
+ */
744
1056
  Then(/^(the )*radio button with value "([^"]*)?" should( not)* be selected$/, async function (theCase, radioValue, notCase) {
745
1057
  const isChecked = await this.page.locator(`input[type="radio"][value="${radioValue}"]`).first().isChecked();
746
1058
  if (notCase) {
@@ -750,10 +1062,13 @@ Then(/^(the )*radio button with value "([^"]*)?" should( not)* be selected$/, as
750
1062
  }
751
1063
  });
752
1064
 
753
- // ---------------------------------------------------------------------------
754
- // Then the "#gender-male" radio button is selected
755
- // Captures: (theCase, radioButton, notCase) = 3
756
- // ---------------------------------------------------------------------------
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
+ */
757
1072
  Then(/^(the )*"([^"]*)?" radio button is( not)* selected$/, async function (theCase, radioButton, notCase) {
758
1073
  const isChecked = await this.page.locator(radioButton).isChecked();
759
1074
  if (notCase) {
@@ -763,10 +1078,14 @@ Then(/^(the )*"([^"]*)?" radio button is( not)* selected$/, async function (theC
763
1078
  }
764
1079
  });
765
1080
 
766
- // ---------------------------------------------------------------------------
767
- // Then the response status code should be 200
768
- // Captures: (theCase, notCase, expectedStatusCode) = 3
769
- // ---------------------------------------------------------------------------
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
+ */
770
1089
  Then(/^(the )*response status code should( not)* be (\d+)$/, async function (theCase, notCase, expectedStatusCode) {
771
1090
  const currentURL = this.page.url();
772
1091
  try {
@@ -787,10 +1106,14 @@ Then(/^(the )*response status code should( not)* be (\d+)$/, async function (the
787
1106
  }
788
1107
  });
789
1108
 
790
- // ---------------------------------------------------------------------------
791
- // Then I should see text matching "^T\w+"
792
- // Captures: (pronounCase, notCase, textPattern) = 3
793
- // ---------------------------------------------------------------------------
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
+ */
794
1117
  Then(/^(I |we )*should( not)* see text matching "([^"]*)?"$/, async function (pronounCase, notCase, textPattern) {
795
1118
  const bodyText = await this.page.evaluate(() => document.body.innerText || '');
796
1119
  const regex = new RegExp(textPattern);
@@ -801,10 +1124,13 @@ Then(/^(I |we )*should( not)* see text matching "([^"]*)?"$/, async function (pr
801
1124
  }
802
1125
  });
803
1126
 
804
- // ---------------------------------------------------------------------------
805
- // Then I should see text matching "..." in the "#date" element
806
- // Captures: (pronounCase, notCase, textPattern, theCase, element) = 5
807
- // ---------------------------------------------------------------------------
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
+ */
808
1134
  Then(/^(I |we )*should( not)* see text matching "([^"]*)?" in( the)* "([^"]*)?" element$/, async function (pronounCase, notCase, textPattern, theCase, element) {
809
1135
  const loc = this.page.locator(element).first();
810
1136
  await loc.waitFor({ timeout: 5000 });
@@ -817,10 +1143,14 @@ Then(/^(I |we )*should( not)* see text matching "([^"]*)?" in( the)* "([^"]*)?"
817
1143
  }
818
1144
  });
819
1145
 
820
- // ---------------------------------------------------------------------------
821
- // Then the url should match "/contact-us.html"
822
- // Captures: (theCase, notCase, pattern) = 3
823
- // ---------------------------------------------------------------------------
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
+ */
824
1154
  Then(/^(the )*url should( not)* match "([^"]*)?"$/, async function (theCase, notCase, pattern) {
825
1155
  const currentUrl = this.page.url();
826
1156
  const regex = new RegExp(pattern);
@@ -831,77 +1161,152 @@ Then(/^(the )*url should( not)* match "([^"]*)?"$/, async function (theCase, not
831
1161
  }
832
1162
  });
833
1163
 
834
- // ---------------------------------------------------------------------------
835
- // When I attach the file "profileIcon.jpg" to "#profile-icon-upload"
836
- // Captures: (pronounCase, theCase, fileName, element) = 4
837
- // ---------------------------------------------------------------------------
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
+ */
838
1171
  When(/^(I |we )*attach( the)* file "([^"]*)?" to "([^"]*)?"$/, async function (pronounCase, theCase, fileName, element) {
839
1172
  await this.page.locator(element).setInputFiles(path.resolve(this.assetsFolder, fileName));
840
1173
  });
841
1174
 
842
- // ---------------------------------------------------------------------------
843
- // When I wait 1 second / 5 seconds
844
- // Captures: (pronounCase, number, withSecondWord) = 3
845
- // ---------------------------------------------------------------------------
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
+ */
846
1188
  When(/^(I |we )*wait (\d*)( second| seconds|s)?$/, async function (pronounCase, number, withSecondWord) {
847
1189
  await this.page.waitForTimeout(parseInt(number) * 1000);
848
1190
  });
849
1191
 
850
- // ---------------------------------------------------------------------------
851
- // When I wait max of 5 seconds
852
- // Captures: (pronounCase, number, withSecondWord) = 3
853
- // ---------------------------------------------------------------------------
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
+ */
854
1205
  When(/^(I |we )*wait max of (\d*)( second| seconds|s)?$/, async function (pronounCase, number, withSecondWord) {
855
1206
  await this.page.waitForTimeout(parseInt(number) * 1000);
856
1207
  });
857
1208
 
858
- // ---------------------------------------------------------------------------
859
- // When I wait 1 minute
860
- // Captures: (pronounCase, number, withMinuteWord) = 3
861
- // ---------------------------------------------------------------------------
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
+ */
862
1221
  When(/^(I |we )*wait (\d*)( minute| minutes|m)?$/, async function (pronounCase, number, withMinuteWord) {
863
1222
  await this.page.waitForTimeout(parseInt(number) * 1000 * 60);
864
1223
  });
865
1224
 
866
- // ---------------------------------------------------------------------------
867
- // When I wait max of 1 minute
868
- // Captures: (pronounCase, number, withMinuteWord) = 3
869
- // ---------------------------------------------------------------------------
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
+ */
870
1235
  When(/^(I |we )*wait max of (\d*)( minute| minutes|m)?$/, async function (pronounCase, number, withMinuteWord) {
871
1236
  await this.page.waitForTimeout(parseInt(number) * 1000 * 60);
872
1237
  });
873
1238
 
874
- // ---------------------------------------------------------------------------
875
- // When I wait until the page is loaded
876
- // Captures: (pronounCase, theCase, withIs) = 3
877
- // ---------------------------------------------------------------------------
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
+ */
878
1247
  When(/^(I |we )*wait until( the)* page( is)* loaded*$/, async function (pronounCase, theCase, withIs) {
879
1248
  await waitForPageLoad(this.page, 10000);
880
1249
  });
881
1250
 
882
- // ---------------------------------------------------------------------------
883
- // When I wait for AJAX to finish
884
- // Captures: (pronounCase) = 1
885
- // ---------------------------------------------------------------------------
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
+ */
886
1260
  When(/^(I |we )*wait for AJAX to finish$/, async function (pronounCase) {
887
1261
  await this.page.waitForLoadState('networkidle', { timeout: 10000 }).catch(() => {});
888
1262
  });
889
1263
 
890
- // ---------------------------------------------------------------------------
891
- // Scroll steps
892
- // ---------------------------------------------------------------------------
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
+ */
893
1273
  When(/^(I scroll|we scroll|scrolling)? down(?: (\d+))?$/, async function (pronounCase, numValue) {
894
1274
  await this.page.evaluate((v) => window.scrollBy(0, v), numValue ? parseInt(numValue, 10) : 350);
895
1275
  });
896
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
+ */
897
1286
  When(/^(I scroll|we scroll|scrolling)? up(?: (\d+))?$/, async function (pronounCase, numValue) {
898
1287
  await this.page.evaluate((v) => window.scrollBy(0, -v), numValue ? parseInt(numValue, 10) : 350);
899
1288
  });
900
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
+ */
901
1298
  When(/^(I scroll|we scroll|scrolling)? to( the)* top( of the page)*$/, async function (pronounCase, theCase, pageCase) {
902
1299
  await this.page.evaluate(() => window.scrollTo(0, 0));
903
1300
  });
904
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
+ */
905
1310
  When(/^(I scroll|we scroll|scrolling)? to( the)* bottom( of the page)*$/, async function (pronounCase, theCase, pageCase) {
906
1311
  await this.page.evaluate(() => {
907
1312
  window.scrollTo(0, document.body.scrollHeight);
@@ -915,6 +1320,14 @@ When(/^(I scroll|we scroll|scrolling)? to( the)* bottom( of the page)*$/, async
915
1320
  });
916
1321
  });
917
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
+ */
918
1331
  When(/^(I scroll|we scroll|scrolling)? to top of "([^"]*)"$/, async function (pronounCase, selector) {
919
1332
  await this.page.locator(selector).evaluate(el => {
920
1333
  el.scrollTop = 0;
@@ -922,6 +1335,14 @@ When(/^(I scroll|we scroll|scrolling)? to top of "([^"]*)"$/, async function (pr
922
1335
  });
923
1336
  });
924
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
+ */
925
1346
  When(/^(I scroll|we scroll|scrolling)? to bottom of "([^"]*)"$/, async function (pronounCase, selector) {
926
1347
  await this.page.locator(selector).evaluate(el => {
927
1348
  el.scrollTop = el.scrollHeight;
@@ -929,33 +1350,90 @@ When(/^(I scroll|we scroll|scrolling)? to bottom of "([^"]*)"$/, async function
929
1350
  });
930
1351
  });
931
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
+ */
932
1362
  When(/^(I scroll|we scroll|scrolling)? right(?: (\d+))?$/, async function (pronounCase, numValue) {
933
1363
  await this.page.evaluate((v) => window.scrollBy(v, 0), numValue ? parseInt(numValue, 10) : 350);
934
1364
  });
935
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
+ */
936
1375
  When(/^(I scroll|we scroll|scrolling)? left(?: (\d+))?$/, async function (pronounCase, numValue) {
937
1376
  await this.page.evaluate((v) => window.scrollBy(-v, 0), numValue ? parseInt(numValue, 10) : 350);
938
1377
  });
939
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
+ */
940
1387
  When(/^(I scroll|we scroll|scrolling)? to( the)* start( of the page)*$/, async function (pronounCase, theCase, pageCase) {
941
1388
  await this.page.evaluate(() => window.scrollTo(0, window.scrollY));
942
1389
  });
943
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
+ */
944
1399
  When(/^(I scroll|we scroll|scrolling)? to( the)* end( of the page)*$/, async function (pronounCase, theCase, pageCase) {
945
1400
  await this.page.evaluate(() => window.scrollTo(document.body.scrollWidth, window.scrollY));
946
1401
  });
947
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
+ */
948
1411
  When(/^(I scroll|we scroll|scrolling)? to start of "([^"]*)"$/, async function (pronounCase, selector) {
949
1412
  await this.page.locator(selector).evaluate(el => { el.scrollLeft = 0; });
950
1413
  });
951
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
+ */
952
1423
  When(/^(I scroll|we scroll|scrolling)? to end of "([^"]*)"$/, async function (pronounCase, selector) {
953
1424
  await this.page.locator(selector).evaluate(el => { el.scrollLeft = el.scrollWidth; });
954
1425
  });
955
1426
 
956
- // ---------------------------------------------------------------------------
957
- // Modal steps
958
- // ---------------------------------------------------------------------------
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
+ */
959
1437
  Then(/^(I |we )*should( not)* see (a |the )*modal( dialog)*$/, async function (pronounCase, notCase, aTheCase, dialogCase) {
960
1438
  const visible = await isAnyModalVisible(this.page);
961
1439
  if (notCase) {
@@ -965,6 +1443,16 @@ Then(/^(I |we )*should( not)* see (a |the )*modal( dialog)*$/, async function (p
965
1443
  }
966
1444
  });
967
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
+ */
968
1456
  Then(/^(I |we )*should( not)* see (a |the )*modal with title "([^"]*)?"$/, async function (pronounCase, notCase, aTheCase, title) {
969
1457
  const modal = this.page.locator(MODAL_SELECTOR);
970
1458
  const byHeading = modal.locator('.modal-title, .dialog-title, h1, h2, h3').filter({ hasText: title });
@@ -977,6 +1465,16 @@ Then(/^(I |we )*should( not)* see (a |the )*modal with title "([^"]*)?"$/, async
977
1465
  }
978
1466
  });
979
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
+ */
980
1478
  Then(/^(I |we )*should( not)* see (a |the )*"([^"]*)?" modal$/, async function (pronounCase, notCase, aTheCase, identifier) {
981
1479
  const selector = (identifier.startsWith('#') || identifier.startsWith('.'))
982
1480
  ? identifier
@@ -989,6 +1487,15 @@ Then(/^(I |we )*should( not)* see (a |the )*"([^"]*)?" modal$/, async function (
989
1487
  }
990
1488
  });
991
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
+ */
992
1499
  Then(/^(I |we )*should( not)* see "([^"]*)?" in( the)* modal( dialog)*$/, async function (pronounCase, notCase, expectedText, theCase, dialogCase) {
993
1500
  const found = await this.page.locator(MODAL_SELECTOR).filter({ hasText: expectedText }).count() > 0;
994
1501
  if (notCase) {
@@ -998,6 +1505,15 @@ Then(/^(I |we )*should( not)* see "([^"]*)?" in( the)* modal( dialog)*$/, async
998
1505
  }
999
1506
  });
1000
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
+ */
1001
1517
  When(/^(I |we )*click "([^"]*)?"( button)* in( the)* modal( dialog)*$/, async function (pronounCase, buttonText, buttonCase, theCase, dialogCase) {
1002
1518
  await waitForModalState(this.page, 'visible', 10000);
1003
1519
  const modal = await findVisibleModal(this.page);
@@ -1007,6 +1523,15 @@ When(/^(I |we )*click "([^"]*)?"( button)* in( the)* modal( dialog)*$/, async fu
1007
1523
  .click();
1008
1524
  });
1009
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
+ */
1010
1535
  When(/^(I |we )*(close|dismiss)( the)* modal( dialog)*$/, async function (pronounCase, closeOrDismiss, theCase, dialogCase) {
1011
1536
  await waitForModalState(this.page, 'visible', 10000);
1012
1537
  const modal = await findVisibleModal(this.page);
@@ -1018,7 +1543,91 @@ When(/^(I |we )*(close|dismiss)( the)* modal( dialog)*$/, async function (pronou
1018
1543
  }
1019
1544
  });
1020
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
+ */
1021
1555
  When(/^(I |we )*wait for( the)* modal( dialog)* to (appear|disappear)$/, async function (pronounCase, theCase, dialogCase, appearOrDisappear) {
1022
1556
  const state = appearOrDisappear === 'appear' ? 'visible' : 'hidden';
1023
1557
  await waitForModalState(this.page, state, 10000);
1024
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
+ });