webship-js 2.0.10 → 2.0.12

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 (248) hide show
  1. package/.circleci/config.yml +10 -1
  2. package/.drone.yml +7 -7
  3. package/.github/ISSUE_TEMPLATE/issue.md +37 -0
  4. package/.github/PULL_REQUEST_TEMPLATE.md +24 -0
  5. package/.github/workflows/github-actions.yml +101 -4
  6. package/.gitlab-ci.yml +9 -4
  7. package/.harness/webship-js-pipeline.yml +5 -6
  8. package/.semaphore/semaphore.yml +6 -9
  9. package/.teamcity/settings.kts +7 -6
  10. package/.travis.yml +6 -1
  11. package/AGENTS.md +1 -1
  12. package/CLAUDE.md +69 -24
  13. package/Jenkinsfile +5 -3
  14. package/README.md +13 -1
  15. package/azure-pipelines.yml +17 -8
  16. package/bamboo-specs/bamboo.yml +9 -15
  17. package/bin/generate-reports.js +51 -7
  18. package/bin/init-webship.js +127 -23
  19. package/bitbucket-pipelines.yml +5 -1
  20. package/buildspec.yml +6 -7
  21. package/cloudbuild.yaml +28 -12
  22. package/codefresh.yml +6 -6
  23. package/cucumber.js +46 -11
  24. package/docs/00-quick-start.md +38 -7
  25. package/docs/02-bbr-smart-waits.md +21 -10
  26. package/docs/03-selector-registry.md +24 -0
  27. package/docs/04-step-reference.md +53 -27
  28. package/docs/05-web-first-assertions.md +6 -0
  29. package/docs/07-auth-state.md +1 -1
  30. package/docs/08-clock-mocking.md +21 -2
  31. package/docs/09-api-testing.md +40 -2
  32. package/docs/10-accessibility.md +2 -0
  33. package/docs/11-debugging.md +24 -1
  34. package/docs/12-ai-agent-guide.md +8 -1
  35. package/docs/13-faq.md +75 -1
  36. package/docs/14-recipes-cookbook.md +2 -0
  37. package/docs/15-tag-conventions.md +5 -1
  38. package/docs/16-ci-cd.md +161 -124
  39. package/docs/README.md +5 -5
  40. package/docs/advanced-screenshots.md +3 -1
  41. package/docs/api-step-definitions.md +16 -2
  42. package/docs/global-settings.md +70 -18
  43. package/docs/install-webship-js/ddev-webship-js.md +3 -0
  44. package/docs/install-webship-js.md +16 -2
  45. package/docs/step-definitions/then-i-should-see.md +14 -1
  46. package/docs/step-definitions/then-item-checkbox.md +2 -0
  47. package/docs/step-definitions/when-i-fill.md +4 -0
  48. package/docs/step-definitions/when-i-select-option-select-list.md +2 -0
  49. package/examples/a11y-legacy-widget.html +34 -0
  50. package/examples/auth-state.html +42 -0
  51. package/examples/choice-controls.html +29 -0
  52. package/examples/clock.html +33 -0
  53. package/examples/datetime-fields.html +52 -0
  54. package/examples/downloads/webship-archive.zip +0 -0
  55. package/examples/downloads/webship-notes.txt +4 -0
  56. package/examples/downloads/webship-report.csv +4 -0
  57. package/examples/downloads.html +16 -0
  58. package/examples/element-selector-hint.html +16 -0
  59. package/examples/element-viewport.html +42 -0
  60. package/examples/field-states.html +27 -0
  61. package/examples/field-types.html +98 -0
  62. package/examples/fill-in-empty.html +26 -0
  63. package/examples/fill-unreachable.html +27 -0
  64. package/examples/iframe-inner.html +20 -0
  65. package/examples/iframe-nested.html +16 -0
  66. package/examples/iframe-newsletter.html +29 -0
  67. package/examples/iframe-order.html +26 -0
  68. package/examples/iframe-outer.html +15 -0
  69. package/examples/iframe.html +21 -0
  70. package/examples/javascript-errors.html +35 -0
  71. package/examples/links.html +1 -0
  72. package/examples/metatags.html +18 -0
  73. package/examples/mouse-and-pointer.html +83 -0
  74. package/examples/multi-value-fields.html +54 -0
  75. package/examples/native-dialogs.html +8 -0
  76. package/examples/network.html +83 -0
  77. package/examples/registered-names.html +15 -0
  78. package/examples/scroll-horizontal.html +50 -0
  79. package/examples/select-by-label.html +33 -0
  80. package/examples/selectors-position.html +29 -0
  81. package/examples/settle-budget.html +21 -0
  82. package/examples/sorted-tables.html +38 -0
  83. package/examples/storage.html +57 -0
  84. package/examples/text-matching.html +48 -0
  85. package/examples/text-order.html +25 -0
  86. package/examples/touch.html +22 -0
  87. package/examples/viewport-size.html +24 -0
  88. package/examples/viewport-top.html +36 -0
  89. package/examples/wait-conditions.html +69 -0
  90. package/examples/web-first.html +99 -0
  91. package/package.json +24 -2
  92. package/playwright.config.ts +3 -1
  93. package/tests/assets/catalog.xml +19 -0
  94. package/tests/assets/feed-namespaced.xml +13 -0
  95. package/tests/assets/sitemap.xml +14 -0
  96. package/tests/assets/webship-site-expected.yaml +21 -0
  97. package/tests/assets/webship-site.schema.json +46 -0
  98. package/tests/assets/webship-site.yaml +21 -0
  99. package/tests/check-api-launch-url.js +106 -0
  100. package/tests/check-assets.js +103 -0
  101. package/tests/check-attachments.js +105 -0
  102. package/tests/check-breakpoints.js +117 -0
  103. package/tests/check-clock.js +143 -0
  104. package/tests/check-config.js +90 -0
  105. package/tests/check-context.js +215 -0
  106. package/tests/check-dry-run.js +104 -0
  107. package/tests/check-examples.js +241 -0
  108. package/tests/check-exit-report.js +141 -0
  109. package/tests/check-javascript-errors.js +105 -0
  110. package/tests/check-must-fail.js +85 -0
  111. package/tests/check-paths.js +82 -0
  112. package/tests/check-report.js +119 -0
  113. package/tests/check-scaffold.js +246 -0
  114. package/tests/check-screenshots.js +117 -0
  115. package/tests/check-settle-verbs.js +137 -0
  116. package/tests/check-time-limit.js +104 -0
  117. package/tests/check-video.js +156 -0
  118. package/tests/check-world.js +167 -0
  119. package/tests/features/a11y.feature +18 -0
  120. package/tests/features/api-base-url.feature +25 -0
  121. package/tests/features/api-form-data.feature +18 -0
  122. package/tests/features/api-json-paths.feature +24 -0
  123. package/tests/features/api-response-contains.feature +21 -0
  124. package/tests/features/api-response-header-presence.feature +17 -0
  125. package/tests/features/api-response-header.feature +17 -0
  126. package/tests/features/api-saved-placeholders.feature +37 -0
  127. package/tests/features/api-step-definitions-individual.feature +1 -1
  128. package/tests/features/api-tables.feature +40 -0
  129. package/tests/features/auth-state.feature +32 -0
  130. package/tests/features/breakpoints.feature +25 -0
  131. package/tests/features/choice-controls.feature +35 -0
  132. package/tests/features/clock.feature +27 -0
  133. package/tests/features/complete-api-testing-examples.feature +1 -1
  134. package/tests/features/cookie.feature +9 -0
  135. package/tests/features/datetime-field-lookup.feature +29 -0
  136. package/tests/features/dialog.feature +27 -0
  137. package/tests/features/element-selector-hint.feature +14 -0
  138. package/tests/features/element.feature +47 -0
  139. package/tests/features/field-state.feature +21 -0
  140. package/tests/features/field.feature +104 -0
  141. package/tests/features/file-download.feature +64 -0
  142. package/tests/features/fill-in-empty-value.feature +41 -0
  143. package/tests/features/fill-reachable.feature +13 -0
  144. package/tests/features/iframe-nested.feature +43 -0
  145. package/tests/features/iframe.feature +83 -0
  146. package/tests/features/javascript-tolerated-errors.feature +20 -0
  147. package/tests/features/javascript.feature +47 -0
  148. package/tests/features/link.feature +11 -0
  149. package/tests/features/metatag.feature +38 -0
  150. package/tests/features/modal-open.feature +13 -0
  151. package/tests/features/mouse-and-pointer.feature +86 -0
  152. package/tests/features/multi-value-field-lookup.feature +30 -0
  153. package/tests/features/network-mocking.feature +80 -0
  154. package/tests/features/registered-names.feature +14 -0
  155. package/tests/features/responsive.feature +27 -0
  156. package/tests/features/scroll-horizontal.feature +55 -0
  157. package/tests/features/select-by-label.feature +31 -0
  158. package/tests/features/selector-files.feature +14 -0
  159. package/tests/features/selectors-position.feature +41 -0
  160. package/tests/features/selectors-table-header.feature +35 -0
  161. package/tests/features/settle-budget.feature +11 -0
  162. package/tests/features/sorted-tables.feature +19 -0
  163. package/tests/features/storage-quoted-values.feature +26 -0
  164. package/tests/features/storage.feature +98 -0
  165. package/tests/features/test--then--i-see-locator.feature +13 -0
  166. package/tests/features/test--then--i-should--see-text-in-element.feature +9 -1
  167. package/tests/features/test--then--the-field-should-contain-value.feature +8 -0
  168. package/tests/features/text-matching.feature +38 -0
  169. package/tests/features/text-order.feature +14 -0
  170. package/tests/features/touch.feature +21 -0
  171. package/tests/features/video.feature +1 -0
  172. package/tests/features/viewport-top.feature +13 -0
  173. package/tests/features/wait.feature +89 -0
  174. package/tests/features/web-first.feature +100 -0
  175. package/tests/features/xml-namespaces.feature +34 -0
  176. package/tests/features/xml.feature +96 -0
  177. package/tests/features/yaml.feature +75 -0
  178. package/tests/must-fail/api-json-paths.feature +21 -0
  179. package/tests/must-fail/api-response-contains.feature +23 -0
  180. package/tests/must-fail/api-response-header-presence.feature +17 -0
  181. package/tests/must-fail/api-response-header.feature +21 -0
  182. package/tests/must-fail/api-without-base-url.feature +11 -0
  183. package/tests/must-fail/assertions.feature +96 -0
  184. package/tests/must-fail/breakpoints.feature +15 -0
  185. package/tests/must-fail/choice-controls.feature +25 -0
  186. package/tests/must-fail/clock.feature +11 -0
  187. package/tests/must-fail/datetime-field.feature +10 -0
  188. package/tests/must-fail/element-selector-hint.feature +17 -0
  189. package/tests/must-fail/field-state.feature +20 -0
  190. package/tests/must-fail/fill-field.feature +30 -0
  191. package/tests/must-fail/iframe-text.feature +17 -0
  192. package/tests/must-fail/modal-open.feature +26 -0
  193. package/tests/must-fail/multi-value-field.feature +18 -0
  194. package/tests/must-fail/registered-names.feature +25 -0
  195. package/tests/must-fail/select-list.feature +15 -0
  196. package/tests/must-fail/selector-files.feature +10 -0
  197. package/tests/must-fail/sorted-tables.feature +20 -0
  198. package/tests/must-fail/storage-before-a-page.feature +13 -0
  199. package/tests/must-fail/text-matching.feature +16 -0
  200. package/tests/must-fail/text-order.feature +15 -0
  201. package/tests/must-fail/viewport-top.feature +20 -0
  202. package/tests/must-fail/waits.feature +51 -0
  203. package/tests/must-fail/yaml-numbers.feature +48 -0
  204. package/tests/reports/README.md +2 -2
  205. package/tests/step-definitions/a11y.steps.js +36 -23
  206. package/tests/step-definitions/action.steps.js +22 -8
  207. package/tests/step-definitions/api.steps.js +349 -67
  208. package/tests/step-definitions/assertion.steps.js +327 -63
  209. package/tests/step-definitions/auth.steps.js +15 -18
  210. package/tests/step-definitions/clock.steps.js +22 -0
  211. package/tests/step-definitions/debug.steps.js +8 -0
  212. package/tests/step-definitions/dialog.steps.js +9 -2
  213. package/tests/step-definitions/element.steps.js +135 -18
  214. package/tests/step-definitions/field.steps.js +523 -80
  215. package/tests/step-definitions/file-download.steps.js +74 -10
  216. package/tests/step-definitions/form.steps.js +76 -29
  217. package/tests/step-definitions/iframe.steps.js +89 -29
  218. package/tests/step-definitions/input.steps.js +26 -7
  219. package/tests/step-definitions/javascript.steps.js +64 -22
  220. package/tests/step-definitions/modal.steps.js +79 -13
  221. package/tests/step-definitions/navigation.steps.js +14 -0
  222. package/tests/step-definitions/network.steps.js +15 -5
  223. package/tests/step-definitions/response.steps.js +6 -4
  224. package/tests/step-definitions/responsive.steps.js +26 -33
  225. package/tests/step-definitions/screenshot.steps.js +26 -9
  226. package/tests/step-definitions/scroll.steps.js +20 -0
  227. package/tests/step-definitions/selectors.steps.js +104 -51
  228. package/tests/step-definitions/storage.steps.js +41 -16
  229. package/tests/step-definitions/table.steps.js +81 -6
  230. package/tests/step-definitions/video.steps.js +52 -55
  231. package/tests/step-definitions/wait.steps.js +209 -54
  232. package/tests/step-definitions/web-first.steps.js +69 -35
  233. package/tests/step-definitions/webship.js +807 -128
  234. package/tests/step-definitions/xml.steps.js +124 -28
  235. package/tests/step-definitions/yaml.steps.js +90 -46
  236. package/.scratch/commit.txt +0 -14
  237. package/.scratch/docs.py +0 -42
  238. package/.scratch/echo-server.js +0 -8
  239. package/.scratch/echo.js +0 -35
  240. package/.scratch/echo.pid +0 -1
  241. package/.scratch/features/cookies.feature +0 -22
  242. package/.scratch/http.pid +0 -1
  243. package/.scratch/https.pid +0 -1
  244. package/.scratch/issue.md +0 -49
  245. package/.scratch/one.js +0 -2
  246. package/.scratch/one.json +0 -280
  247. package/.scratch/patch.py +0 -163
  248. package/.scratch/pr.md +0 -30
@@ -1,19 +1,22 @@
1
1
  'use strict';
2
2
 
3
- const { friendly } = require('./webship');
3
+ const { friendly, videoFileName } = require('./webship');
4
4
 
5
5
  // Video recording steps — start / stop / save mid-scenario.
6
6
  //
7
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.
8
+ // `start` / `stop` therefore open a new browser context with the new
9
+ // recording flag, through the World (openContext / replaceContext of
10
+ // webship.js): the cookies and local storage, the viewport of an @mobile /
11
+ // @desktop tag, the smart waits, JavaScript-error capture and a running
12
+ // request log go on with the new page. The page itself starts blank — call
13
+ // `start` BEFORE any navigation, and open the page again after `stop` when
14
+ // the scenario goes on.
12
15
  //
13
- // Default mode is 'off' (no recording). See cucumber.js → worldParameters.video.
16
+ // Default mode is 'off': no recording, except the scenarios tagged @video.
17
+ // See cucumber.js → worldParameters.video.
14
18
 
15
19
  const { When, Then } = require('@cucumber/cucumber');
16
- const fs = require('fs');
17
20
  const path = require('path');
18
21
 
19
22
  function settings(world) {
@@ -21,26 +24,17 @@ function settings(world) {
21
24
  return {
22
25
  dir: process.env.WEBSHIP_VIDEO_DIR || cfg.dir || './videos',
23
26
  size: cfg.size || { width: 1280, height: 720 },
27
+ filenamePattern: cfg.filenamePattern || '{datetime}.{feature_file}.{scenario}.{status}.{ext}',
24
28
  };
25
29
  }
26
30
 
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
31
  /**
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.
32
+ * Start recording the browser as a webm video. Opens a new browser context
33
+ * with `recordVideo` enabled; the cookies, the local storage, the viewport
34
+ * and the page setups go on, the page starts blank. Place BEFORE any
35
+ * navigation in the scenario. When the scenario already records (the mode
36
+ * is on or on-failure, the @video tag, an earlier start) the step changes
37
+ * nothing: the recording goes on.
44
38
  *
45
39
  * Example #1: When I start video recording
46
40
  * Example #2: And I start video recording
@@ -50,8 +44,12 @@ async function rebuildContext(world, recordVideo) {
50
44
  *
51
45
  */
52
46
  When(/^(I |we )*start video recording$/, async function (pronoun) {
47
+ if (this._videoRequested && this.page && this.page.video()) return;
53
48
  try {
54
- await rebuildContext(this, true);
49
+ if (!this._videoSettings) this._videoSettings = settings(this);
50
+ this._videoRequested = true;
51
+ this._videoStartedAt = new Date();
52
+ await this.replaceContext();
55
53
  } catch (e) {
56
54
  throw friendly({
57
55
  action: 'start video recording',
@@ -62,9 +60,14 @@ When(/^(I |we )*start video recording$/, async function (pronoun) {
62
60
  });
63
61
 
64
62
  /**
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.
63
+ * Stop recording. Closes the current browser context (which flushes the
64
+ * webm to disk), saves the video, and opens a new context that does not
65
+ * record, with the same cookies, local storage, viewport and page setups,
66
+ * so the rest of the scenario can continue (the page starts blank).
67
+ *
68
+ * The video is saved under the name reserved with "I save the current video
69
+ * as", else under worldParameters.video.filenamePattern with the status
70
+ * "manual" (the scenario has not ended yet).
68
71
  *
69
72
  * Example #1: When I stop video recording
70
73
  * Example #2: And I stop video recording
@@ -77,14 +80,15 @@ When(/^(I |we )*stop video recording$/, async function (pronoun) {
77
80
  try {
78
81
  if (!this.page || !this._videoRequested) return;
79
82
  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.
83
+ // Keep the session for the new context, close this one — it flushes the
84
+ // webm — then saveAs while the browser is still alive.
85
+ let state = null;
86
+ try { state = await this.context.storageState(); } catch { /* nothing to carry */ }
82
87
  try { await this.context.close(); } catch { /* ignore */ }
83
88
  if (video) {
84
89
  try {
85
- const s = settings(this);
86
- const name = this._videoSaveAsName || `manual.${Date.now()}.webm`;
87
- const dest = path.join(s.dir, name);
90
+ const s = this._videoSettings || settings(this);
91
+ const dest = path.join(s.dir, videoFileName(this, 'manual'));
88
92
  await video.saveAs(dest);
89
93
  await video.delete().catch(() => {});
90
94
  process.stderr.write(`\n[webship-js] video saved → ${dest}\n`);
@@ -94,19 +98,13 @@ When(/^(I |we )*stop video recording$/, async function (pronoun) {
94
98
  process.stderr.write(`\n[webship-js] video save failed: ${e.message}\n`);
95
99
  }
96
100
  }
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
101
  this._videoRequested = false;
104
- await this.openBrowser();
102
+ await this.openContext(state ? { storageState: state } : {});
105
103
  } catch (e) {
106
104
  throw friendly({
107
105
  action: 'stop video recording',
108
106
  cause: e,
109
- hint: 'the scenario will continue with a fresh, non-recording browser.',
107
+ hint: 'the scenario goes on in a new browser context that does not record.',
110
108
  });
111
109
  }
112
110
  });
@@ -116,7 +114,8 @@ When(/^(I |we )*stop video recording$/, async function (pronoun) {
116
114
  * save happens at scenario end (Playwright's `video.saveAs()` blocks
117
115
  * until recording finishes, so we cannot copy bytes mid-flight). If the
118
116
  * scenario calls `stop video recording` before scenario end, the manual
119
- * webm uses this name instead of the automatic timestamped one.
117
+ * webm uses this name instead of the automatic timestamped one. A reserved
118
+ * name is kept in the on-failure mode too, when the scenario passes.
120
119
  *
121
120
  * Example #1: When I save the current video as "checkout-flow.webm"
122
121
  * Example #2: When I save the current video as "regression-21.webm"
@@ -144,8 +143,10 @@ When(/^(I |we )*save the current video as "([^"]*)"$/, function (pronoun, name)
144
143
  });
145
144
 
146
145
  /**
147
- * Print the path that the current video will be written to. Diagnostic
148
- * only — never asserts, never fails.
146
+ * Print the path that the current video will be written to when the
147
+ * scenario ends (or the recording is stopped): the reserved name, else the
148
+ * filenamePattern with "<status>" where the scenario's result will go.
149
+ * Diagnostic only — never asserts, never fails.
149
150
  *
150
151
  * Example #1: Then print video path
151
152
  * Example #2: And print video path
@@ -157,21 +158,17 @@ When(/^(I |we )*save the current video as "([^"]*)"$/, function (pronoun, name)
157
158
  Then(/^print video path$/, async function () {
158
159
  // Diagnostic only — swallow every error and report inline.
159
160
  try {
160
- if (!this.page || !this._videoRequested) {
161
+ if (!this.page || !this._videoRequested || !this.page.video()) {
161
162
  console.log('\n--- Video path: recording is OFF ---');
162
163
  return;
163
164
  }
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
- }
165
+ const s = this._videoSettings || settings(this);
166
+ const dest = path.join(s.dir, videoFileName(this, null));
167
+ const kept = s.mode === 'on-failure' && !this._videoForcedByTag && !this._videoSaveAsName
168
+ ? ', kept only when the scenario fails'
169
+ : '';
170
+ const status = this._videoSaveAsName ? '' : ', <status> being the result of the scenario (passed, failed, …)';
171
+ console.log(`\n--- Video path: ${dest} (written when the scenario ends${status}${kept}) ---`);
175
172
  } catch (e) {
176
173
  console.log(`\n--- Video path error: ${e.message} ---`);
177
174
  }
@@ -11,11 +11,54 @@
11
11
  // so this file never duplicates BBR plumbing.
12
12
 
13
13
  const { When } = require('@cucumber/cucumber');
14
- const { smartSettle, waitForModalState } = require('./webship');
14
+ const { smartSettle, pollPage, waitForModalState, friendly, failure, excerpt, isTimeout, pageTextLocator } = require('./webship');
15
+
16
+ // A step whose length the scenario gives ("I wait 2 minutes", "within 60
17
+ // seconds") runs for that time, past the step timeout too (45 s,
18
+ // WEBSHIP_STEP_TIMEOUT): its definition takes OWN_LENGTH, which sets no
19
+ // cucumber time limit, and the step bounds itself with withinTimeLimit.
20
+ const OWN_LENGTH = { timeout: -1 };
21
+
22
+ // How long past its own length a step waits for a page that stopped answering.
23
+ const TIME_LIMIT_MARGIN_MS = 15000;
24
+
25
+ /**
26
+ * Run the work of a step whose length the scenario gives, bounded by that
27
+ * length plus a margin, so that a page that stopped answering ends the step
28
+ * with a plain failure instead of hanging the run.
29
+ *
30
+ * @param {number} ms - The length the scenario gave, in ms.
31
+ * @param {string} what - The step's work, for the failure ("The wait of 2 minutes").
32
+ * @param {Function} work - Returns the promise of the work.
33
+ * @returns {Promise<*>} What the work returns.
34
+ */
35
+ async function withinTimeLimit(ms, what, work) {
36
+ const limit = ms + TIME_LIMIT_MARGIN_MS;
37
+ let timer;
38
+ const overdue = new Promise((resolve, reject) => {
39
+ timer = setTimeout(() => reject(friendly(
40
+ `${what} did not end: the page did not answer within ${Math.ceil(limit / 1000)} seconds.\n` +
41
+ ' Hint: a script of the page may never return; open the page in a browser to see it.'
42
+ )), limit);
43
+ });
44
+ try {
45
+ return await Promise.race([Promise.resolve().then(work), overdue]);
46
+ } finally {
47
+ clearTimeout(timer);
48
+ }
49
+ }
50
+
51
+ // Settle the page for the length a wait step was given, past the step timeout too.
52
+ function settleFor(world, ms, what) {
53
+ return withinTimeLimit(ms, what, () => smartSettle(world.page, ms));
54
+ }
15
55
 
16
56
  /**
17
57
  * Wait UP TO N seconds for the page to settle. Returns early on idle.
18
58
  *
59
+ * Like every wait whose length the scenario gives, it runs for that length
60
+ * even past the step timeout (45 s, WEBSHIP_STEP_TIMEOUT).
61
+ *
19
62
  * "Settle" = DOM ready, no in-flight fetch/XHR, no pending setTimeout
20
63
  * callbacks, and no MutationObserver activity for at least 250 ms.
21
64
  *
@@ -29,8 +72,8 @@ const { smartSettle, waitForModalState } = require('./webship');
29
72
  * Then I should see "Saved"
30
73
  *
31
74
  */
32
- When(/^(I |we )*wait for (\d+) seconds?$/, async function (pronoun, seconds) {
33
- await smartSettle(this.page, parseInt(seconds, 10) * 1000);
75
+ When(/^(I |we )*wait for (\d+) seconds?$/, OWN_LENGTH, async function (pronoun, seconds) {
76
+ await settleFor(this, parseInt(seconds, 10) * 1000, `The wait for ${seconds} seconds`);
34
77
  });
35
78
 
36
79
  /**
@@ -48,12 +91,13 @@ When(/^(I |we )*wait for (\d+) seconds?$/, async function (pronoun, seconds) {
48
91
  * Then I should see "Results"
49
92
  *
50
93
  */
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);
94
+ When(/^(I |we )*wait for (\d+) seconds? for AJAX to finish$/, OWN_LENGTH, async function (pronoun, seconds) {
95
+ await settleFor(this, parseInt(seconds, 10) * 1000, `The wait for ${seconds} seconds for AJAX`);
53
96
  });
54
97
 
55
98
  /**
56
- * Wait UP TO a number of seconds for the page to settle.
99
+ * Wait UP TO a number of seconds for the page to settle. A number with no
100
+ * unit is read as seconds.
57
101
  *
58
102
  * Example #1: When I wait 1 second
59
103
  * Example #2: When I wait 5 seconds
@@ -63,14 +107,16 @@ When(/^(I |we )*wait for (\d+) seconds? for AJAX to finish$/, async function (pr
63
107
  * Example #6: When we wait 1 second
64
108
  * Example #7: When we wait 5 seconds
65
109
  * Example #8: When we wait 4s
110
+ * Example #9: When I wait 2
66
111
  *
67
112
  */
68
- When(/^(I |we )*wait (\d+)( second| seconds|s)?$/, async function (pronounCase, number, withSecondWord) {
69
- await smartSettle(this.page, parseInt(number, 10) * 1000);
113
+ When(/^(I |we )*wait (\d+)( second| seconds|s)?$/, OWN_LENGTH, async function (pronounCase, number, withSecondWord) {
114
+ await settleFor(this, parseInt(number, 10) * 1000, `The wait of ${number} seconds`);
70
115
  });
71
116
 
72
117
  /**
73
- * Wait UP TO a maximum number of seconds for the page to settle.
118
+ * Wait UP TO a maximum number of seconds for the page to settle. A number with
119
+ * no unit is read as seconds.
74
120
  *
75
121
  * Example #1: When I wait max of 1 second
76
122
  * Example #2: When I wait max of 5 seconds
@@ -80,14 +126,16 @@ When(/^(I |we )*wait (\d+)( second| seconds|s)?$/, async function (pronounCase,
80
126
  * Example #6: When we wait max of 1 second
81
127
  * Example #7: When we wait max of 5 seconds
82
128
  * Example #8: When we wait max of 4s
129
+ * Example #9: When I wait max of 2
83
130
  *
84
131
  */
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);
132
+ When(/^(I |we )*wait max of (\d+)( second| seconds|s)?$/, OWN_LENGTH, async function (pronounCase, number, withSecondWord) {
133
+ await settleFor(this, parseInt(number, 10) * 1000, `The wait of at most ${number} seconds`);
87
134
  });
88
135
 
89
136
  /**
90
- * Wait UP TO a number of minutes for the page to settle.
137
+ * Wait UP TO a number of minutes for the page to settle. The unit is required:
138
+ * a number with no unit is read as seconds.
91
139
  *
92
140
  * Example #1: When I wait 1 minute
93
141
  * Example #2: When I wait 10 minutes
@@ -96,12 +144,13 @@ When(/^(I |we )*wait max of (\d+)( second| seconds|s)?$/, async function (pronou
96
144
  * Example #5: And wait 2 minutes
97
145
  *
98
146
  */
99
- When(/^(I |we )*wait (\d+)( minute| minutes|m)?$/, async function (pronounCase, number, withMinuteWord) {
100
- await smartSettle(this.page, parseInt(number, 10) * 1000 * 60);
147
+ When(/^(I |we )*wait (\d+)( minute| minutes|m)$/, OWN_LENGTH, async function (pronounCase, number, withMinuteWord) {
148
+ await settleFor(this, parseInt(number, 10) * 1000 * 60, `The wait of ${number} minutes`);
101
149
  });
102
150
 
103
151
  /**
104
- * Wait UP TO a maximum number of minutes for the page to settle.
152
+ * Wait UP TO a maximum number of minutes for the page to settle. The unit is
153
+ * required: a number with no unit is read as seconds.
105
154
  *
106
155
  * Example #1: When I wait max of 1 minute
107
156
  * Example #2: When I wait max of 10 minutes
@@ -110,8 +159,8 @@ When(/^(I |we )*wait (\d+)( minute| minutes|m)?$/, async function (pronounCase,
110
159
  * Example #5: And wait max of 2 minutes
111
160
  *
112
161
  */
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);
162
+ When(/^(I |we )*wait max of (\d+)( minute| minutes|m)$/, OWN_LENGTH, async function (pronounCase, number, withMinuteWord) {
163
+ await settleFor(this, parseInt(number, 10) * 1000 * 60, `The wait of at most ${number} minutes`);
115
164
  });
116
165
 
117
166
  /**
@@ -120,6 +169,8 @@ When(/^(I |we )*wait max of (\d+)( minute| minutes|m)?$/, async function (pronou
120
169
  * Example #1: When I wait until the page is loaded
121
170
  * Example #2: When we wait until the page is loaded
122
171
  * Example #3: When wait until page loaded
172
+ * Example #4: And I wait until the page is loaded
173
+ * Example #5: When we wait until page is loaded
123
174
  *
124
175
  */
125
176
  When(/^(I |we )*wait until( the)* page( is)* loaded*$/, async function (pronounCase, theCase, withIs) {
@@ -127,15 +178,17 @@ When(/^(I |we )*wait until( the)* page( is)* loaded*$/, async function (pronounC
127
178
  });
128
179
 
129
180
  /**
130
- * Wait for active XHR/fetch requests to complete.
181
+ * Wait for active XHR/fetch requests to complete. "AJAX" may be written in
182
+ * any letter case.
131
183
  *
132
184
  * Example #1: When I wait for AJAX to finish
133
185
  * Example #2: And I wait for AJAX to finish
134
186
  * Example #3: When we wait for AJAX to finish
135
187
  * Example #4: And wait for AJAX to finish
188
+ * Example #5: When I wait for ajax to finish
136
189
  *
137
190
  */
138
- When(/^(I |we )*wait for AJAX to finish$/, async function (pronounCase) {
191
+ When(/^(I |we )*wait for (?:AJAX|ajax|Ajax) to finish$/, async function (pronounCase) {
139
192
  await smartSettle(this.page, 10000);
140
193
  });
141
194
 
@@ -146,6 +199,7 @@ When(/^(I |we )*wait for AJAX to finish$/, async function (pronounCase) {
146
199
  * Example #2: When I wait for the modal to disappear
147
200
  * Example #3: When we wait for modal to appear
148
201
  * Example #4: And I wait for the modal dialog to disappear
202
+ * Example #5: When we wait for the modal dialog to appear
149
203
  *
150
204
  */
151
205
  When(/^(I |we )*wait for( the)* modal( dialog)* to (appear|disappear)$/, async function (pronounCase, theCase, dialogCase, appearOrDisappear) {
@@ -167,7 +221,17 @@ When(/^(I |we )*wait for( the)* modal( dialog)* to (appear|disappear)$/, async f
167
221
  *
168
222
  */
169
223
  When(/^(I |we )*wait for "([^"]*)" to appear$/, async function (pronounCase, selector) {
170
- await this.page.waitForSelector(selector, { state: 'visible', timeout: 10000 });
224
+ try {
225
+ await this.page.waitForSelector(selector, { state: 'visible', timeout: 10000 });
226
+ } catch (e) {
227
+ if (!isTimeout(e)) throw e;
228
+ const present = await this.page.locator(selector).count().catch(() => 0);
229
+ throw failure(this.page, present
230
+ ? `The element "${selector}" is on the page but did not become visible within 10 seconds.`
231
+ : `The element "${selector}" did not appear within 10 seconds.`, {
232
+ hint: `"${selector}" is a CSS selector. For a text, use: I wait for the text "..." to appear`,
233
+ });
234
+ }
171
235
  });
172
236
 
173
237
  /**
@@ -184,7 +248,14 @@ When(/^(I |we )*wait for "([^"]*)" to appear$/, async function (pronounCase, sel
184
248
  *
185
249
  */
186
250
  When(/^(I |we )*wait for "([^"]*)" to disappear$/, async function (pronounCase, selector) {
187
- await this.page.waitForSelector(selector, { state: 'hidden', timeout: 10000 });
251
+ try {
252
+ await this.page.waitForSelector(selector, { state: 'hidden', timeout: 10000 });
253
+ } catch (e) {
254
+ if (!isTimeout(e)) throw e;
255
+ throw failure(this.page, `The element "${selector}" is still visible after 10 seconds.`, {
256
+ hint: `"${selector}" is a CSS selector; the step passes when the first element it matches is hidden or gone.`,
257
+ });
258
+ }
188
259
  });
189
260
 
190
261
  /**
@@ -202,10 +273,17 @@ When(/^(I |we )*wait for "([^"]*)" to disappear$/, async function (pronounCase,
202
273
  *
203
274
  */
204
275
  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
- );
276
+ try {
277
+ await this.page.waitForFunction(
278
+ (t) => document.body && document.body.innerText.includes(t),
279
+ text, { timeout: 10000, polling: 100 }
280
+ );
281
+ } catch (e) {
282
+ if (!isTimeout(e)) throw e;
283
+ throw failure(this.page, `The text "${text}" did not appear within 10 seconds.`, {
284
+ hint: 'check the spelling and the letter case; the step reads the visible text of the page.',
285
+ });
286
+ }
209
287
  });
210
288
 
211
289
  /**
@@ -221,10 +299,17 @@ When(/^(I |we )*wait for( the)* text "([^"]*)" to appear$/, async function (pron
221
299
  *
222
300
  */
223
301
  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
- );
302
+ try {
303
+ await this.page.waitForFunction(
304
+ (t) => !document.body || !document.body.innerText.includes(t),
305
+ text, { timeout: 10000, polling: 100 }
306
+ );
307
+ } catch (e) {
308
+ if (!isTimeout(e)) throw e;
309
+ throw failure(this.page, `The text "${text}" is still on the page after 10 seconds.`, {
310
+ hint: 'the step reads the visible text of the page.',
311
+ });
312
+ }
228
313
  });
229
314
 
230
315
  /**
@@ -241,10 +326,17 @@ When(/^(I |we )*wait for( the)* text "([^"]*)" to disappear$/, async function (p
241
326
  *
242
327
  */
243
328
  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
- );
329
+ try {
330
+ await this.page.waitForFunction(
331
+ (frag) => window.location.href.includes(frag),
332
+ fragment, { timeout: 10000, polling: 100 }
333
+ );
334
+ } catch (e) {
335
+ if (!isTimeout(e)) throw e;
336
+ throw failure(this.page, `The URL does not contain "${fragment}" after 10 seconds.`, {
337
+ hint: 'the step looks for the text in the whole address, with the domain, the query and the hash.',
338
+ });
339
+ }
248
340
  });
249
341
 
250
342
  /**
@@ -259,10 +351,21 @@ When(/^(I |we )*wait until( the)* URL contains "([^"]*)"$/, async function (pron
259
351
  *
260
352
  */
261
353
  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
- );
354
+ try {
355
+ await this.page.waitForFunction(
356
+ ({ op, value }) => op === 'is' ? document.title === value : document.title.includes(value),
357
+ { op, value }, { timeout: 10000, polling: 100 }
358
+ );
359
+ } catch (e) {
360
+ if (!isTimeout(e)) throw e;
361
+ const title = await this.page.title().catch(() => '');
362
+ throw failure(this.page, op === 'is'
363
+ ? `The page title is not "${value}" after 10 seconds.`
364
+ : `The page title does not contain "${value}" after 10 seconds.`, {
365
+ found: `"${excerpt(title)}"`,
366
+ hint: 'the page title is the text of the browser tab, not the main heading of the page.',
367
+ });
368
+ }
266
369
  });
267
370
 
268
371
  /**
@@ -281,10 +384,19 @@ When(/^(I |we )*wait until( the)* page title (is|contains) "([^"]*)"$/, async fu
281
384
  */
282
385
  When(/^(I |we )*wait until (\d+) elements? match(?:es)? "([^"]*)"$/, async function (pronounCase, count, selector) {
283
386
  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
- );
387
+ try {
388
+ await this.page.waitForFunction(
389
+ ({ sel, n }) => document.querySelectorAll(sel).length === n,
390
+ { sel: selector, n: expected }, { timeout: 10000, polling: 100 }
391
+ );
392
+ } catch (e) {
393
+ if (!isTimeout(e)) throw e;
394
+ const actual = await this.page.locator(selector).count().catch(() => 0);
395
+ throw failure(this.page, `Expected ${expected} element(s) matching "${selector}" within 10 seconds.`, {
396
+ found: `${actual} element(s)`,
397
+ hint: `"${selector}" is a CSS selector; hidden elements count too. For a minimum, use: I wait until at least ${expected} elements match "${selector}"`,
398
+ });
399
+ }
288
400
  });
289
401
 
290
402
  /**
@@ -303,10 +415,19 @@ When(/^(I |we )*wait until (\d+) elements? match(?:es)? "([^"]*)"$/, async funct
303
415
  */
304
416
  When(/^(I |we )*wait until at least (\d+) elements? match(?:es)? "([^"]*)"$/, async function (pronounCase, count, selector) {
305
417
  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
- );
418
+ try {
419
+ await this.page.waitForFunction(
420
+ ({ sel, n }) => document.querySelectorAll(sel).length >= n,
421
+ { sel: selector, n: expected }, { timeout: 10000, polling: 100 }
422
+ );
423
+ } catch (e) {
424
+ if (!isTimeout(e)) throw e;
425
+ const actual = await this.page.locator(selector).count().catch(() => 0);
426
+ throw failure(this.page, `Expected at least ${expected} element(s) matching "${selector}" within 10 seconds.`, {
427
+ found: `${actual} element(s)`,
428
+ hint: `"${selector}" is a CSS selector; hidden elements count too.`,
429
+ });
430
+ }
310
431
  });
311
432
 
312
433
  /**
@@ -357,6 +478,10 @@ When(/^(I |we )*wait until( the)* page is interactive$/, async function (pronoun
357
478
  * request. Reads `window.__webshipPendingTimers`, the counter installed by
358
479
  * webship.js's init script.
359
480
  *
481
+ * Under a fake clock (`Given the system time is "…"`, or a clock step that
482
+ * installed one) the page's timers belong to the clock and run only when it
483
+ * moves, so the step fails at once and says so: advance the clock instead.
484
+ *
360
485
  * Example #1: When I wait until pending timers settle
361
486
  * Example #2: When I press "Close"
362
487
  * And I wait until pending timers settle
@@ -369,17 +494,41 @@ When(/^(I |we )*wait until( the)* page is interactive$/, async function (pronoun
369
494
  *
370
495
  */
371
496
  When(/^(I |we )*wait until pending timers settle$/, async function (pronounCase) {
372
- await this.page.waitForFunction(
497
+ const fakeClock = await this.page.evaluate(() => !!(window.Date && window.Date.isFake)).catch(() => false);
498
+ if (fakeClock) {
499
+ throw failure(this.page, 'A fake clock is installed, so the timers of the page run only when the clock moves.', {
500
+ hint: 'advance the clock past the timers instead, for example: When I advance the clock by 5 seconds',
501
+ });
502
+ }
503
+ // Polled from Node: a poll on the page's own setTimeout would be counted as
504
+ // one more pending timer, and the wait could never see the count reach zero.
505
+ const settled = await pollPage(
506
+ this.page,
373
507
  () => {
374
508
  const t = window.__webshipPendingTimers;
375
509
  return typeof t !== 'number' || t <= 0;
376
510
  },
377
- null, { timeout: 10000, polling: 100 }
511
+ null, 10000, 100
378
512
  );
513
+ if (!settled) {
514
+ throw friendly({
515
+ action: 'wait until pending timers settle',
516
+ cause: 'the page still had a pending timer after 10 seconds',
517
+ hint: 'a page that reschedules a timer forever never settles; wait for the element or the text you expect instead.',
518
+ });
519
+ }
379
520
  });
380
521
 
381
522
  /**
382
- * Pollable text assertion — retries the inner step until passing or timeout.
523
+ * Text assertion that waits longer: `I should see` with a budget of its own,
524
+ * 10 seconds unless the step says "within N seconds".
525
+ *
526
+ * It reads the page exactly as `I should see` and `I should not see` do: the
527
+ * text of the page as Playwright's text matching reads it, letter case
528
+ * ignored, runs of white space collapsed, the text of hidden elements
529
+ * included, the text of `<script>` and `<style>` left out. For the text a
530
+ * visitor can see, with its letter case, use `I wait for the text "..." to
531
+ * appear`.
383
532
  *
384
533
  * Use sparingly; prefer explicit edge waits (`wait for "X" to appear`).
385
534
  *
@@ -391,10 +540,16 @@ When(/^(I |we )*wait until pending timers settle$/, async function (pronounCase)
391
540
  * Then eventually I should see "Submitted" within 8 seconds
392
541
  *
393
542
  */
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
- );
543
+ When(/^eventually (I |we )*should see "([^"]*)"(?: within (\d+) seconds?)?$/, OWN_LENGTH, async function (pronoun, text, seconds) {
544
+ const total = (seconds ? Math.max(1, parseInt(seconds, 10)) : 10) * 1000;
545
+ try {
546
+ await withinTimeLimit(total, `The wait for the text "${text}"`, () => pageTextLocator(this.page, text).waitFor({ state: 'attached', timeout: total }));
547
+ } catch (e) {
548
+ if (!isTimeout(e)) throw e;
549
+ throw failure(this.page, `The text "${text}" did not appear within ${total / 1000} seconds.`, {
550
+ hint: 'check the spelling; like "I should see", the step ignores letter case and reads all the text of the page, the text of hidden elements included. For a longer wait, add "within N seconds" to the step.',
551
+ });
552
+ }
400
553
  });
554
+
555
+ module.exports = { OWN_LENGTH, withinTimeLimit };