webship-js 2.0.2 → 2.0.4

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 (181) hide show
  1. package/.circleci/config.yml +7 -31
  2. package/.drone.yml +68 -0
  3. package/.harness/webship-js-pipeline.yml +101 -0
  4. package/.semaphore/semaphore.yml +58 -0
  5. package/.teamcity/pom.xml +52 -0
  6. package/.teamcity/settings.kts +92 -0
  7. package/.travis.yml +24 -3
  8. package/AGENTS.md +109 -0
  9. package/CLAUDE.md +317 -0
  10. package/Jenkinsfile +54 -0
  11. package/azure-pipelines.yml +82 -0
  12. package/bamboo-specs/bamboo.yml +131 -0
  13. package/bin/generate-reports.js +181 -9
  14. package/buildspec.yml +56 -0
  15. package/cloudbuild.yaml +49 -0
  16. package/codefresh.yml +77 -0
  17. package/cucumber.js +48 -5
  18. package/docs/00-quick-start.md +102 -0
  19. package/docs/01-getting-started.md +102 -0
  20. package/docs/02-bbr-smart-waits.md +77 -0
  21. package/docs/03-selector-registry.md +95 -0
  22. package/docs/04-step-reference.md +799 -0
  23. package/docs/05-web-first-assertions.md +91 -0
  24. package/docs/06-network-and-dialogs.md +83 -0
  25. package/docs/07-auth-state.md +75 -0
  26. package/docs/08-clock-mocking.md +59 -0
  27. package/docs/09-api-testing.md +114 -0
  28. package/docs/10-accessibility.md +167 -0
  29. package/docs/11-debugging.md +129 -0
  30. package/docs/12-ai-agent-guide.md +338 -0
  31. package/docs/13-faq.md +236 -0
  32. package/docs/14-recipes-cookbook.md +255 -0
  33. package/docs/15-tag-conventions.md +76 -0
  34. package/docs/16-ci-cd.md +879 -0
  35. package/docs/README.md +113 -0
  36. package/docs/advanced-screenshots/then-i-save-fullscreen-screenshot.md +36 -0
  37. package/docs/advanced-screenshots/then-i-save-width-x-height-screenshot.md +34 -0
  38. package/docs/advanced-screenshots/when-i-save-screenshot-name-filename.md +45 -0
  39. package/docs/advanced-screenshots.md +52 -0
  40. package/docs/advanced-selectors.md +18 -0
  41. package/docs/api-step-definitions.md +45 -0
  42. package/docs/diffy-step-definitions/then-compare-diffy-env1-env2.md +30 -0
  43. package/docs/diffy-step-definitions/then-create-diffy-comparison-name-value.md +21 -0
  44. package/docs/diffy-step-definitions/then-create-diffy-comparison.md +25 -0
  45. package/docs/diffy-step-definitions/then-create-diffy-screenshot-environment-name.md +35 -0
  46. package/docs/diffy-step-definitions/then-i-take-screenshot.md +21 -0
  47. package/docs/diffy-step-definitions/then-i-take-screenshots-all-breakpoints.md +27 -0
  48. package/docs/diffy-step-definitions/then-send-screenshots-diffy-name-value.md +27 -0
  49. package/docs/diffy-step-definitions/then-upload-folder-url-diffy-snapshotname.md +28 -0
  50. package/docs/diffy-step-definitions/then-wait-diffy-comparison-complete.md +21 -0
  51. package/docs/diffy-step-definitions/when-i-resize-window-number.md +29 -0
  52. package/docs/diffy-step-definitions.md +21 -0
  53. package/docs/global-settings.md +295 -0
  54. package/docs/install-webship-js/ddev-webship-js.md +52 -0
  55. package/docs/install-webship-js.md +35 -0
  56. package/docs/overview.md +41 -0
  57. package/docs/step-definitions/given-i-am-anonymous-user.md +67 -0
  58. package/docs/step-definitions/given-i-am-homepage.md +68 -0
  59. package/docs/step-definitions/given-i-am-specific-page.md +72 -0
  60. package/docs/step-definitions/then-i-should-be.md +56 -0
  61. package/docs/step-definitions/then-i-should-see.md +62 -0
  62. package/docs/step-definitions/then-item-checkbox.md +54 -0
  63. package/docs/step-definitions/then-item-link-should-contain-url.md +84 -0
  64. package/docs/step-definitions/then-item-should-contain.md +67 -0
  65. package/docs/step-definitions/then-radio-button-value-should-be-selected.md +68 -0
  66. package/docs/step-definitions/then-response-status-code-should-be-number.md +69 -0
  67. package/docs/step-definitions/then-value-radio-button-selected.md +62 -0
  68. package/docs/step-definitions/when-i-attach-file-file-name-element.md +71 -0
  69. package/docs/step-definitions/when-i-check-checkbox.md +60 -0
  70. package/docs/step-definitions/when-i-click-link.md +51 -0
  71. package/docs/step-definitions/when-i-click-operation-text-row.md +71 -0
  72. package/docs/step-definitions/when-i-fill.md +59 -0
  73. package/docs/step-definitions/when-i-go-homepage.md +60 -0
  74. package/docs/step-definitions/when-i-go-specific-page.md +67 -0
  75. package/docs/step-definitions/when-i-move-backward-one-page.md +49 -0
  76. package/docs/step-definitions/when-i-move-forward-one-page.md +58 -0
  77. package/docs/step-definitions/when-i-press-button.md +58 -0
  78. package/docs/step-definitions/when-i-reload-page.md +51 -0
  79. package/docs/step-definitions/when-i-scroll.md +73 -0
  80. package/docs/step-definitions/when-i-select-option-select-list.md +53 -0
  81. package/docs/step-definitions/when-i-select-radio-button-value.md +62 -0
  82. package/docs/step-definitions/when-i-uncheck-checkbox.md +57 -0
  83. package/docs/step-definitions/when-i-wait-ajax-finish.md +64 -0
  84. package/docs/step-definitions/when-i-wait.md +62 -0
  85. package/docs/step-definitions.md +50 -0
  86. package/examples/a11y.html +31 -0
  87. package/examples/cookies.html +10 -0
  88. package/examples/date.html +12 -0
  89. package/examples/element.html +11 -0
  90. package/examples/field.html +24 -0
  91. package/examples/keyboard.html +11 -0
  92. package/examples/links.html +9 -0
  93. package/examples/modal.html +14 -0
  94. package/examples/path.html +3 -0
  95. package/examples/table.html +13 -0
  96. package/examples/video-demo.html +43 -0
  97. package/package.json +10 -3
  98. package/playwright.config.ts +3 -2
  99. package/tests/features/a11y.feature +39 -0
  100. package/tests/features/cookie.feature +13 -0
  101. package/tests/features/date.feature +11 -0
  102. package/tests/features/element.feature +16 -0
  103. package/tests/features/field.feature +25 -0
  104. package/tests/features/keyboard.feature +10 -0
  105. package/tests/features/link.feature +11 -0
  106. package/tests/features/modal-advanced-example.feature +1 -1
  107. package/tests/features/modal.feature +11 -0
  108. package/tests/features/path.feature +16 -0
  109. package/tests/features/response.feature +8 -0
  110. package/tests/features/responsive.feature +10 -0
  111. package/tests/features/table.feature +18 -0
  112. package/tests/features/video.feature +18 -0
  113. package/tests/features/wait.feature +7 -0
  114. package/tests/features/yaml.feature +102 -0
  115. package/tests/reports/README.md +55 -0
  116. package/tests/selectors/_canonical-keys.json +113 -0
  117. package/tests/selectors/back-end-selectors.json +7 -1
  118. package/tests/selectors/cms-contentful-admin.json +35 -0
  119. package/tests/selectors/cms-craft-admin.json +39 -0
  120. package/tests/selectors/cms-drupal-cms-gin.json +56 -0
  121. package/tests/selectors/cms-drupal-core-claro.json +50 -0
  122. package/tests/selectors/cms-generic-admin.json +34 -0
  123. package/tests/selectors/cms-ghost-admin.json +34 -0
  124. package/tests/selectors/cms-joomla-admin.json +41 -0
  125. package/tests/selectors/cms-magento2-admin.json +32 -0
  126. package/tests/selectors/cms-prestashop-admin.json +38 -0
  127. package/tests/selectors/cms-shopify-admin.json +25 -0
  128. package/tests/selectors/cms-strapi-admin.json +42 -0
  129. package/tests/selectors/cms-typo3-admin.json +41 -0
  130. package/tests/selectors/cms-woocommerce-front.json +50 -0
  131. package/tests/selectors/cms-wordpress-admin.json +31 -0
  132. package/tests/selectors/framework-ant-design.json +80 -0
  133. package/tests/selectors/framework-bootstrap.json +86 -0
  134. package/tests/selectors/framework-bulma.json +74 -0
  135. package/tests/selectors/framework-chakra.json +58 -0
  136. package/tests/selectors/framework-foundation.json +51 -0
  137. package/tests/selectors/framework-material-ui.json +72 -0
  138. package/tests/selectors/framework-shadcn.json +51 -0
  139. package/tests/selectors/framework-tailwind.json +40 -0
  140. package/tests/selectors/framework-vuetify.json +61 -0
  141. package/tests/step-definitions/a11y.steps.js +800 -0
  142. package/tests/step-definitions/action.steps.js +167 -0
  143. package/tests/step-definitions/{webship-api.js → api.steps.js} +41 -23
  144. package/tests/step-definitions/assertion.steps.js +352 -0
  145. package/tests/step-definitions/auth.steps.js +126 -0
  146. package/tests/step-definitions/clock.steps.js +128 -0
  147. package/tests/step-definitions/cookie.steps.js +216 -0
  148. package/tests/step-definitions/debug.steps.js +39 -0
  149. package/tests/step-definitions/dialog.steps.js +193 -0
  150. package/tests/step-definitions/element.steps.js +356 -0
  151. package/tests/step-definitions/field.steps.js +653 -0
  152. package/tests/step-definitions/file-download.steps.js +211 -0
  153. package/tests/step-definitions/form.steps.js +333 -0
  154. package/tests/step-definitions/iframe.steps.js +228 -0
  155. package/tests/step-definitions/input.steps.js +202 -0
  156. package/tests/step-definitions/javascript.steps.js +232 -0
  157. package/tests/step-definitions/keyboard.steps.js +112 -0
  158. package/tests/step-definitions/link.steps.js +142 -0
  159. package/tests/step-definitions/metatag.steps.js +91 -0
  160. package/tests/step-definitions/modal.steps.js +244 -0
  161. package/tests/step-definitions/navigation.steps.js +218 -0
  162. package/tests/step-definitions/network.steps.js +280 -0
  163. package/tests/step-definitions/path.steps.js +141 -0
  164. package/tests/step-definitions/response.steps.js +98 -0
  165. package/tests/step-definitions/responsive.steps.js +125 -0
  166. package/tests/step-definitions/rest.steps.js +111 -0
  167. package/tests/step-definitions/{webship-screenshot.js → screenshot.steps.js} +1 -5
  168. package/tests/step-definitions/scroll.steps.js +189 -0
  169. package/tests/step-definitions/{webship-selectors.js → selectors.steps.js} +64 -27
  170. package/tests/step-definitions/storage.steps.js +194 -0
  171. package/tests/step-definitions/table.steps.js +181 -0
  172. package/tests/step-definitions/video.steps.js +178 -0
  173. package/tests/step-definitions/wait.steps.js +400 -0
  174. package/tests/step-definitions/web-first.steps.js +298 -0
  175. package/tests/step-definitions/webship.js +741 -1477
  176. package/tests/step-definitions/xml.steps.js +411 -0
  177. package/tests/step-definitions/yaml.steps.js +913 -0
  178. package/tests/step-definitions-diffy/webship-diffy.js +0 -13
  179. package/tsconfig.json +19 -3
  180. package/videos/README.md +32 -0
  181. package/.travis-ci.yml +0 -16
@@ -0,0 +1,178 @@
1
+ 'use strict';
2
+
3
+ const { friendly } = require('./webship');
4
+
5
+ // Video recording steps — start / stop / save mid-scenario.
6
+ //
7
+ // Playwright records video only at browser-context creation. Mid-scenario
8
+ // `start` / `stop` therefore work by tearing down the current page +
9
+ // context and reopening with the new recording flag. Page state is lost
10
+ // across the boundary — call `start` BEFORE any navigation and `stop` only
11
+ // when you no longer need the current page state.
12
+ //
13
+ // Default mode is 'off' (no recording). See cucumber.js → worldParameters.video.
14
+
15
+ const { When, Then } = require('@cucumber/cucumber');
16
+ const fs = require('fs');
17
+ const path = require('path');
18
+
19
+ function settings(world) {
20
+ const cfg = (world.parameters && world.parameters.video) || {};
21
+ return {
22
+ dir: process.env.WEBSHIP_VIDEO_DIR || cfg.dir || './videos',
23
+ size: cfg.size || { width: 1280, height: 720 },
24
+ };
25
+ }
26
+
27
+ async function rebuildContext(world, recordVideo) {
28
+ await world.closeBrowser();
29
+ if (recordVideo) {
30
+ const s = settings(world);
31
+ fs.mkdirSync(s.dir, { recursive: true });
32
+ world._videoRequested = true;
33
+ await world.openBrowser({ recordVideo: { dir: s.dir, size: s.size } });
34
+ } else {
35
+ world._videoRequested = false;
36
+ await world.openBrowser();
37
+ }
38
+ }
39
+
40
+ /**
41
+ * Start recording the browser as a webm video. Closes the current page +
42
+ * context and reopens with `recordVideo` enabled. Place BEFORE any
43
+ * navigation in the scenario.
44
+ *
45
+ * Example #1: When I start video recording
46
+ * Example #2: And I start video recording
47
+ * Example #3: Given I start video recording
48
+ * Example #4: But I start video recording
49
+ * Example #5: Then I start video recording
50
+ *
51
+ */
52
+ When(/^(I |we )*start video recording$/, async function (pronoun) {
53
+ try {
54
+ await rebuildContext(this, true);
55
+ } catch (e) {
56
+ throw friendly({
57
+ action: 'start video recording',
58
+ cause: e,
59
+ hint: `the videos directory (${(this.parameters && this.parameters.video && this.parameters.video.dir) || './videos'}) must be writable.`,
60
+ });
61
+ }
62
+ });
63
+
64
+ /**
65
+ * Stop recording. Closes the current page + context (which flushes the
66
+ * webm to disk) and reopens a fresh, non-recording browser so the rest
67
+ * of the scenario can continue.
68
+ *
69
+ * Example #1: When I stop video recording
70
+ * Example #2: And I stop video recording
71
+ * Example #3: But I stop video recording
72
+ * Example #4: Then I stop video recording
73
+ * Example #5: Then I stop video recording
74
+ *
75
+ */
76
+ When(/^(I |we )*stop video recording$/, async function (pronoun) {
77
+ try {
78
+ if (!this.page || !this._videoRequested) return;
79
+ const video = this.page.video();
80
+ // Close context first — flushes the webm — then saveAs while the
81
+ // browser is still alive, finally close the browser and reopen fresh.
82
+ try { await this.context.close(); } catch { /* ignore */ }
83
+ if (video) {
84
+ try {
85
+ const s = settings(this);
86
+ const name = this._videoSaveAsName || `manual.${Date.now()}.webm`;
87
+ const dest = path.join(s.dir, name);
88
+ await video.saveAs(dest);
89
+ await video.delete().catch(() => {});
90
+ process.stderr.write(`\n[webship-js] video saved → ${dest}\n`);
91
+ // Reset so the After hook does not try to re-save.
92
+ this._videoSaveAsName = null;
93
+ } catch (e) {
94
+ process.stderr.write(`\n[webship-js] video save failed: ${e.message}\n`);
95
+ }
96
+ }
97
+ if (this.playwrightBrowser) {
98
+ try { await this.playwrightBrowser.close(); } catch { /* ignore */ }
99
+ this.playwrightBrowser = null;
100
+ }
101
+ this.context = null;
102
+ this.page = null;
103
+ this._videoRequested = false;
104
+ await this.openBrowser();
105
+ } catch (e) {
106
+ throw friendly({
107
+ action: 'stop video recording',
108
+ cause: e,
109
+ hint: 'the scenario will continue with a fresh, non-recording browser.',
110
+ });
111
+ }
112
+ });
113
+
114
+ /**
115
+ * Reserve a custom filename for the current scenario's video. The actual
116
+ * save happens at scenario end (Playwright's `video.saveAs()` blocks
117
+ * until recording finishes, so we cannot copy bytes mid-flight). If the
118
+ * scenario calls `stop video recording` before scenario end, the manual
119
+ * webm uses this name instead of the automatic timestamped one.
120
+ *
121
+ * Example #1: When I save the current video as "checkout-flow.webm"
122
+ * Example #2: When I save the current video as "regression-21.webm"
123
+ * Example #3: And I save the current video as "smoke.webm"
124
+ * Example #4: Then I save the current video as "demo.webm"
125
+ * Example #5: But I save the current video as "rerun.webm"
126
+ *
127
+ */
128
+ When(/^(I |we )*save the current video as "([^"]*)"$/, function (pronoun, name) {
129
+ try {
130
+ if (!this._videoRequested) {
131
+ throw new Error('recording is not active');
132
+ }
133
+ if (!name || !name.trim()) {
134
+ throw new Error('filename is empty');
135
+ }
136
+ this._videoSaveAsName = name;
137
+ } catch (e) {
138
+ throw friendly({
139
+ action: `save the current video as "${name}"`,
140
+ cause: e,
141
+ hint: 'call "When I start video recording" first, or set worldParameters.video.mode to "on".',
142
+ });
143
+ }
144
+ });
145
+
146
+ /**
147
+ * Print the path that the current video will be written to. Diagnostic
148
+ * only — never asserts, never fails.
149
+ *
150
+ * Example #1: Then print video path
151
+ * Example #2: And print video path
152
+ * Example #3: But print video path
153
+ * Example #4: Then print video path
154
+ * Example #5: Then print video path
155
+ *
156
+ */
157
+ Then(/^print video path$/, async function () {
158
+ // Diagnostic only — swallow every error and report inline.
159
+ try {
160
+ if (!this.page || !this._videoRequested) {
161
+ console.log('\n--- Video path: recording is OFF ---');
162
+ return;
163
+ }
164
+ const video = this.page.video();
165
+ if (!video) {
166
+ console.log('\n--- Video path: no video object on this page ---');
167
+ return;
168
+ }
169
+ try {
170
+ const p = await video.path();
171
+ console.log(`\n--- Video path: ${p} ---`);
172
+ } catch (e) {
173
+ console.log(`\n--- Video path unavailable: ${e.message} ---`);
174
+ }
175
+ } catch (e) {
176
+ console.log(`\n--- Video path error: ${e.message} ---`);
177
+ }
178
+ });
@@ -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
+ });