webship-js 2.0.2 → 2.0.3

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 (162) hide show
  1. package/AGENTS.md +109 -0
  2. package/CLAUDE.md +317 -0
  3. package/bin/generate-reports.js +181 -9
  4. package/cucumber.js +10 -4
  5. package/docs/00-quick-start.md +102 -0
  6. package/docs/01-getting-started.md +102 -0
  7. package/docs/02-bbr-smart-waits.md +77 -0
  8. package/docs/03-selector-registry.md +95 -0
  9. package/docs/04-step-reference.md +728 -0
  10. package/docs/05-web-first-assertions.md +91 -0
  11. package/docs/06-network-and-dialogs.md +83 -0
  12. package/docs/07-auth-state.md +75 -0
  13. package/docs/08-clock-mocking.md +59 -0
  14. package/docs/09-api-testing.md +114 -0
  15. package/docs/10-accessibility.md +167 -0
  16. package/docs/11-debugging.md +129 -0
  17. package/docs/12-ai-agent-guide.md +338 -0
  18. package/docs/13-faq.md +236 -0
  19. package/docs/14-recipes-cookbook.md +255 -0
  20. package/docs/15-tag-conventions.md +76 -0
  21. package/docs/advanced-screenshots/then-i-save-fullscreen-screenshot.md +36 -0
  22. package/docs/advanced-screenshots/then-i-save-width-x-height-screenshot.md +34 -0
  23. package/docs/advanced-screenshots/when-i-save-screenshot-name-filename.md +45 -0
  24. package/docs/advanced-screenshots.md +52 -0
  25. package/docs/advanced-selectors.md +18 -0
  26. package/docs/api-step-definitions.md +45 -0
  27. package/docs/diffy-step-definitions/then-compare-diffy-env1-env2.md +30 -0
  28. package/docs/diffy-step-definitions/then-create-diffy-comparison-name-value.md +21 -0
  29. package/docs/diffy-step-definitions/then-create-diffy-comparison.md +25 -0
  30. package/docs/diffy-step-definitions/then-create-diffy-screenshot-environment-name.md +35 -0
  31. package/docs/diffy-step-definitions/then-i-take-screenshot.md +21 -0
  32. package/docs/diffy-step-definitions/then-i-take-screenshots-all-breakpoints.md +27 -0
  33. package/docs/diffy-step-definitions/then-send-screenshots-diffy-name-value.md +27 -0
  34. package/docs/diffy-step-definitions/then-upload-folder-url-diffy-snapshotname.md +28 -0
  35. package/docs/diffy-step-definitions/then-wait-diffy-comparison-complete.md +21 -0
  36. package/docs/diffy-step-definitions/when-i-resize-window-number.md +29 -0
  37. package/docs/diffy-step-definitions.md +21 -0
  38. package/docs/global-settings.md +244 -0
  39. package/docs/index.md +104 -0
  40. package/docs/install-webship-js/ddev-webship-js.md +52 -0
  41. package/docs/install-webship-js.md +35 -0
  42. package/docs/overview.md +41 -0
  43. package/docs/step-definitions/given-i-am-anonymous-user.md +67 -0
  44. package/docs/step-definitions/given-i-am-homepage.md +68 -0
  45. package/docs/step-definitions/given-i-am-specific-page.md +72 -0
  46. package/docs/step-definitions/then-i-should-be.md +56 -0
  47. package/docs/step-definitions/then-i-should-see.md +62 -0
  48. package/docs/step-definitions/then-item-checkbox.md +54 -0
  49. package/docs/step-definitions/then-item-link-should-contain-url.md +84 -0
  50. package/docs/step-definitions/then-item-should-contain.md +67 -0
  51. package/docs/step-definitions/then-radio-button-value-should-be-selected.md +68 -0
  52. package/docs/step-definitions/then-response-status-code-should-be-number.md +69 -0
  53. package/docs/step-definitions/then-value-radio-button-selected.md +62 -0
  54. package/docs/step-definitions/when-i-attach-file-file-name-element.md +71 -0
  55. package/docs/step-definitions/when-i-check-checkbox.md +60 -0
  56. package/docs/step-definitions/when-i-click-link.md +51 -0
  57. package/docs/step-definitions/when-i-click-operation-text-row.md +71 -0
  58. package/docs/step-definitions/when-i-fill.md +59 -0
  59. package/docs/step-definitions/when-i-go-homepage.md +60 -0
  60. package/docs/step-definitions/when-i-go-specific-page.md +67 -0
  61. package/docs/step-definitions/when-i-move-backward-one-page.md +49 -0
  62. package/docs/step-definitions/when-i-move-forward-one-page.md +58 -0
  63. package/docs/step-definitions/when-i-press-button.md +58 -0
  64. package/docs/step-definitions/when-i-reload-page.md +51 -0
  65. package/docs/step-definitions/when-i-scroll.md +73 -0
  66. package/docs/step-definitions/when-i-select-option-select-list.md +53 -0
  67. package/docs/step-definitions/when-i-select-radio-button-value.md +62 -0
  68. package/docs/step-definitions/when-i-uncheck-checkbox.md +57 -0
  69. package/docs/step-definitions/when-i-wait-ajax-finish.md +64 -0
  70. package/docs/step-definitions/when-i-wait.md +62 -0
  71. package/docs/step-definitions.md +50 -0
  72. package/examples/a11y.html +31 -0
  73. package/examples/cookies.html +10 -0
  74. package/examples/date.html +12 -0
  75. package/examples/element.html +11 -0
  76. package/examples/field.html +24 -0
  77. package/examples/keyboard.html +11 -0
  78. package/examples/links.html +9 -0
  79. package/examples/modal.html +14 -0
  80. package/examples/path.html +3 -0
  81. package/examples/table.html +13 -0
  82. package/package.json +10 -3
  83. package/playwright.config.ts +3 -2
  84. package/tests/features/a11y.feature +39 -0
  85. package/tests/features/cookie.feature +13 -0
  86. package/tests/features/date.feature +11 -0
  87. package/tests/features/element.feature +16 -0
  88. package/tests/features/field.feature +25 -0
  89. package/tests/features/keyboard.feature +10 -0
  90. package/tests/features/link.feature +11 -0
  91. package/tests/features/modal-advanced-example.feature +1 -1
  92. package/tests/features/modal.feature +11 -0
  93. package/tests/features/path.feature +16 -0
  94. package/tests/features/response.feature +8 -0
  95. package/tests/features/responsive.feature +10 -0
  96. package/tests/features/table.feature +18 -0
  97. package/tests/features/wait.feature +7 -0
  98. package/tests/features/yaml.feature +102 -0
  99. package/tests/reports/README.md +55 -0
  100. package/tests/selectors/_canonical-keys.json +113 -0
  101. package/tests/selectors/back-end-selectors.json +7 -1
  102. package/tests/selectors/cms-contentful-admin.json +35 -0
  103. package/tests/selectors/cms-craft-admin.json +39 -0
  104. package/tests/selectors/cms-drupal-cms-gin.json +56 -0
  105. package/tests/selectors/cms-drupal-core-claro.json +50 -0
  106. package/tests/selectors/cms-generic-admin.json +34 -0
  107. package/tests/selectors/cms-ghost-admin.json +34 -0
  108. package/tests/selectors/cms-joomla-admin.json +41 -0
  109. package/tests/selectors/cms-magento2-admin.json +32 -0
  110. package/tests/selectors/cms-prestashop-admin.json +38 -0
  111. package/tests/selectors/cms-shopify-admin.json +25 -0
  112. package/tests/selectors/cms-strapi-admin.json +42 -0
  113. package/tests/selectors/cms-typo3-admin.json +41 -0
  114. package/tests/selectors/cms-woocommerce-front.json +50 -0
  115. package/tests/selectors/cms-wordpress-admin.json +31 -0
  116. package/tests/selectors/framework-ant-design.json +80 -0
  117. package/tests/selectors/framework-bootstrap.json +86 -0
  118. package/tests/selectors/framework-bulma.json +74 -0
  119. package/tests/selectors/framework-chakra.json +58 -0
  120. package/tests/selectors/framework-foundation.json +51 -0
  121. package/tests/selectors/framework-material-ui.json +72 -0
  122. package/tests/selectors/framework-shadcn.json +51 -0
  123. package/tests/selectors/framework-tailwind.json +40 -0
  124. package/tests/selectors/framework-vuetify.json +61 -0
  125. package/tests/step-definitions/a11y.steps.js +798 -0
  126. package/tests/step-definitions/action.steps.js +167 -0
  127. package/tests/step-definitions/{webship-api.js → api.steps.js} +24 -7
  128. package/tests/step-definitions/assertion.steps.js +352 -0
  129. package/tests/step-definitions/auth.steps.js +124 -0
  130. package/tests/step-definitions/clock.steps.js +128 -0
  131. package/tests/step-definitions/cookie.steps.js +216 -0
  132. package/tests/step-definitions/debug.steps.js +31 -0
  133. package/tests/step-definitions/dialog.steps.js +193 -0
  134. package/tests/step-definitions/element.steps.js +314 -0
  135. package/tests/step-definitions/field.steps.js +653 -0
  136. package/tests/step-definitions/file-download.steps.js +193 -0
  137. package/tests/step-definitions/form.steps.js +333 -0
  138. package/tests/step-definitions/iframe.steps.js +178 -0
  139. package/tests/step-definitions/input.steps.js +163 -0
  140. package/tests/step-definitions/javascript.steps.js +71 -0
  141. package/tests/step-definitions/keyboard.steps.js +78 -0
  142. package/tests/step-definitions/link.steps.js +142 -0
  143. package/tests/step-definitions/metatag.steps.js +91 -0
  144. package/tests/step-definitions/modal.steps.js +219 -0
  145. package/tests/step-definitions/navigation.steps.js +218 -0
  146. package/tests/step-definitions/network.steps.js +238 -0
  147. package/tests/step-definitions/path.steps.js +141 -0
  148. package/tests/step-definitions/response.steps.js +98 -0
  149. package/tests/step-definitions/responsive.steps.js +123 -0
  150. package/tests/step-definitions/rest.steps.js +111 -0
  151. package/tests/step-definitions/{webship-screenshot.js → screenshot.steps.js} +1 -5
  152. package/tests/step-definitions/scroll.steps.js +189 -0
  153. package/tests/step-definitions/{webship-selectors.js → selectors.steps.js} +46 -11
  154. package/tests/step-definitions/storage.steps.js +194 -0
  155. package/tests/step-definitions/table.steps.js +181 -0
  156. package/tests/step-definitions/wait.steps.js +400 -0
  157. package/tests/step-definitions/web-first.steps.js +296 -0
  158. package/tests/step-definitions/webship.js +552 -1507
  159. package/tests/step-definitions/xml.steps.js +409 -0
  160. package/tests/step-definitions/yaml.steps.js +911 -0
  161. package/tests/step-definitions-diffy/webship-diffy.js +0 -13
  162. package/tsconfig.json +19 -3
@@ -0,0 +1,181 @@
1
+ 'use strict';
2
+
3
+ // Inspect and assert HTML table contents.
4
+
5
+ const { Then } = require('@cucumber/cucumber');
6
+ const assert = require('assert');
7
+
8
+ async function getTable(page, sel) {
9
+ return await page.locator(sel).first().evaluate((tbl) => {
10
+ const rows = Array.from(tbl.querySelectorAll('tr'));
11
+ const head = Array.from((tbl.querySelector('thead') || tbl).querySelectorAll('th')).map((c) => c.textContent.trim());
12
+ const body = rows
13
+ .filter((r) => r.querySelector('td'))
14
+ .map((r) => Array.from(r.querySelectorAll('td')).map((c) => c.textContent.trim()));
15
+ return { head, body, rowCount: body.length, colCount: (body[0] || head).length };
16
+ });
17
+ }
18
+
19
+ /**
20
+ * Assert a table has exactly N body rows.
21
+ *
22
+ * Example #1: Then the table "#users" should have 5 rows
23
+ * Example #2: Then the table "table.orders" should have 1 row
24
+ * Example #3: And the table "[data-testid=products]" should have 12 rows
25
+ * Example #4: Then the table "#audit-log" should have 0 rows
26
+ * Example #5: Then the table "table.responsive" should have 20 rows
27
+ *
28
+ */
29
+ Then('the table {string} should have {int} row(s)', async function (sel, count) {
30
+ const t = await getTable(this.page, sel);
31
+ assert.strictEqual(t.rowCount, count, `Table "${sel}" has ${t.rowCount} rows, expected ${count}.`);
32
+ });
33
+
34
+ /**
35
+ * Assert a table has exactly N columns.
36
+ *
37
+ * Example #1: Then the table "#users" should have 4 columns
38
+ * Example #2: Then the table "table.orders" should have 6 columns
39
+ * Example #3: And the table "[data-testid=products]" should have 5 columns
40
+ * Example #4: Then the table "#summary" should have 2 columns
41
+ * Example #5: Then the table "table.responsive" should have 8 columns
42
+ *
43
+ */
44
+ Then('the table {string} should have {int} column(s)', async function (sel, count) {
45
+ const t = await getTable(this.page, sel);
46
+ assert.strictEqual(t.colCount, count, `Table "${sel}" has ${t.colCount} columns, expected ${count}.`);
47
+ });
48
+
49
+ /**
50
+ * Assert the table header contains every column listed in the table.
51
+ *
52
+ * Example #1: Then the table "#users" should contain the following columns:
53
+ * | Name |
54
+ * | Email |
55
+ * Example #2: Then the table "table.orders" should contain the following columns:
56
+ * | Order ID | Status | Total |
57
+ * Example #3: And the table "[data-testid=products]" should contain the following columns:
58
+ * | Title | Price | Stock |
59
+ * Example #4: Then the table "#audit-log" should contain the following columns:
60
+ * | Timestamp | Actor | Action |
61
+ * Example #5: Then the table ".grid" should contain the following columns:
62
+ * | Country | Population | Capital |
63
+ *
64
+ */
65
+ Then('the table {string} should contain the following columns:', async function (sel, table) {
66
+ const t = await getTable(this.page, sel);
67
+ const want = table.raw().flat();
68
+ for (const col of want) {
69
+ assert.ok(t.head.includes(col), `Column "${col}" not found in [${t.head.join(', ')}].`);
70
+ }
71
+ });
72
+
73
+ /**
74
+ * Assert a table has zero body rows.
75
+ *
76
+ * Example #1: Then the table "#users" should be empty
77
+ * Example #2: Then the table "table.orders" should be empty
78
+ * Example #3: And the table "[data-testid=products]" should be empty
79
+ * Example #4: Then the table "#audit-log" should be empty
80
+ * Example #5: Then the table ".grid" should be empty
81
+ *
82
+ */
83
+ Then('the table {string} should be empty', async function (sel) {
84
+ const t = await getTable(this.page, sel);
85
+ assert.strictEqual(t.rowCount, 0, `Table "${sel}" should be empty.`);
86
+ });
87
+
88
+ /**
89
+ * Assert a table has at least one body row.
90
+ *
91
+ * Example #1: Then the table "#users" should not be empty
92
+ * Example #2: Then the table "table.orders" should not be empty
93
+ * Example #3: And the table "[data-testid=products]" should not be empty
94
+ * Example #4: Then the table "#audit-log" should not be empty
95
+ * Example #5: Then the table ".grid" should not be empty
96
+ *
97
+ */
98
+ Then('the table {string} should not be empty', async function (sel) {
99
+ const t = await getTable(this.page, sel);
100
+ assert.ok(t.rowCount > 0, `Table "${sel}" should not be empty.`);
101
+ });
102
+
103
+ /**
104
+ * Assert a table is sorted ascending or descending by a header.
105
+ *
106
+ * Direction accepts `ascending` / `asc` / `descending` / `desc`.
107
+ *
108
+ * Example #1: Then the table "#users" should be sorted by "Name" in "ascending" order
109
+ * Example #2: Then the table "table.orders" should be sorted by "Total" in "descending" order
110
+ * Example #3: And the table "[data-testid=products]" should be sorted by "Price" in "asc" order
111
+ * Example #4: Then the table "#audit-log" should be sorted by "Timestamp" in "desc" order
112
+ * Example #5: Then the table ".grid" should be sorted by "Country" in "ascending" order
113
+ *
114
+ */
115
+ Then('the table {string} should be sorted by {string} in {string} order', async function (sel, column, direction) {
116
+ const t = await getTable(this.page, sel);
117
+ const idx = t.head.findIndex((h) => h === column);
118
+ assert.ok(idx !== -1, `Column "${column}" not found.`);
119
+ const values = t.body.map((r) => r[idx]);
120
+ const sorted = [...values].sort();
121
+ if (direction.toLowerCase() === 'descending' || direction.toLowerCase() === 'desc') sorted.reverse();
122
+ assert.deepStrictEqual(values, sorted, `Table "${sel}" not sorted by "${column}" ${direction}.`);
123
+ });
124
+
125
+ /**
126
+ * Assert a table contains every row described by the data table (substring match per cell).
127
+ *
128
+ * Example #1: Then the table "#users" should contain the following rows:
129
+ * | Alice | Editor |
130
+ * | Bob | Admin |
131
+ * Example #2: Then the table "table.orders" should contain the following rows:
132
+ * | 1234 | Shipped |
133
+ * | 5678 | Cancelled |
134
+ * Example #3: And the table "[data-testid=products]" should contain the following rows:
135
+ * | Laptop | $999.00 |
136
+ * Example #4: Then the table "#audit-log" should contain the following rows:
137
+ * | login |
138
+ * Example #5: Then the table ".grid" should contain the following rows:
139
+ * | Jordan | Amman |
140
+ *
141
+ */
142
+ Then('the table {string} should contain the following rows:', async function (sel, table) {
143
+ const t = await getTable(this.page, sel);
144
+ for (const row of table.raw()) {
145
+ const found = t.body.some((br) => row.every((cell) => br.some((bc) => bc.indexOf(cell) !== -1)));
146
+ assert.ok(found, `Row ${JSON.stringify(row)} not found in table.`);
147
+ }
148
+ });
149
+
150
+ /**
151
+ * Assert a row containing a given text fragment also contains every listed cell value.
152
+ *
153
+ * Example #1: Then the "Alice" row should contain the following:
154
+ * | Editor |
155
+ * | Active |
156
+ * Example #2: Then the "Order #1234" row should contain the following:
157
+ * | Shipped |
158
+ * Example #3: And the "Project Alpha" row should contain the following:
159
+ * | Open |
160
+ * | High |
161
+ * Example #4: Then the "alice@example.com" row should contain the following:
162
+ * | Admin |
163
+ * Example #5: Then the "Premium" row should contain the following:
164
+ * | $99 |
165
+ *
166
+ */
167
+ Then('the {string} row should contain the following:', async function (rowText, table) {
168
+ const cells = table.raw().flat();
169
+ // Find a tr whose text contains rowText.
170
+ const trs = await this.page.locator('tr').all();
171
+ let match = null;
172
+ for (const tr of trs) {
173
+ const txt = await tr.innerText();
174
+ if (txt.indexOf(rowText) !== -1) { match = tr; break; }
175
+ }
176
+ assert.ok(match, `No row matching "${rowText}" was found.`);
177
+ const text = await match.innerText();
178
+ for (const c of cells) {
179
+ assert.ok(text.indexOf(c) !== -1, `Row "${rowText}" does not contain "${c}".`);
180
+ }
181
+ });
@@ -0,0 +1,400 @@
1
+ 'use strict';
2
+
3
+ // All wait/settle step definitions live in this file.
4
+ //
5
+ // Behavior-Based Robotics (BBR) principle: react to the environment, not the
6
+ // clock. A wait step never blocks for a fixed duration — it returns as soon
7
+ // as the page is at the *edge* of activity, bounded by a budget so a runaway
8
+ // page cannot stall the run.
9
+ //
10
+ // Shared smartSettle and modal probes are imported from webship.js
11
+ // so this file never duplicates BBR plumbing.
12
+
13
+ const { When } = require('@cucumber/cucumber');
14
+ const { smartSettle, waitForModalState } = require('./webship');
15
+
16
+ /**
17
+ * Wait UP TO N seconds for the page to settle. Returns early on idle.
18
+ *
19
+ * "Settle" = DOM ready, no in-flight fetch/XHR, no pending setTimeout
20
+ * callbacks, and no MutationObserver activity for at least 250 ms.
21
+ *
22
+ * Example #1: When I wait for 1 second
23
+ * Example #2: When I wait for 5 seconds
24
+ * Example #3: And I wait for 3 seconds
25
+ * Example #4: When we wait for 2 seconds
26
+ * Example #5: And we wait for 10 seconds
27
+ * Example #6: When I press "Save"
28
+ * And I wait for 2 seconds
29
+ * Then I should see "Saved"
30
+ *
31
+ */
32
+ When(/^(I |we )*wait for (\d+) seconds?$/, async function (pronoun, seconds) {
33
+ await smartSettle(this.page, parseInt(seconds, 10) * 1000);
34
+ });
35
+
36
+ /**
37
+ * Wait UP TO N seconds for the page (and AJAX) to settle. Returns early.
38
+ *
39
+ * Same probe as `wait for N seconds` — kept for legacy phrasing parity with
40
+ * older feature files that say "for AJAX to finish" explicitly.
41
+ *
42
+ * Example #1: When I wait for 1 second for AJAX to finish
43
+ * Example #2: When I wait for 3 seconds for AJAX to finish
44
+ * Example #3: And I wait for 5 seconds for AJAX to finish
45
+ * Example #4: When we wait for 2 seconds for AJAX to finish
46
+ * Example #5: When I press "Search"
47
+ * And I wait for 5 seconds for AJAX to finish
48
+ * Then I should see "Results"
49
+ *
50
+ */
51
+ When(/^(I |we )*wait for (\d+) seconds? for AJAX to finish$/, async function (pronoun, seconds) {
52
+ await smartSettle(this.page, parseInt(seconds, 10) * 1000);
53
+ });
54
+
55
+ /**
56
+ * Wait UP TO a number of seconds for the page to settle.
57
+ *
58
+ * Example #1: When I wait 1 second
59
+ * Example #2: When I wait 5 seconds
60
+ * Example #3: When we wait 3s
61
+ * Example #4: And wait 2s
62
+ * Example #5: And wait 2 seconds
63
+ * Example #6: When we wait 1 second
64
+ * Example #7: When we wait 5 seconds
65
+ * Example #8: When we wait 4s
66
+ *
67
+ */
68
+ When(/^(I |we )*wait (\d+)( second| seconds|s)?$/, async function (pronounCase, number, withSecondWord) {
69
+ await smartSettle(this.page, parseInt(number, 10) * 1000);
70
+ });
71
+
72
+ /**
73
+ * Wait UP TO a maximum number of seconds for the page to settle.
74
+ *
75
+ * Example #1: When I wait max of 1 second
76
+ * Example #2: When I wait max of 5 seconds
77
+ * Example #3: When we wait max of 3s
78
+ * Example #4: And wait max of 2s
79
+ * Example #5: And wait max of 2 seconds
80
+ * Example #6: When we wait max of 1 second
81
+ * Example #7: When we wait max of 5 seconds
82
+ * Example #8: When we wait max of 4s
83
+ *
84
+ */
85
+ When(/^(I |we )*wait max of (\d+)( second| seconds|s)?$/, async function (pronounCase, number, withSecondWord) {
86
+ await smartSettle(this.page, parseInt(number, 10) * 1000);
87
+ });
88
+
89
+ /**
90
+ * Wait UP TO a number of minutes for the page to settle.
91
+ *
92
+ * Example #1: When I wait 1 minute
93
+ * Example #2: When I wait 10 minutes
94
+ * Example #3: When we wait 1m
95
+ * Example #4: And wait 2m
96
+ * Example #5: And wait 2 minutes
97
+ *
98
+ */
99
+ When(/^(I |we )*wait (\d+)( minute| minutes|m)?$/, async function (pronounCase, number, withMinuteWord) {
100
+ await smartSettle(this.page, parseInt(number, 10) * 1000 * 60);
101
+ });
102
+
103
+ /**
104
+ * Wait UP TO a maximum number of minutes for the page to settle.
105
+ *
106
+ * Example #1: When I wait max of 1 minute
107
+ * Example #2: When I wait max of 10 minutes
108
+ * Example #3: When we wait max of 1m
109
+ * Example #4: And wait max of 2m
110
+ * Example #5: And wait max of 2 minutes
111
+ *
112
+ */
113
+ When(/^(I |we )*wait max of (\d+)( minute| minutes|m)?$/, async function (pronounCase, number, withMinuteWord) {
114
+ await smartSettle(this.page, parseInt(number, 10) * 1000 * 60);
115
+ });
116
+
117
+ /**
118
+ * Wait until the page is loaded.
119
+ *
120
+ * Example #1: When I wait until the page is loaded
121
+ * Example #2: When we wait until the page is loaded
122
+ * Example #3: When wait until page loaded
123
+ *
124
+ */
125
+ When(/^(I |we )*wait until( the)* page( is)* loaded*$/, async function (pronounCase, theCase, withIs) {
126
+ await smartSettle(this.page, 10000);
127
+ });
128
+
129
+ /**
130
+ * Wait for active XHR/fetch requests to complete.
131
+ *
132
+ * Example #1: When I wait for AJAX to finish
133
+ * Example #2: And I wait for AJAX to finish
134
+ * Example #3: When we wait for AJAX to finish
135
+ * Example #4: And wait for AJAX to finish
136
+ *
137
+ */
138
+ When(/^(I |we )*wait for AJAX to finish$/, async function (pronounCase) {
139
+ await smartSettle(this.page, 10000);
140
+ });
141
+
142
+ /**
143
+ * Wait for a modal dialog to appear or disappear.
144
+ *
145
+ * Example #1: When I wait for the modal to appear
146
+ * Example #2: When I wait for the modal to disappear
147
+ * Example #3: When we wait for modal to appear
148
+ * Example #4: And I wait for the modal dialog to disappear
149
+ *
150
+ */
151
+ When(/^(I |we )*wait for( the)* modal( dialog)* to (appear|disappear)$/, async function (pronounCase, theCase, dialogCase, appearOrDisappear) {
152
+ const state = appearOrDisappear === 'appear' ? 'visible' : 'hidden';
153
+ await waitForModalState(this.page, state, 10000, this);
154
+ });
155
+
156
+ /**
157
+ * Wait until a CSS selector becomes visible. Returns the moment the
158
+ * matching element is on screen (display !== 'none', visibility !== 'hidden',
159
+ * has a non-zero box). This is the canonical "wait until X appears" probe.
160
+ *
161
+ * Example #1: When I wait for "#dashboard" to appear
162
+ * Example #2: When I wait for ".success-banner" to appear
163
+ * Example #3: And I wait for "[data-testid=user-list]" to appear
164
+ * Example #4: When we wait for ".modal.show" to appear
165
+ * Example #5: When I press "Save"
166
+ * And I wait for ".toast-success" to appear
167
+ *
168
+ */
169
+ When(/^(I |we )*wait for "([^"]*)" to appear$/, async function (pronounCase, selector) {
170
+ await this.page.waitForSelector(selector, { state: 'visible', timeout: 10000 });
171
+ });
172
+
173
+ /**
174
+ * Wait until a CSS selector becomes hidden (display:none, visibility:hidden,
175
+ * detached, or zero-size).
176
+ *
177
+ * Example #1: When I wait for "#loading-spinner" to disappear
178
+ * Example #2: When I wait for ".overlay" to disappear
179
+ * Example #3: And I wait for ".modal.show" to disappear
180
+ * Example #4: When we wait for "[data-testid=skeleton]" to disappear
181
+ * Example #5: When I press "Submit"
182
+ * And I wait for ".loader" to disappear
183
+ * Then I should see "Saved"
184
+ *
185
+ */
186
+ When(/^(I |we )*wait for "([^"]*)" to disappear$/, async function (pronounCase, selector) {
187
+ await this.page.waitForSelector(selector, { state: 'hidden', timeout: 10000 });
188
+ });
189
+
190
+ /**
191
+ * Wait until visible text appears anywhere on the page.
192
+ *
193
+ * Polls `document.body.innerText` every 100 ms for up to 10 s. Match is
194
+ * case-sensitive substring.
195
+ *
196
+ * Example #1: When I wait for the text "Dashboard" to appear
197
+ * Example #2: When I wait for the text "Loading complete" to appear
198
+ * Example #3: And I wait for text "Welcome" to appear
199
+ * Example #4: When we wait for the text "Order #1234" to appear
200
+ * Example #5: When I press "Submit"
201
+ * And I wait for the text "Thank you" to appear
202
+ *
203
+ */
204
+ When(/^(I |we )*wait for( the)* text "([^"]*)" to appear$/, async function (pronounCase, theCase, text) {
205
+ await this.page.waitForFunction(
206
+ (t) => document.body && document.body.innerText.includes(t),
207
+ text, { timeout: 10000, polling: 100 }
208
+ );
209
+ });
210
+
211
+ /**
212
+ * Wait until visible text is gone from the page.
213
+ *
214
+ * Example #1: When I wait for the text "Loading…" to disappear
215
+ * Example #2: When I wait for the text "Saving" to disappear
216
+ * Example #3: And I wait for text "Pending" to disappear
217
+ * Example #4: When we wait for the text "Connecting" to disappear
218
+ * Example #5: When I press "Submit"
219
+ * And I wait for the text "Validating" to disappear
220
+ * Then I should see "Done"
221
+ *
222
+ */
223
+ When(/^(I |we )*wait for( the)* text "([^"]*)" to disappear$/, async function (pronounCase, theCase, text) {
224
+ await this.page.waitForFunction(
225
+ (t) => !document.body || !document.body.innerText.includes(t),
226
+ text, { timeout: 10000, polling: 100 }
227
+ );
228
+ });
229
+
230
+ /**
231
+ * Wait until the current URL contains a fragment.
232
+ *
233
+ * Useful after a redirect, push-state navigation, or hash-based routing.
234
+ *
235
+ * Example #1: When I wait until the URL contains "/dashboard"
236
+ * Example #2: When I wait until the URL contains "?step=2"
237
+ * Example #3: And I wait until the URL contains "#confirmation"
238
+ * Example #4: When we wait until the URL contains "/orders/"
239
+ * Example #5: When I follow "Sign in"
240
+ * And I wait until the URL contains "/auth/callback"
241
+ *
242
+ */
243
+ When(/^(I |we )*wait until( the)* URL contains "([^"]*)"$/, async function (pronounCase, theCase, fragment) {
244
+ await this.page.waitForFunction(
245
+ (frag) => window.location.href.includes(frag),
246
+ fragment, { timeout: 10000, polling: 100 }
247
+ );
248
+ });
249
+
250
+ /**
251
+ * Wait until `document.title` equals (`is`) or contains the given value.
252
+ *
253
+ * Example #1: When I wait until the page title is "Dashboard - MyApp"
254
+ * Example #2: When I wait until the page title contains "Dashboard"
255
+ * Example #3: And I wait until the page title contains "(3 unread)"
256
+ * Example #4: When we wait until the page title is "Order Placed"
257
+ * Example #5: When I follow "Inbox"
258
+ * And I wait until the page title contains "Inbox"
259
+ *
260
+ */
261
+ When(/^(I |we )*wait until( the)* page title (is|contains) "([^"]*)"$/, async function (pronounCase, theCase, op, value) {
262
+ await this.page.waitForFunction(
263
+ ({ op, value }) => op === 'is' ? document.title === value : document.title.includes(value),
264
+ { op, value }, { timeout: 10000, polling: 100 }
265
+ );
266
+ });
267
+
268
+ /**
269
+ * Wait until exactly N elements match a CSS selector.
270
+ *
271
+ * Use 0 to wait for elements to disappear, or a positive count to wait for
272
+ * a specific number to render.
273
+ *
274
+ * Example #1: When I wait until 5 elements match ".product-card"
275
+ * Example #2: When I wait until 0 elements match ".loading-skeleton"
276
+ * Example #3: And I wait until 1 element matches ".active-row"
277
+ * Example #4: When we wait until 10 elements match "tr.user"
278
+ * Example #5: When I press "Load more"
279
+ * And I wait until 20 elements match ".feed-item"
280
+ *
281
+ */
282
+ When(/^(I |we )*wait until (\d+) elements? match(?:es)? "([^"]*)"$/, async function (pronounCase, count, selector) {
283
+ const expected = parseInt(count, 10);
284
+ await this.page.waitForFunction(
285
+ ({ sel, n }) => document.querySelectorAll(sel).length === n,
286
+ { sel: selector, n: expected }, { timeout: 10000, polling: 100 }
287
+ );
288
+ });
289
+
290
+ /**
291
+ * Wait until at least N elements match a CSS selector.
292
+ *
293
+ * Useful for infinite-scroll / pagination tests where the lower bound matters
294
+ * but the exact count may vary.
295
+ *
296
+ * Example #1: When I wait until at least 3 elements match ".item"
297
+ * Example #2: When I wait until at least 1 element matches ".notification"
298
+ * Example #3: And I wait until at least 10 elements match ".feed-item"
299
+ * Example #4: When we wait until at least 5 elements match "tr"
300
+ * Example #5: When I scroll to the bottom
301
+ * And I wait until at least 25 elements match ".product-card"
302
+ *
303
+ */
304
+ When(/^(I |we )*wait until at least (\d+) elements? match(?:es)? "([^"]*)"$/, async function (pronounCase, count, selector) {
305
+ const expected = parseInt(count, 10);
306
+ await this.page.waitForFunction(
307
+ ({ sel, n }) => document.querySelectorAll(sel).length >= n,
308
+ { sel: selector, n: expected }, { timeout: 10000, polling: 100 }
309
+ );
310
+ });
311
+
312
+ /**
313
+ * Wait until the network goes quiet (full smart settle, 10 s budget).
314
+ *
315
+ * Three equivalent phrasings.
316
+ *
317
+ * Example #1: When I wait until the network is idle
318
+ * Example #2: And I wait until requests are complete
319
+ * Example #3: When we wait until network goes quiet
320
+ * Example #4: When I press "Search"
321
+ * And I wait until the network is idle
322
+ * Then I should see "Results"
323
+ * Example #5: When I press "Refresh"
324
+ * And I wait until requests are complete
325
+ *
326
+ */
327
+ When(/^(I |we )*wait until (the network is idle|requests are complete|network goes quiet)$/, async function () {
328
+ await smartSettle(this.page, 10000);
329
+ });
330
+
331
+ /**
332
+ * Wait until the page is interactive (DOMContentLoaded + body attached).
333
+ *
334
+ * Lighter than `wait until the network is idle` — does not wait for late
335
+ * fetch/XHR. Useful when you need to interact with the document early.
336
+ *
337
+ * Example #1: When I wait until the page is interactive
338
+ * Example #2: Given I am on "/heavy-page"
339
+ * When I wait until the page is interactive
340
+ * Example #3: And I wait until the page is interactive
341
+ * Example #4: When we wait until the page is interactive
342
+ * Example #5: Given I am on "/spa"
343
+ * When I wait until the page is interactive
344
+ * Then "<#root>" should be attached
345
+ *
346
+ */
347
+ When(/^(I |we )*wait until( the)* page is interactive$/, async function () {
348
+ await this.page.waitForSelector('body', { state: 'attached', timeout: 10000 });
349
+ await this.page.waitForLoadState('domcontentloaded', { timeout: 10000 });
350
+ });
351
+
352
+ /**
353
+ * Wait until every tracked `setTimeout` callback has fired.
354
+ *
355
+ * Catches "fade-out then display:none" close transitions, debounced renders,
356
+ * and any UI flow that schedules a delayed update without making a network
357
+ * request. Reads `window.__webshipPendingTimers`, the counter installed by
358
+ * webship.js's init script.
359
+ *
360
+ * Example #1: When I wait until pending timers settle
361
+ * Example #2: When I press "Close"
362
+ * And I wait until pending timers settle
363
+ * Then I should not see the modal
364
+ * Example #3: And I wait until pending timers settle
365
+ * Example #4: When we wait until pending timers settle
366
+ * Example #5: When I press "Toast"
367
+ * And I wait until pending timers settle
368
+ * Then I should not see "Saved"
369
+ *
370
+ */
371
+ When(/^(I |we )*wait until pending timers settle$/, async function () {
372
+ await this.page.waitForFunction(
373
+ () => {
374
+ const t = window.__webshipPendingTimers;
375
+ return typeof t !== 'number' || t <= 0;
376
+ },
377
+ null, { timeout: 10000, polling: 100 }
378
+ );
379
+ });
380
+
381
+ /**
382
+ * Pollable text assertion — retries the inner step until passing or timeout.
383
+ *
384
+ * Use sparingly; prefer explicit edge waits (`wait for "X" to appear`).
385
+ *
386
+ * Example #1: Then eventually I should see "Done"
387
+ * Example #2: Then eventually I should see "Loaded" within 5 seconds
388
+ * Example #3: And eventually we should see "Saved"
389
+ * Example #4: Then eventually I should see "Order Confirmed" within 30 seconds
390
+ * Example #5: When I press "Submit"
391
+ * Then eventually I should see "Submitted" within 8 seconds
392
+ *
393
+ */
394
+ When(/^eventually (I |we )*should see "([^"]*)"(?: within (\d+) seconds?)?$/, async function (pronoun, text, seconds) {
395
+ const total = (seconds ? parseInt(seconds, 10) : 10) * 1000;
396
+ await this.page.waitForFunction(
397
+ (t) => document.body && document.body.innerText.includes(t),
398
+ text, { timeout: total, polling: 100 }
399
+ );
400
+ });