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
@@ -8,6 +8,22 @@ const { Given, When } = require('@cucumber/cucumber');
8
8
 
9
9
  const ISO_HINT = 'install the fake clock first via "Given the system time is \\"YYYY-MM-DDTHH:MM:SSZ\\"".';
10
10
 
11
+ /**
12
+ * Playwright installs a fake clock on the first clock call when none is
13
+ * installed, at the current time; the timers the page set before that call
14
+ * keep running on real time. Say so once per scenario when a step moves a
15
+ * clock that "Given the system time is" did not install.
16
+ */
17
+ async function noteClockInstalledNow(world, what) {
18
+ let installed = true;
19
+ try { installed = await world.page.evaluate(() => !!(window.Date && window.Date.isFake)); } catch { /* no page yet */ }
20
+ if (installed || world.__clockNoteShown) return;
21
+ world.__clockNoteShown = true;
22
+ const note = `[webship-js] The clock was not installed with "Given the system time is …": "${what}" installed a fake clock now, at the current time. Timers the page set before this step run on real time and do not move with it.`;
23
+ process.stderr.write(`\n${note}\n`);
24
+ try { await world.attach(note, 'text/plain'); } catch { /* attach is optional */ }
25
+ }
26
+
11
27
  /**
12
28
  * Install a fake clock anchored at an ISO 8601 instant.
13
29
  *
@@ -41,6 +57,7 @@ Given(/^the system time is "([^"]*)"$/, async function (iso) {
41
57
  *
42
58
  */
43
59
  When(/^(I |we )*advance the clock by (\d+) ?ms$/, async function (pronoun, ms) {
60
+ await noteClockInstalledNow(this, `advance the clock by ${ms} ms`);
44
61
  try { await this.page.clock.runFor(parseInt(ms, 10)); }
45
62
  catch (e) { throw friendly({ action: `advance the clock by ${ms} ms`, cause: e, hint: ISO_HINT }); }
46
63
  });
@@ -56,6 +73,7 @@ When(/^(I |we )*advance the clock by (\d+) ?ms$/, async function (pronoun, ms) {
56
73
  *
57
74
  */
58
75
  When(/^(I |we )*advance the clock by (\d+) seconds?$/, async function (pronoun, seconds) {
76
+ await noteClockInstalledNow(this, `advance the clock by ${seconds} second(s)`);
59
77
  try { await this.page.clock.runFor(parseInt(seconds, 10) * 1000); }
60
78
  catch (e) { throw friendly({ action: `advance the clock by ${seconds} second(s)`, cause: e, hint: ISO_HINT }); }
61
79
  });
@@ -71,6 +89,7 @@ When(/^(I |we )*advance the clock by (\d+) seconds?$/, async function (pronoun,
71
89
  *
72
90
  */
73
91
  When(/^(I |we )*advance the clock by (\d+) minutes?$/, async function (pronoun, minutes) {
92
+ await noteClockInstalledNow(this, `advance the clock by ${minutes} minute(s)`);
74
93
  try { await this.page.clock.runFor(parseInt(minutes, 10) * 60 * 1000); }
75
94
  catch (e) { throw friendly({ action: `advance the clock by ${minutes} minute(s)`, cause: e, hint: ISO_HINT }); }
76
95
  });
@@ -86,6 +105,7 @@ When(/^(I |we )*advance the clock by (\d+) minutes?$/, async function (pronoun,
86
105
  *
87
106
  */
88
107
  When(/^(I |we )*pause the clock$/, async function (pronoun) {
108
+ await noteClockInstalledNow(this, 'pause the clock');
89
109
  try { await this.page.clock.pauseAt(await this.page.evaluate(() => Date.now())); }
90
110
  catch (e) { throw friendly({ action: 'pause the clock', cause: e, hint: ISO_HINT }); }
91
111
  });
@@ -101,6 +121,7 @@ When(/^(I |we )*pause the clock$/, async function (pronoun) {
101
121
  *
102
122
  */
103
123
  When(/^(I |we )*resume the clock$/, async function (pronoun) {
124
+ await noteClockInstalledNow(this, 'resume the clock');
104
125
  try { await this.page.clock.resume(); }
105
126
  catch (e) { throw friendly({ action: 'resume the clock', cause: e, hint: 'pause the clock first via "When I pause the clock".' }); }
106
127
  });
@@ -123,6 +144,7 @@ When(/^(I |we )*set the system time to "([^"]*)"$/, async function (pronoun, iso
123
144
  hint: 'use an ISO 8601 date like "2026-05-08T12:30:00Z".',
124
145
  });
125
146
  }
147
+ await noteClockInstalledNow(this, `set the system time to "${iso}"`);
126
148
  try { await this.page.clock.setSystemTime(d); }
127
149
  catch (e) { throw friendly({ action: `set the system time to "${iso}"`, cause: e, hint: ISO_HINT }); }
128
150
  });
@@ -11,6 +11,10 @@ const { Then } = require('@cucumber/cucumber');
11
11
  * Example #1: Then print current URL
12
12
  * Example #2: When print current URL
13
13
  * Example #3: And print current URL
14
+ * Example #4: Given I am on "/about-us.html"
15
+ * Then print current URL
16
+ * Example #5: When I press "Search"
17
+ * Then print current URL
14
18
  */
15
19
  Then(/^print current URL$/, function () {
16
20
  try {
@@ -27,6 +31,10 @@ Then(/^print current URL$/, function () {
27
31
  * Example #1: Then print last response
28
32
  * Example #2: When print last response
29
33
  * Example #3: And print last response
34
+ * Example #4: Given I am on "/about-us.html"
35
+ * Then print last response
36
+ * Example #5: When I follow "Contact"
37
+ * Then print last response
30
38
  */
31
39
  Then(/^print last response$/, async function () {
32
40
  try {
@@ -9,6 +9,13 @@
9
9
 
10
10
  const { Given, Then } = require('@cucumber/cucumber');
11
11
  const assert = require('assert');
12
+ const { onNewPage } = require('./webship');
13
+
14
+ // A handler waiting for a dialog goes over to the page of a browser context
15
+ // that a step replaces (restoring an auth state, a video recording).
16
+ onNewPage((world, page) => {
17
+ if (world._dialogHandler) page.on('dialog', world._dialogHandler);
18
+ });
12
19
 
13
20
  // Single shared attach() — handles single-shot ("next") and persistent
14
21
  // ("all") variants via the `once` flag.
@@ -75,9 +82,9 @@ Given(/^(I |we )*will accept the next dialog$/, function (pronoun) {
75
82
  * Then I should be on the homepage
76
83
  * Example #4: Given I will dismiss the next dialog
77
84
  * When I press "Delete"
78
- * Then "<.row>" should still be visible
85
+ * Then ".row" should be visible
79
86
  * Example #5: Given I will dismiss the next dialog
80
- * When I close the tab
87
+ * When I reload the page
81
88
  *
82
89
  */
83
90
  Given(/^(I |we )*will dismiss the next dialog$/, function (pronoun) {
@@ -1,12 +1,18 @@
1
1
  'use strict';
2
2
 
3
- const { friendly } = require('./webship');
3
+ const { friendly, failure, registeredNameHint } = require('./webship');
4
4
 
5
5
  // Element interactions and visual / positional assertions using Playwright.
6
6
 
7
7
  const { Given, When, Then } = require('@cucumber/cucumber');
8
8
  const assert = require('assert');
9
9
 
10
+ // The hint for an element step given a name of the selector registry: the same
11
+ // step with the selector the name stands for.
12
+ function elementRegistryHint(world, sel, step) {
13
+ return registeredNameHint(world, sel, { withSelector: (selector) => step.replace('{selector}', selector) });
14
+ }
15
+
10
16
  /**
11
17
  * Assert element A is positioned vertically below element B (greater Y).
12
18
  *
@@ -27,7 +33,69 @@ Then('the element {string} should appear after the element {string}', async func
27
33
  });
28
34
 
29
35
  /**
30
- * Assert text A appears after text B in the document body's text order.
36
+ * A short excerpt of `text` around the place `index`, for a failure message.
37
+ *
38
+ * @param {string} text
39
+ * @param {number} index
40
+ * @param {number} length
41
+ * @returns {string}
42
+ */
43
+ function around(text, index, length) {
44
+ const start = Math.max(0, index - 30);
45
+ const end = Math.min(text.length, index + length + 30);
46
+ return `${start > 0 ? '…' : ''}${text.slice(start, end).replace(/\s+/g, ' ').trim()}${end < text.length ? '…' : ''}`;
47
+ }
48
+
49
+ /**
50
+ * Check that the first place `after` appears comes later than the first place
51
+ * `before` appears, in the visible text of the page or of one element.
52
+ *
53
+ * @param {Object} world
54
+ * @param {string} after
55
+ * @param {string} before
56
+ * @param {string} [scope] - CSS selector of the element to read; the page when absent.
57
+ */
58
+ async function assertTextAfter(world, after, before, scope) {
59
+ let text;
60
+ if (scope) {
61
+ const element = world.page.locator(scope).first();
62
+ try {
63
+ await element.waitFor({ state: 'attached', timeout: 5000 });
64
+ } catch {
65
+ throw failure(world.page, `No element matches "${scope}" after 5 seconds.`, {
66
+ hint: 'the last argument is a CSS selector of the element whose text is read, such as "nav.breadcrumb".',
67
+ });
68
+ }
69
+ text = await element.innerText();
70
+ } else {
71
+ text = await world.page.locator('body').innerText();
72
+ }
73
+ const where = scope ? `in the element "${scope}"` : 'on the page';
74
+ const scopedForm = `the text "${after}" should appear after the text "${before}" in the "<selector>" element`;
75
+ const iAfter = text.indexOf(after);
76
+ const iBefore = text.indexOf(before);
77
+ if (iAfter === -1 || iBefore === -1) {
78
+ const missing = [iAfter === -1 ? after : null, iBefore === -1 ? before : null].filter((t) => t !== null);
79
+ throw failure(world.page, `The text ${missing.map((t) => `"${t}"`).join(' and the text ')} ${missing.length > 1 ? 'are' : 'is'} not ${where}.`, {
80
+ hint: 'the step reads the visible text, with its letter case.',
81
+ });
82
+ }
83
+ if (iAfter <= iBefore) {
84
+ throw failure(world.page, `The text "${after}" does not appear after the text "${before}" ${where}.`, {
85
+ found: `"${after}" first at "${around(text, iAfter, after.length)}"; "${before}" first at "${around(text, iBefore, before.length)}"`,
86
+ hint: scope
87
+ ? 'the step compares the first place each text appears in the visible text of the element, with its letter case.'
88
+ : `the step compares the first place each text appears in the visible text of the whole page, with its letter case, so a menu or a header can decide it. To compare them inside one part of the page, use: ${scopedForm}`,
89
+ });
90
+ }
91
+ }
92
+
93
+ /**
94
+ * Assert text A appears after text B in the visible text of the page.
95
+ *
96
+ * The first place each text appears on the whole page is compared, so a text
97
+ * that a menu or a header also holds is found there first. To compare two
98
+ * texts inside one part of the page, add `in the "<selector>" element`.
31
99
  *
32
100
  * Example #1: Then the text "Sign in" should appear after the text "Welcome"
33
101
  * Example #2: Then the text "Total" should appear after the text "Subtotal"
@@ -37,12 +105,22 @@ Then('the element {string} should appear after the element {string}', async func
37
105
  *
38
106
  */
39
107
  Then('the text {string} should appear after the text {string}', async function (t1, t2) {
40
- const body = await this.page.locator('body').innerText();
41
- const i1 = body.indexOf(t1);
42
- const i2 = body.indexOf(t2);
43
- assert.ok(i1 !== -1, `Text "${t1}" not found.`);
44
- assert.ok(i2 !== -1, `Text "${t2}" not found.`);
45
- assert.ok(i1 > i2, `Text "${t1}" should appear after "${t2}".`);
108
+ await assertTextAfter(this, t1, t2);
109
+ });
110
+
111
+ /**
112
+ * Assert text A appears after text B inside one element: the first place each
113
+ * text appears in the visible text of the first element the selector matches.
114
+ *
115
+ * Example #1: Then the text "Products" should appear after the text "Home" in the "nav.breadcrumb" element
116
+ * Example #2: Then the text "Total" should appear after the text "Subtotal" in the "#cart" element
117
+ * Example #3: And the text "Step 3" should appear after the text "Step 2" in the ".wizard" element
118
+ * Example #4: Then the text "Privacy" should appear after the text "Terms" in the "footer" element
119
+ * Example #5: Then the text "Reply" should appear after the text "Comment" in the "article" element
120
+ *
121
+ */
122
+ Then('the text {string} should appear after the text {string} in the {string} element', async function (t1, t2, scope) {
123
+ await assertTextAfter(this, t1, t2, scope);
46
124
  });
47
125
 
48
126
  /**
@@ -106,7 +184,10 @@ Then('the element {string} with the attribute {string} and the value containing
106
184
  });
107
185
 
108
186
  /**
109
- * Assert an element is positioned within the top 100 px of the viewport.
187
+ * Assert an element is at the top of the viewport: the top of its box is
188
+ * between 0 and 100 pixels from the top of the viewport. The step looks
189
+ * again for up to 5 seconds, so an element still on its way after a smooth
190
+ * scroll gets there.
110
191
  *
111
192
  * Example #1: Then the element "#header" should be at the top of the viewport
112
193
  * Example #2: Then the element "h1" should be at the top of the viewport
@@ -114,12 +195,46 @@ Then('the element {string} with the attribute {string} and the value containing
114
195
  * Example #4: When I scroll to the top
115
196
  * Then the element "#hero" should be at the top of the viewport
116
197
  * Example #5: Then the element "[role=banner]" should be at the top of the viewport
198
+ * Example #6: When I click "Go to section 3"
199
+ * Then the element "#section-3" should be at the top of the viewport
117
200
  *
118
201
  */
119
202
  Then('the element {string} should be at the top of the viewport', async function (sel) {
120
- const box = await this.page.locator(sel).first().boundingBox();
121
- assert.ok(box, `Element "${sel}" not found or not visible.`);
122
- assert.ok(box.y >= 0 && box.y <= 100, `Element "${sel}" is not at top of viewport (y=${box.y}).`);
203
+ const element = this.page.locator(sel).first();
204
+ const deadline = Date.now() + 5000;
205
+ let state = 'missing';
206
+ let top = null;
207
+ for (;;) {
208
+ if (await element.count().catch(() => 0)) {
209
+ const box = await element.boundingBox().catch(() => null);
210
+ if (box) {
211
+ top = box.y;
212
+ state = 'placed';
213
+ if (top >= 0 && top <= 100) return;
214
+ } else {
215
+ state = 'hidden';
216
+ }
217
+ } else {
218
+ state = 'missing';
219
+ }
220
+ if (Date.now() >= deadline) break;
221
+ await this.page.waitForTimeout(100);
222
+ }
223
+ if (state === 'missing') {
224
+ throw failure(this.page, `No element matches "${sel}" after 5 seconds.`, {
225
+ hint: elementRegistryHint(this, sel, 'the element "{selector}" should be at the top of the viewport') ||
226
+ 'the argument is a CSS selector, such as "#hero" or "header.site-header".',
227
+ });
228
+ }
229
+ if (state === 'hidden') {
230
+ throw failure(this.page, `The element "${sel}" is on the page but not visible after 5 seconds.`, {
231
+ hint: 'a hidden element has no place in the viewport.',
232
+ });
233
+ }
234
+ throw failure(this.page, `The element "${sel}" is not at the top of the viewport after 5 seconds.`, {
235
+ found: `its top is ${Math.round(top)} px from the top of the viewport`,
236
+ hint: `the step passes when the top of the element is between 0 and 100 pixels from the top of the viewport. To bring it there, use: When I scroll to the element "${sel}"`,
237
+ });
123
238
  });
124
239
 
125
240
  /**
@@ -135,7 +250,9 @@ Then('the element {string} should be at the top of the viewport', async function
135
250
  Then('the element {string} should be centered in the viewport', async function (sel) {
136
251
  const box = await this.page.locator(sel).first().boundingBox();
137
252
  assert.ok(box, `Element "${sel}" not found.`);
138
- const vw = this.page.viewportSize().width;
253
+ // Read the width from the page: page.viewportSize() is null when the
254
+ // browser context is opened with a fluid viewport (`viewport: null`).
255
+ const vw = await this.page.evaluate(() => document.documentElement.clientWidth);
139
256
  const center = box.x + box.width / 2;
140
257
  const tolerance = vw * 0.1;
141
258
  assert.ok(Math.abs(center - vw / 2) <= tolerance, `Element "${sel}" not centered (center=${center}, vw=${vw}).`);
@@ -161,7 +278,7 @@ When(/^(I |we )*click on the element "([^"]*)"$/, async function (pronoun, sel)
161
278
  throw friendly({
162
279
  action: `click on the element "${sel}"`,
163
280
  cause: e,
164
- hint: `check that the element exists on the page, is visible, and is clickable.`,
281
+ hint: elementRegistryHint(this, sel, 'I click on the element "{selector}"') || `check that the element exists on the page, is visible, and is clickable.`,
165
282
  });
166
283
  }
167
284
  });
@@ -186,7 +303,7 @@ When(/^(I |we )*trigger the JS event "([^"]*)" on the element "([^"]*)"$/, async
186
303
  throw friendly({
187
304
  action: `trigger the "${event}" event on "${sel}"`,
188
305
  cause: e,
189
- hint: `use a standard event name like click, change, input, focus, or blur.`,
306
+ hint: elementRegistryHint(this, sel, `I trigger the JS event "${event}" on the element "{selector}"`) || `use a standard event name like click, change, input, focus, or blur.`,
190
307
  });
191
308
  }
192
309
  });
@@ -208,7 +325,7 @@ When(/^(I |we )*scroll to the element "([^"]*)"$/, async function (pronoun, sel)
208
325
  throw friendly({
209
326
  action: `scroll to "${sel}"`,
210
327
  cause: e,
211
- hint: `check the element exists on the page and was not removed before scrolling.`,
328
+ hint: elementRegistryHint(this, sel, 'I scroll to the element "{selector}"') || `check the element exists on the page and was not removed before scrolling.`,
212
329
  });
213
330
  }
214
331
  });
@@ -230,7 +347,7 @@ When(/^(I |we )*hover over the element "([^"]*)"$/, async function (pronoun, sel
230
347
  throw friendly({
231
348
  action: `hover over "${sel}"`,
232
349
  cause: e,
233
- hint: `check the element exists, is visible, and is not covered by another element.`,
350
+ hint: elementRegistryHint(this, sel, 'I hover over the element "{selector}"') || `check the element exists, is visible, and is not covered by another element.`,
234
351
  });
235
352
  }
236
353
  });
@@ -252,7 +369,7 @@ When(/^(I |we )*focus on the element "([^"]*)"$/, async function (pronoun, sel)
252
369
  throw friendly({
253
370
  action: `focus on "${sel}"`,
254
371
  cause: e,
255
- hint: `the element must be focusable — an input, button, link, or have a tabindex.`,
372
+ hint: elementRegistryHint(this, sel, 'I focus on the element "{selector}"') || `the element must be focusable — an input, button, link, or have a tabindex.`,
256
373
  });
257
374
  }
258
375
  });