webship-js 2.0.11 → 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 (168) hide show
  1. package/.circleci/config.yml +10 -1
  2. package/.drone.yml +7 -7
  3. package/.github/workflows/github-actions.yml +45 -0
  4. package/.gitlab-ci.yml +9 -4
  5. package/.harness/webship-js-pipeline.yml +5 -6
  6. package/.semaphore/semaphore.yml +6 -9
  7. package/.teamcity/settings.kts +7 -6
  8. package/.travis.yml +6 -1
  9. package/AGENTS.md +1 -1
  10. package/CLAUDE.md +65 -23
  11. package/Jenkinsfile +5 -3
  12. package/azure-pipelines.yml +17 -8
  13. package/bamboo-specs/bamboo.yml +9 -15
  14. package/bin/init-webship.js +44 -8
  15. package/bitbucket-pipelines.yml +5 -1
  16. package/buildspec.yml +6 -7
  17. package/cloudbuild.yaml +28 -12
  18. package/codefresh.yml +6 -6
  19. package/cucumber.js +17 -10
  20. package/docs/00-quick-start.md +8 -0
  21. package/docs/02-bbr-smart-waits.md +15 -10
  22. package/docs/03-selector-registry.md +24 -0
  23. package/docs/04-step-reference.md +51 -25
  24. package/docs/05-web-first-assertions.md +6 -0
  25. package/docs/07-auth-state.md +1 -1
  26. package/docs/08-clock-mocking.md +21 -2
  27. package/docs/09-api-testing.md +40 -2
  28. package/docs/10-accessibility.md +2 -0
  29. package/docs/11-debugging.md +3 -1
  30. package/docs/12-ai-agent-guide.md +5 -0
  31. package/docs/13-faq.md +72 -1
  32. package/docs/14-recipes-cookbook.md +2 -0
  33. package/docs/15-tag-conventions.md +2 -1
  34. package/docs/16-ci-cd.md +140 -119
  35. package/docs/README.md +5 -5
  36. package/docs/advanced-screenshots.md +3 -1
  37. package/docs/api-step-definitions.md +16 -2
  38. package/docs/global-settings.md +69 -17
  39. package/docs/install-webship-js.md +2 -0
  40. package/docs/step-definitions/then-i-should-see.md +14 -1
  41. package/docs/step-definitions/then-item-checkbox.md +2 -0
  42. package/docs/step-definitions/when-i-fill.md +4 -0
  43. package/docs/step-definitions/when-i-select-option-select-list.md +2 -0
  44. package/examples/choice-controls.html +29 -0
  45. package/examples/datetime-fields.html +52 -0
  46. package/examples/element-selector-hint.html +16 -0
  47. package/examples/field-states.html +27 -0
  48. package/examples/fill-in-empty.html +26 -0
  49. package/examples/fill-unreachable.html +27 -0
  50. package/examples/iframe-inner.html +20 -0
  51. package/examples/iframe-nested.html +16 -0
  52. package/examples/iframe-outer.html +15 -0
  53. package/examples/multi-value-fields.html +54 -0
  54. package/examples/registered-names.html +15 -0
  55. package/examples/select-by-label.html +33 -0
  56. package/examples/settle-budget.html +21 -0
  57. package/examples/sorted-tables.html +38 -0
  58. package/examples/text-matching.html +48 -0
  59. package/examples/text-order.html +25 -0
  60. package/examples/touch.html +22 -0
  61. package/examples/viewport-top.html +36 -0
  62. package/package.json +16 -1
  63. package/playwright.config.ts +3 -1
  64. package/tests/check-api-launch-url.js +106 -0
  65. package/tests/check-assets.js +103 -0
  66. package/tests/check-attachments.js +105 -0
  67. package/tests/check-breakpoints.js +117 -0
  68. package/tests/check-clock.js +143 -0
  69. package/tests/check-config.js +90 -0
  70. package/tests/check-context.js +215 -0
  71. package/tests/check-dry-run.js +104 -0
  72. package/tests/check-examples.js +10 -4
  73. package/tests/check-exit-report.js +141 -0
  74. package/tests/check-javascript-errors.js +105 -0
  75. package/tests/check-must-fail.js +5 -4
  76. package/tests/check-scaffold.js +36 -1
  77. package/tests/check-screenshots.js +117 -0
  78. package/tests/check-settle-verbs.js +137 -0
  79. package/tests/check-time-limit.js +104 -0
  80. package/tests/check-video.js +156 -0
  81. package/tests/check-world.js +167 -0
  82. package/tests/features/api-base-url.feature +25 -0
  83. package/tests/features/api-form-data.feature +18 -0
  84. package/tests/features/api-json-paths.feature +24 -0
  85. package/tests/features/api-response-contains.feature +21 -0
  86. package/tests/features/api-response-header-presence.feature +17 -0
  87. package/tests/features/api-response-header.feature +17 -0
  88. package/tests/features/api-saved-placeholders.feature +37 -0
  89. package/tests/features/api-step-definitions-individual.feature +1 -1
  90. package/tests/features/api-tables.feature +40 -0
  91. package/tests/features/breakpoints.feature +25 -0
  92. package/tests/features/choice-controls.feature +35 -0
  93. package/tests/features/complete-api-testing-examples.feature +1 -1
  94. package/tests/features/datetime-field-lookup.feature +29 -0
  95. package/tests/features/element-selector-hint.feature +14 -0
  96. package/tests/features/field-state.feature +21 -0
  97. package/tests/features/fill-in-empty-value.feature +41 -0
  98. package/tests/features/fill-reachable.feature +13 -0
  99. package/tests/features/iframe-nested.feature +43 -0
  100. package/tests/features/javascript-tolerated-errors.feature +20 -0
  101. package/tests/features/modal-open.feature +13 -0
  102. package/tests/features/multi-value-field-lookup.feature +30 -0
  103. package/tests/features/registered-names.feature +14 -0
  104. package/tests/features/select-by-label.feature +31 -0
  105. package/tests/features/selector-files.feature +14 -0
  106. package/tests/features/selectors-table-header.feature +35 -0
  107. package/tests/features/settle-budget.feature +11 -0
  108. package/tests/features/sorted-tables.feature +19 -0
  109. package/tests/features/storage-quoted-values.feature +26 -0
  110. package/tests/features/text-matching.feature +38 -0
  111. package/tests/features/text-order.feature +14 -0
  112. package/tests/features/touch.feature +21 -0
  113. package/tests/features/viewport-top.feature +13 -0
  114. package/tests/features/xml-namespaces.feature +34 -0
  115. package/tests/must-fail/api-json-paths.feature +21 -0
  116. package/tests/must-fail/api-response-contains.feature +23 -0
  117. package/tests/must-fail/api-response-header-presence.feature +17 -0
  118. package/tests/must-fail/api-response-header.feature +21 -0
  119. package/tests/must-fail/api-without-base-url.feature +11 -0
  120. package/tests/must-fail/breakpoints.feature +15 -0
  121. package/tests/must-fail/choice-controls.feature +25 -0
  122. package/tests/must-fail/clock.feature +11 -0
  123. package/tests/must-fail/datetime-field.feature +10 -0
  124. package/tests/must-fail/element-selector-hint.feature +17 -0
  125. package/tests/must-fail/field-state.feature +20 -0
  126. package/tests/must-fail/fill-field.feature +30 -0
  127. package/tests/must-fail/iframe-text.feature +17 -0
  128. package/tests/must-fail/modal-open.feature +26 -0
  129. package/tests/must-fail/multi-value-field.feature +18 -0
  130. package/tests/must-fail/registered-names.feature +25 -0
  131. package/tests/must-fail/select-list.feature +15 -0
  132. package/tests/must-fail/selector-files.feature +10 -0
  133. package/tests/must-fail/sorted-tables.feature +20 -0
  134. package/tests/must-fail/storage-before-a-page.feature +13 -0
  135. package/tests/must-fail/text-matching.feature +16 -0
  136. package/tests/must-fail/text-order.feature +15 -0
  137. package/tests/must-fail/viewport-top.feature +20 -0
  138. package/tests/must-fail/yaml-numbers.feature +48 -0
  139. package/tests/step-definitions/a11y.steps.js +24 -15
  140. package/tests/step-definitions/action.steps.js +22 -8
  141. package/tests/step-definitions/api.steps.js +349 -67
  142. package/tests/step-definitions/assertion.steps.js +100 -10
  143. package/tests/step-definitions/auth.steps.js +15 -18
  144. package/tests/step-definitions/clock.steps.js +22 -0
  145. package/tests/step-definitions/debug.steps.js +8 -0
  146. package/tests/step-definitions/dialog.steps.js +7 -0
  147. package/tests/step-definitions/element.steps.js +132 -17
  148. package/tests/step-definitions/field.steps.js +409 -96
  149. package/tests/step-definitions/form.steps.js +76 -29
  150. package/tests/step-definitions/iframe.steps.js +89 -29
  151. package/tests/step-definitions/input.steps.js +26 -7
  152. package/tests/step-definitions/javascript.steps.js +64 -22
  153. package/tests/step-definitions/modal.steps.js +79 -13
  154. package/tests/step-definitions/navigation.steps.js +14 -0
  155. package/tests/step-definitions/network.steps.js +15 -5
  156. package/tests/step-definitions/response.steps.js +6 -4
  157. package/tests/step-definitions/responsive.steps.js +26 -33
  158. package/tests/step-definitions/screenshot.steps.js +25 -8
  159. package/tests/step-definitions/scroll.steps.js +20 -0
  160. package/tests/step-definitions/selectors.steps.js +95 -48
  161. package/tests/step-definitions/storage.steps.js +38 -13
  162. package/tests/step-definitions/table.steps.js +81 -6
  163. package/tests/step-definitions/video.steps.js +52 -55
  164. package/tests/step-definitions/wait.steps.js +88 -23
  165. package/tests/step-definitions/web-first.steps.js +69 -35
  166. package/tests/step-definitions/webship.js +681 -143
  167. package/tests/step-definitions/xml.steps.js +49 -15
  168. package/tests/step-definitions/yaml.steps.js +45 -20
@@ -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, pollPage, waitForModalState, friendly, failure, excerpt, isTimeout } = 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, pollPage, waitForModalState, friendly, failure, excerpt, is
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,8 +91,8 @@ 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
  /**
@@ -67,8 +110,8 @@ When(/^(I |we )*wait for (\d+) seconds? for AJAX to finish$/, async function (pr
67
110
  * Example #9: When I wait 2
68
111
  *
69
112
  */
70
- When(/^(I |we )*wait (\d+)( second| seconds|s)?$/, async function (pronounCase, number, withSecondWord) {
71
- 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`);
72
115
  });
73
116
 
74
117
  /**
@@ -86,8 +129,8 @@ When(/^(I |we )*wait (\d+)( second| seconds|s)?$/, async function (pronounCase,
86
129
  * Example #9: When I wait max of 2
87
130
  *
88
131
  */
89
- When(/^(I |we )*wait max of (\d+)( second| seconds|s)?$/, async function (pronounCase, number, withSecondWord) {
90
- 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`);
91
134
  });
92
135
 
93
136
  /**
@@ -101,8 +144,8 @@ When(/^(I |we )*wait max of (\d+)( second| seconds|s)?$/, async function (pronou
101
144
  * Example #5: And wait 2 minutes
102
145
  *
103
146
  */
104
- When(/^(I |we )*wait (\d+)( minute| minutes|m)$/, async function (pronounCase, number, withMinuteWord) {
105
- 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`);
106
149
  });
107
150
 
108
151
  /**
@@ -116,8 +159,8 @@ When(/^(I |we )*wait (\d+)( minute| minutes|m)$/, async function (pronounCase, n
116
159
  * Example #5: And wait max of 2 minutes
117
160
  *
118
161
  */
119
- When(/^(I |we )*wait max of (\d+)( minute| minutes|m)$/, async function (pronounCase, number, withMinuteWord) {
120
- 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`);
121
164
  });
122
165
 
123
166
  /**
@@ -126,6 +169,8 @@ When(/^(I |we )*wait max of (\d+)( minute| minutes|m)$/, async function (pronoun
126
169
  * Example #1: When I wait until the page is loaded
127
170
  * Example #2: When we wait until the page is loaded
128
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
129
174
  *
130
175
  */
131
176
  When(/^(I |we )*wait until( the)* page( is)* loaded*$/, async function (pronounCase, theCase, withIs) {
@@ -133,15 +178,17 @@ When(/^(I |we )*wait until( the)* page( is)* loaded*$/, async function (pronounC
133
178
  });
134
179
 
135
180
  /**
136
- * 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.
137
183
  *
138
184
  * Example #1: When I wait for AJAX to finish
139
185
  * Example #2: And I wait for AJAX to finish
140
186
  * Example #3: When we wait for AJAX to finish
141
187
  * Example #4: And wait for AJAX to finish
188
+ * Example #5: When I wait for ajax to finish
142
189
  *
143
190
  */
144
- 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) {
145
192
  await smartSettle(this.page, 10000);
146
193
  });
147
194
 
@@ -152,6 +199,7 @@ When(/^(I |we )*wait for AJAX to finish$/, async function (pronounCase) {
152
199
  * Example #2: When I wait for the modal to disappear
153
200
  * Example #3: When we wait for modal to appear
154
201
  * Example #4: And I wait for the modal dialog to disappear
202
+ * Example #5: When we wait for the modal dialog to appear
155
203
  *
156
204
  */
157
205
  When(/^(I |we )*wait for( the)* modal( dialog)* to (appear|disappear)$/, async function (pronounCase, theCase, dialogCase, appearOrDisappear) {
@@ -430,6 +478,10 @@ When(/^(I |we )*wait until( the)* page is interactive$/, async function (pronoun
430
478
  * request. Reads `window.__webshipPendingTimers`, the counter installed by
431
479
  * webship.js's init script.
432
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
+ *
433
485
  * Example #1: When I wait until pending timers settle
434
486
  * Example #2: When I press "Close"
435
487
  * And I wait until pending timers settle
@@ -442,6 +494,12 @@ When(/^(I |we )*wait until( the)* page is interactive$/, async function (pronoun
442
494
  *
443
495
  */
444
496
  When(/^(I |we )*wait until pending timers settle$/, async function (pronounCase) {
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
+ }
445
503
  // Polled from Node: a poll on the page's own setTimeout would be counted as
446
504
  // one more pending timer, and the wait could never see the count reach zero.
447
505
  const settled = await pollPage(
@@ -462,7 +520,15 @@ When(/^(I |we )*wait until pending timers settle$/, async function (pronounCase)
462
520
  });
463
521
 
464
522
  /**
465
- * 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`.
466
532
  *
467
533
  * Use sparingly; prefer explicit edge waits (`wait for "X" to appear`).
468
534
  *
@@ -474,17 +540,16 @@ When(/^(I |we )*wait until pending timers settle$/, async function (pronounCase)
474
540
  * Then eventually I should see "Submitted" within 8 seconds
475
541
  *
476
542
  */
477
- When(/^eventually (I |we )*should see "([^"]*)"(?: within (\d+) seconds?)?$/, async function (pronoun, text, seconds) {
478
- const total = (seconds ? parseInt(seconds, 10) : 10) * 1000;
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;
479
545
  try {
480
- await this.page.waitForFunction(
481
- (t) => document.body && document.body.innerText.includes(t),
482
- text, { timeout: total, polling: 100 }
483
- );
546
+ await withinTimeLimit(total, `The wait for the text "${text}"`, () => pageTextLocator(this.page, text).waitFor({ state: 'attached', timeout: total }));
484
547
  } catch (e) {
485
548
  if (!isTimeout(e)) throw e;
486
549
  throw failure(this.page, `The text "${text}" did not appear within ${total / 1000} seconds.`, {
487
- hint: 'check the spelling and the letter case; the step reads the visible text of the page. For a longer wait, add "within N seconds" to the step.',
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.',
488
551
  });
489
552
  }
490
553
  });
554
+
555
+ module.exports = { OWN_LENGTH, withinTimeLimit };