webship-js 2.0.1 → 2.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (194) hide show
  1. package/AGENTS.md +109 -0
  2. package/CLAUDE.md +317 -0
  3. package/bin/generate-reports.js +363 -0
  4. package/bin/init-webship.js +343 -0
  5. package/bin/postinstall.js +8 -74
  6. package/cucumber.js +66 -2
  7. package/docs/00-quick-start.md +102 -0
  8. package/docs/01-getting-started.md +102 -0
  9. package/docs/02-bbr-smart-waits.md +77 -0
  10. package/docs/03-selector-registry.md +95 -0
  11. package/docs/04-step-reference.md +728 -0
  12. package/docs/05-web-first-assertions.md +91 -0
  13. package/docs/06-network-and-dialogs.md +83 -0
  14. package/docs/07-auth-state.md +75 -0
  15. package/docs/08-clock-mocking.md +59 -0
  16. package/docs/09-api-testing.md +114 -0
  17. package/docs/10-accessibility.md +167 -0
  18. package/docs/11-debugging.md +129 -0
  19. package/docs/12-ai-agent-guide.md +338 -0
  20. package/docs/13-faq.md +236 -0
  21. package/docs/14-recipes-cookbook.md +255 -0
  22. package/docs/15-tag-conventions.md +76 -0
  23. package/docs/advanced-screenshots/then-i-save-fullscreen-screenshot.md +36 -0
  24. package/docs/advanced-screenshots/then-i-save-width-x-height-screenshot.md +34 -0
  25. package/docs/advanced-screenshots/when-i-save-screenshot-name-filename.md +45 -0
  26. package/docs/advanced-screenshots.md +52 -0
  27. package/docs/advanced-selectors.md +18 -0
  28. package/docs/api-step-definitions.md +45 -0
  29. package/docs/diffy-step-definitions/then-compare-diffy-env1-env2.md +30 -0
  30. package/docs/diffy-step-definitions/then-create-diffy-comparison-name-value.md +21 -0
  31. package/docs/diffy-step-definitions/then-create-diffy-comparison.md +25 -0
  32. package/docs/diffy-step-definitions/then-create-diffy-screenshot-environment-name.md +35 -0
  33. package/docs/diffy-step-definitions/then-i-take-screenshot.md +21 -0
  34. package/docs/diffy-step-definitions/then-i-take-screenshots-all-breakpoints.md +27 -0
  35. package/docs/diffy-step-definitions/then-send-screenshots-diffy-name-value.md +27 -0
  36. package/docs/diffy-step-definitions/then-upload-folder-url-diffy-snapshotname.md +28 -0
  37. package/docs/diffy-step-definitions/then-wait-diffy-comparison-complete.md +21 -0
  38. package/docs/diffy-step-definitions/when-i-resize-window-number.md +29 -0
  39. package/docs/diffy-step-definitions.md +21 -0
  40. package/docs/global-settings.md +244 -0
  41. package/docs/index.md +104 -0
  42. package/docs/install-webship-js/ddev-webship-js.md +52 -0
  43. package/docs/install-webship-js.md +35 -0
  44. package/docs/overview.md +41 -0
  45. package/docs/step-definitions/given-i-am-anonymous-user.md +67 -0
  46. package/docs/step-definitions/given-i-am-homepage.md +68 -0
  47. package/docs/step-definitions/given-i-am-specific-page.md +72 -0
  48. package/docs/step-definitions/then-i-should-be.md +56 -0
  49. package/docs/step-definitions/then-i-should-see.md +62 -0
  50. package/docs/step-definitions/then-item-checkbox.md +54 -0
  51. package/docs/step-definitions/then-item-link-should-contain-url.md +84 -0
  52. package/docs/step-definitions/then-item-should-contain.md +67 -0
  53. package/docs/step-definitions/then-radio-button-value-should-be-selected.md +68 -0
  54. package/docs/step-definitions/then-response-status-code-should-be-number.md +69 -0
  55. package/docs/step-definitions/then-value-radio-button-selected.md +62 -0
  56. package/docs/step-definitions/when-i-attach-file-file-name-element.md +71 -0
  57. package/docs/step-definitions/when-i-check-checkbox.md +60 -0
  58. package/docs/step-definitions/when-i-click-link.md +51 -0
  59. package/docs/step-definitions/when-i-click-operation-text-row.md +71 -0
  60. package/docs/step-definitions/when-i-fill.md +59 -0
  61. package/docs/step-definitions/when-i-go-homepage.md +60 -0
  62. package/docs/step-definitions/when-i-go-specific-page.md +67 -0
  63. package/docs/step-definitions/when-i-move-backward-one-page.md +49 -0
  64. package/docs/step-definitions/when-i-move-forward-one-page.md +58 -0
  65. package/docs/step-definitions/when-i-press-button.md +58 -0
  66. package/docs/step-definitions/when-i-reload-page.md +51 -0
  67. package/docs/step-definitions/when-i-scroll.md +73 -0
  68. package/docs/step-definitions/when-i-select-option-select-list.md +53 -0
  69. package/docs/step-definitions/when-i-select-radio-button-value.md +62 -0
  70. package/docs/step-definitions/when-i-uncheck-checkbox.md +57 -0
  71. package/docs/step-definitions/when-i-wait-ajax-finish.md +64 -0
  72. package/docs/step-definitions/when-i-wait.md +62 -0
  73. package/docs/step-definitions.md +50 -0
  74. package/examples/a11y.html +31 -0
  75. package/examples/cookies.html +10 -0
  76. package/examples/date.html +12 -0
  77. package/examples/diffy/baseline.html +54 -0
  78. package/examples/diffy/changed.html +63 -0
  79. package/examples/diffy/index.html +52 -0
  80. package/examples/element.html +11 -0
  81. package/examples/field.html +24 -0
  82. package/examples/index.html +6 -0
  83. package/examples/keyboard.html +11 -0
  84. package/examples/links.html +9 -0
  85. package/examples/modal.html +14 -0
  86. package/examples/path.html +3 -0
  87. package/examples/table.html +13 -0
  88. package/examples/test--when--i-additionally-select.html +27 -0
  89. package/package.json +19 -6
  90. package/playwright.config.ts +3 -2
  91. package/tests/features/a11y.feature +39 -0
  92. package/tests/features/cookie.feature +13 -0
  93. package/tests/features/date.feature +11 -0
  94. package/tests/features/diffy/test--diffy-01-example-demo.feature +22 -0
  95. package/tests/features/diffy/test--diffy-02-all-steps.feature +52 -0
  96. package/tests/features/diffy/test--diffy-03-real-api.feature +21 -0
  97. package/tests/features/element.feature +16 -0
  98. package/tests/features/field.feature +25 -0
  99. package/tests/features/keyboard.feature +10 -0
  100. package/tests/features/link.feature +11 -0
  101. package/tests/features/modal-advanced-example.feature +1 -1
  102. package/tests/features/modal.feature +11 -0
  103. package/tests/features/path.feature +16 -0
  104. package/tests/features/response.feature +8 -0
  105. package/tests/features/responsive.feature +10 -0
  106. package/tests/features/table.feature +18 -0
  107. package/tests/features/test--then--i-save-screenshot.feature +33 -0
  108. package/tests/features/test--then--i-see-locator.feature +320 -0
  109. package/tests/features/test--then--i-should-see-n-elements.feature +24 -0
  110. package/tests/features/test--then--print-current-url-and-response.feature +21 -0
  111. package/tests/features/test--when--i-additionally-select.feature +30 -0
  112. package/tests/features/test--when--i-follow.feature +22 -0
  113. package/tests/features/wait.feature +7 -0
  114. package/tests/features/yaml.feature +102 -0
  115. package/tests/reports/README.md +55 -0
  116. package/tests/selectors/_canonical-keys.json +113 -0
  117. package/tests/selectors/back-end-selectors.json +19 -0
  118. package/tests/selectors/cms-contentful-admin.json +35 -0
  119. package/tests/selectors/cms-craft-admin.json +39 -0
  120. package/tests/selectors/cms-drupal-cms-gin.json +56 -0
  121. package/tests/selectors/cms-drupal-core-claro.json +50 -0
  122. package/tests/selectors/cms-generic-admin.json +34 -0
  123. package/tests/selectors/cms-ghost-admin.json +34 -0
  124. package/tests/selectors/cms-joomla-admin.json +41 -0
  125. package/tests/selectors/cms-magento2-admin.json +32 -0
  126. package/tests/selectors/cms-prestashop-admin.json +38 -0
  127. package/tests/selectors/cms-shopify-admin.json +25 -0
  128. package/tests/selectors/cms-strapi-admin.json +42 -0
  129. package/tests/selectors/cms-typo3-admin.json +41 -0
  130. package/tests/selectors/cms-woocommerce-front.json +50 -0
  131. package/tests/selectors/cms-wordpress-admin.json +31 -0
  132. package/tests/selectors/framework-ant-design.json +80 -0
  133. package/tests/selectors/framework-bootstrap.json +86 -0
  134. package/tests/selectors/framework-bulma.json +74 -0
  135. package/tests/selectors/framework-chakra.json +58 -0
  136. package/tests/selectors/framework-foundation.json +51 -0
  137. package/tests/selectors/framework-material-ui.json +72 -0
  138. package/tests/selectors/framework-shadcn.json +51 -0
  139. package/tests/selectors/framework-tailwind.json +40 -0
  140. package/tests/selectors/framework-vuetify.json +61 -0
  141. package/tests/selectors/front-end-selectors.json +16 -0
  142. package/tests/selectors/homepage-selectors.json +13 -0
  143. package/tests/step-definitions/a11y.steps.js +798 -0
  144. package/tests/step-definitions/action.steps.js +167 -0
  145. package/tests/step-definitions/{webship-api.js → api.steps.js} +254 -44
  146. package/tests/step-definitions/assertion.steps.js +352 -0
  147. package/tests/step-definitions/auth.steps.js +124 -0
  148. package/tests/step-definitions/clock.steps.js +128 -0
  149. package/tests/step-definitions/cookie.steps.js +216 -0
  150. package/tests/step-definitions/debug.steps.js +31 -0
  151. package/tests/step-definitions/dialog.steps.js +193 -0
  152. package/tests/step-definitions/element.steps.js +314 -0
  153. package/tests/step-definitions/field.steps.js +653 -0
  154. package/tests/step-definitions/file-download.steps.js +193 -0
  155. package/tests/step-definitions/form.steps.js +333 -0
  156. package/tests/step-definitions/iframe.steps.js +178 -0
  157. package/tests/step-definitions/input.steps.js +163 -0
  158. package/tests/step-definitions/javascript.steps.js +71 -0
  159. package/tests/step-definitions/keyboard.steps.js +78 -0
  160. package/tests/step-definitions/link.steps.js +142 -0
  161. package/tests/step-definitions/metatag.steps.js +91 -0
  162. package/tests/step-definitions/modal.steps.js +219 -0
  163. package/tests/step-definitions/navigation.steps.js +218 -0
  164. package/tests/step-definitions/network.steps.js +238 -0
  165. package/tests/step-definitions/path.steps.js +141 -0
  166. package/tests/step-definitions/response.steps.js +98 -0
  167. package/tests/step-definitions/responsive.steps.js +123 -0
  168. package/tests/step-definitions/rest.steps.js +111 -0
  169. package/tests/step-definitions/screenshot.steps.js +423 -0
  170. package/tests/step-definitions/scroll.steps.js +189 -0
  171. package/tests/step-definitions/selectors.steps.js +996 -0
  172. package/tests/step-definitions/storage.steps.js +194 -0
  173. package/tests/step-definitions/table.steps.js +181 -0
  174. package/tests/step-definitions/wait.steps.js +400 -0
  175. package/tests/step-definitions/web-first.steps.js +296 -0
  176. package/tests/step-definitions/webship.js +567 -923
  177. package/tests/step-definitions/xml.steps.js +409 -0
  178. package/tests/step-definitions/yaml.steps.js +911 -0
  179. package/tests/step-definitions-diffy/README.md +329 -0
  180. package/tests/step-definitions-diffy/mock-diffy-api/server.js +84 -0
  181. package/tests/step-definitions-diffy/webship-diffy-mock.js +31 -0
  182. package/tests/step-definitions-diffy/webship-diffy.js +459 -0
  183. package/tsconfig.json +19 -3
  184. package/generate-reports.js +0 -22
  185. package/required/cucumber.js +0 -37
  186. package/required/generate-reports.js +0 -22
  187. package/required/package.json +0 -18
  188. package/required/playwright.config.ts +0 -37
  189. package/required/tests/features/README.md +0 -1
  190. package/required/tests/features/check-homepage.feature +0 -8
  191. package/required/tests/reports/README.md +0 -1
  192. package/required/tests/step-definitions/README.md +0 -1
  193. package/required/tests/step-definitions/custom.js +0 -4
  194. package/required/tsconfig.json +0 -12
@@ -0,0 +1,314 @@
1
+ 'use strict';
2
+
3
+ // Element interactions and visual / positional assertions using Playwright.
4
+
5
+ const { Given, When, Then } = require('@cucumber/cucumber');
6
+ const assert = require('assert');
7
+
8
+ /**
9
+ * Assert element A is positioned vertically below element B (greater Y).
10
+ *
11
+ * Example #1: Then the element "#footer" should appear after the element "#main"
12
+ * Example #2: Then the element ".checkout" should appear after the element ".cart"
13
+ * Example #3: And the element "#summary" should appear after the element "#details"
14
+ * Example #4: Then the element "h2" should appear after the element "h1"
15
+ * Example #5: Then the element "[data-testid=cta]" should appear after the element ".hero"
16
+ *
17
+ */
18
+ Then('the element {string} should appear after the element {string}', async function (sel1, sel2) {
19
+ const el1 = await this.page.locator(sel1).first();
20
+ const el2 = await this.page.locator(sel2).first();
21
+ const b1 = await el1.boundingBox();
22
+ const b2 = await el2.boundingBox();
23
+ assert.ok(b1 && b2, 'Both elements must be visible.');
24
+ assert.ok(b1.y > b2.y, `Element "${sel1}" should appear after "${sel2}".`);
25
+ });
26
+
27
+ /**
28
+ * Assert text A appears after text B in the document body's text order.
29
+ *
30
+ * Example #1: Then the text "Sign in" should appear after the text "Welcome"
31
+ * Example #2: Then the text "Total" should appear after the text "Subtotal"
32
+ * Example #3: And the text "Footer" should appear after the text "Header"
33
+ * Example #4: Then the text "Privacy" should appear after the text "Terms"
34
+ * Example #5: Then the text "Step 3" should appear after the text "Step 2"
35
+ *
36
+ */
37
+ Then('the text {string} should appear after the text {string}', async function (t1, t2) {
38
+ const body = await this.page.locator('body').innerText();
39
+ const i1 = body.indexOf(t1);
40
+ const i2 = body.indexOf(t2);
41
+ assert.ok(i1 !== -1, `Text "${t1}" not found.`);
42
+ assert.ok(i2 !== -1, `Text "${t2}" not found.`);
43
+ assert.ok(i1 > i2, `Text "${t1}" should appear after "${t2}".`);
44
+ });
45
+
46
+ /**
47
+ * Assert at least one element matching `<selector>[<attr>="<value>"]` exists.
48
+ *
49
+ * Example #1: Then the element "a" with the attribute "href" and the value "/about" should exist
50
+ * Example #2: Then the element "input" with the attribute "name" and the value "email" should exist
51
+ * Example #3: And the element "button" with the attribute "type" and the value "submit" should exist
52
+ * Example #4: Then the element "div" with the attribute "data-testid" and the value "user-list" should exist
53
+ * Example #5: Then the element "img" with the attribute "alt" and the value "Logo" should exist
54
+ *
55
+ */
56
+ Then('the element {string} with the attribute {string} and the value {string} should exist', async function (sel, attr, value) {
57
+ const count = await this.page.locator(`${sel}[${attr}="${value}"]`).count();
58
+ assert.ok(count > 0, `Element "${sel}" with ${attr}="${value}" not found.`);
59
+ });
60
+
61
+ /**
62
+ * Assert at least one element with attribute value containing a substring exists.
63
+ *
64
+ * Example #1: Then the element "a" with the attribute "href" and the value containing "/about" should exist
65
+ * Example #2: Then the element "input" with the attribute "class" and the value containing "is-valid" should exist
66
+ * Example #3: And the element "button" with the attribute "data-testid" and the value containing "cta" should exist
67
+ * Example #4: Then the element "img" with the attribute "src" and the value containing ".png" should exist
68
+ * Example #5: Then the element "div" with the attribute "aria-label" and the value containing "card" should exist
69
+ *
70
+ */
71
+ Then('the element {string} with the attribute {string} and the value containing {string} should exist', async function (sel, attr, value) {
72
+ const count = await this.page.locator(`${sel}[${attr}*="${value}"]`).count();
73
+ assert.ok(count > 0, `Element "${sel}" with ${attr} containing "${value}" not found.`);
74
+ });
75
+
76
+ /**
77
+ * Assert NO element matches `<selector>[<attr>="<value>"]`.
78
+ *
79
+ * Example #1: Then the element "a" with the attribute "href" and the value "/admin" should not exist
80
+ * Example #2: Then the element "input" with the attribute "type" and the value "hidden" should not exist
81
+ * Example #3: And the element "button" with the attribute "disabled" and the value "true" should not exist
82
+ * Example #4: Then the element "div" with the attribute "data-testid" and the value "error" should not exist
83
+ * Example #5: Then the element "img" with the attribute "alt" and the value "" should not exist
84
+ *
85
+ */
86
+ Then('the element {string} with the attribute {string} and the value {string} should not exist', async function (sel, attr, value) {
87
+ const count = await this.page.locator(`${sel}[${attr}="${value}"]`).count();
88
+ assert.strictEqual(count, 0, `Element "${sel}" with ${attr}="${value}" should not exist.`);
89
+ });
90
+
91
+ /**
92
+ * Assert NO element has attribute value containing a substring.
93
+ *
94
+ * Example #1: Then the element "a" with the attribute "href" and the value containing "/old" should not exist
95
+ * Example #2: Then the element "div" with the attribute "class" and the value containing "is-error" should not exist
96
+ * Example #3: And the element "button" with the attribute "data-testid" and the value containing "deprecated" should not exist
97
+ * Example #4: Then the element "img" with the attribute "src" and the value containing "tracking" should not exist
98
+ * Example #5: Then the element "input" with the attribute "name" and the value containing "_legacy" should not exist
99
+ *
100
+ */
101
+ Then('the element {string} with the attribute {string} and the value containing {string} should not exist', async function (sel, attr, value) {
102
+ const count = await this.page.locator(`${sel}[${attr}*="${value}"]`).count();
103
+ assert.strictEqual(count, 0, `Element "${sel}" with ${attr} containing "${value}" should not exist.`);
104
+ });
105
+
106
+ /**
107
+ * Assert an element is positioned within the top 100 px of the viewport.
108
+ *
109
+ * Example #1: Then the element "#header" should be at the top of the viewport
110
+ * Example #2: Then the element "h1" should be at the top of the viewport
111
+ * Example #3: And the element ".sticky-nav" should be at the top of the viewport
112
+ * Example #4: When I scroll to the top
113
+ * Then the element "#hero" should be at the top of the viewport
114
+ * Example #5: Then the element "[role=banner]" should be at the top of the viewport
115
+ *
116
+ */
117
+ Then('the element {string} should be at the top of the viewport', async function (sel) {
118
+ const box = await this.page.locator(sel).first().boundingBox();
119
+ assert.ok(box, `Element "${sel}" not found or not visible.`);
120
+ assert.ok(box.y >= 0 && box.y <= 100, `Element "${sel}" is not at top of viewport (y=${box.y}).`);
121
+ });
122
+
123
+ /**
124
+ * Assert an element is horizontally centered in the viewport (±10% tolerance).
125
+ *
126
+ * Example #1: Then the element ".hero" should be centered in the viewport
127
+ * Example #2: Then the element "#cta" should be centered in the viewport
128
+ * Example #3: And the element ".modal-dialog" should be centered in the viewport
129
+ * Example #4: Then the element "h1" should be centered in the viewport
130
+ * Example #5: Then the element ".loader" should be centered in the viewport
131
+ *
132
+ */
133
+ Then('the element {string} should be centered in the viewport', async function (sel) {
134
+ const box = await this.page.locator(sel).first().boundingBox();
135
+ assert.ok(box, `Element "${sel}" not found.`);
136
+ const vw = this.page.viewportSize().width;
137
+ const center = box.x + box.width / 2;
138
+ const tolerance = vw * 0.1;
139
+ assert.ok(Math.abs(center - vw / 2) <= tolerance, `Element "${sel}" not centered (center=${center}, vw=${vw}).`);
140
+ });
141
+
142
+ // Native browser dialog handlers (alert / confirm / prompt) live in
143
+ // tests/step-definitions/dialog.steps.js.
144
+
145
+ /**
146
+ * Click an element addressed by CSS selector.
147
+ *
148
+ * Example #1: When I click on the element "#sign-in"
149
+ * Example #2: When I click on the element ".btn-primary"
150
+ * Example #3: And we click on the element "[data-testid=cta]"
151
+ * Example #4: When I click on the element "li.nav-item:first-child a"
152
+ * Example #5: When I click on the element "button[aria-label='Close']"
153
+ *
154
+ */
155
+ When(/^(I |we )*click on the element "([^"]*)"$/, async function (pronoun, sel) {
156
+ await this.page.locator(sel).first().click();
157
+ });
158
+
159
+ /**
160
+ * Dispatch a synthetic JavaScript event on a CSS-addressed element.
161
+ *
162
+ * Useful for components that listen for non-bubbling events or for events
163
+ * Playwright cannot synthesize through normal interactions.
164
+ *
165
+ * Example #1: When I trigger the JS event "click" on the element "#cta"
166
+ * Example #2: When I trigger the JS event "change" on the element "#country"
167
+ * Example #3: And I trigger the JS event "input" on the element "#search"
168
+ * Example #4: When I trigger the JS event "focus" on the element "#email"
169
+ * Example #5: When I trigger the JS event "blur" on the element "#name"
170
+ *
171
+ */
172
+ When(/^(I |we )*trigger the JS event "([^"]*)" on the element "([^"]*)"$/, async function (pronoun, event, sel) {
173
+ await this.page.locator(sel).first().dispatchEvent(event);
174
+ });
175
+
176
+ /**
177
+ * Scroll a CSS-addressed element into view (uses Playwright's auto-scroll).
178
+ *
179
+ * Example #1: When I scroll to the element "#footer"
180
+ * Example #2: When I scroll to the element ".pricing-table"
181
+ * Example #3: And we scroll to the element "[data-testid=signup-cta]"
182
+ * Example #4: When I scroll to the element "tbody tr:nth-child(20)"
183
+ * Example #5: When I scroll to the element ".testimonial:last-child"
184
+ *
185
+ */
186
+ When(/^(I |we )*scroll to the element "([^"]*)"$/, async function (pronoun, sel) {
187
+ await this.page.locator(sel).first().scrollIntoViewIfNeeded();
188
+ });
189
+
190
+ /**
191
+ * Hover the mouse pointer over a CSS-addressed element.
192
+ *
193
+ * Example #1: When I hover over the element ".tooltip-trigger"
194
+ * Example #2: When I hover over the element "#user-menu"
195
+ * Example #3: And we hover over the element "[data-testid=avatar]"
196
+ * Example #4: When I hover over the element "img.preview"
197
+ * Example #5: When I hover over the element "li.menu-item"
198
+ *
199
+ */
200
+ When(/^(I |we )*hover over the element "([^"]*)"$/, async function (pronoun, sel) {
201
+ await this.page.locator(sel).first().hover();
202
+ });
203
+
204
+ /**
205
+ * Move keyboard focus to a CSS-addressed element.
206
+ *
207
+ * Example #1: When I focus on the element "#email"
208
+ * Example #2: When I focus on the element "input[type=search]"
209
+ * Example #3: And we focus on the element "[data-testid=combobox]"
210
+ * Example #4: When I focus on the element "textarea#message"
211
+ * Example #5: When I focus on the element "button.primary"
212
+ *
213
+ */
214
+ When(/^(I |we )*focus on the element "([^"]*)"$/, async function (pronoun, sel) {
215
+ await this.page.locator(sel).first().focus();
216
+ });
217
+
218
+ /**
219
+ * Wait for a CSS-addressed element to become visible (display !== none, etc.).
220
+ *
221
+ * Example #1: Then the element "#dashboard" should be displayed
222
+ * Example #2: Then the element ".success-banner" should be displayed
223
+ * Example #3: And the element "[data-testid=user-list]" should be displayed
224
+ * Example #4: Then the element ".toast" should be displayed
225
+ * Example #5: When I press "Save"
226
+ * Then the element ".toast-success" should be displayed
227
+ *
228
+ */
229
+ Then('the element {string} should be displayed', async function (sel) {
230
+ await this.page.locator(sel).first().waitFor({ state: 'visible' });
231
+ });
232
+
233
+ /**
234
+ * Assert a CSS-addressed element is hidden or absent.
235
+ *
236
+ * Example #1: Then the element "#loading-spinner" should not be displayed
237
+ * Example #2: Then the element ".error-banner" should not be displayed
238
+ * Example #3: And the element "[data-testid=skeleton]" should not be displayed
239
+ * Example #4: Then the element ".modal" should not be displayed
240
+ * Example #5: When I press "Submit"
241
+ * Then the element ".pending-badge" should not be displayed
242
+ *
243
+ */
244
+ Then('the element {string} should not be displayed', async function (sel) {
245
+ const loc = this.page.locator(sel).first();
246
+ const count = await loc.count();
247
+ if (count === 0) return;
248
+ assert.ok(!(await loc.isVisible()), `Element "${sel}" should not be displayed.`);
249
+ });
250
+
251
+ async function inViewport(page, sel, topOffset = 0) {
252
+ return await page.locator(sel).first().evaluate((el, off) => {
253
+ const r = el.getBoundingClientRect();
254
+ return r.top >= off && r.left >= 0 && r.bottom <= window.innerHeight && r.right <= window.innerWidth;
255
+ }, topOffset);
256
+ }
257
+
258
+ /**
259
+ * Assert an element is fully inside the current viewport rectangle.
260
+ *
261
+ * Example #1: Then the element "#hero" should be displayed within a viewport
262
+ * Example #2: Then the element ".cta" should be displayed within a viewport
263
+ * Example #3: And the element "[data-testid=summary]" should be displayed within a viewport
264
+ * Example #4: Then the element "h1" should be displayed within a viewport
265
+ * Example #5: When I scroll to the element "#footer"
266
+ * Then the element "#footer" should be displayed within a viewport
267
+ *
268
+ */
269
+ Then('the element {string} should be displayed within a viewport', async function (sel) {
270
+ assert.ok(await inViewport(this.page, sel, 0), `Element "${sel}" is not within viewport.`);
271
+ });
272
+
273
+ /**
274
+ * Assert an element is fully inside the viewport, allowing a top offset.
275
+ * Useful for sticky headers — pass the header height as the offset.
276
+ *
277
+ * Example #1: Then the element "#hero" should be displayed within a viewport with a top offset of 60 pixels
278
+ * Example #2: Then the element ".main" should be displayed within a viewport with a top offset of 80 pixels
279
+ * Example #3: And the element ".cta" should be displayed within a viewport with a top offset of 50 pixels
280
+ * Example #4: Then the element "h1" should be displayed within a viewport with a top offset of 100 pixels
281
+ * Example #5: Then the element "#summary" should be displayed within a viewport with a top offset of 64 pixels
282
+ *
283
+ */
284
+ Then('the element {string} should be displayed within a viewport with a top offset of {int} pixels', async function (sel, off) {
285
+ assert.ok(await inViewport(this.page, sel, off), `Element "${sel}" is not within viewport (offset ${off}).`);
286
+ });
287
+
288
+ /**
289
+ * Assert an element is NOT inside the viewport (top-offset variant).
290
+ *
291
+ * Example #1: Then the element "#footer" should not be displayed within a viewport with a top offset of 60 pixels
292
+ * Example #2: Then the element ".off-screen" should not be displayed within a viewport with a top offset of 80 pixels
293
+ * Example #3: And the element ".pending" should not be displayed within a viewport with a top offset of 50 pixels
294
+ * Example #4: Then the element "#cookies-banner" should not be displayed within a viewport with a top offset of 100 pixels
295
+ * Example #5: Then the element ".low-priority" should not be displayed within a viewport with a top offset of 64 pixels
296
+ *
297
+ */
298
+ Then('the element {string} should not be displayed within a viewport with a top offset of {int} pixels', async function (sel, off) {
299
+ assert.ok(!(await inViewport(this.page, sel, off)), `Element "${sel}" should not be in viewport (offset ${off}).`);
300
+ });
301
+
302
+ /**
303
+ * Assert an element is NOT inside the viewport rectangle.
304
+ *
305
+ * Example #1: Then the element "#footer" should not be displayed within a viewport
306
+ * Example #2: Then the element ".off-screen" should not be displayed within a viewport
307
+ * Example #3: And the element ".pending" should not be displayed within a viewport
308
+ * Example #4: Then the element "#cookies-banner" should not be displayed within a viewport
309
+ * Example #5: Then the element ".low-priority" should not be displayed within a viewport
310
+ *
311
+ */
312
+ Then('the element {string} should not be displayed within a viewport', async function (sel) {
313
+ assert.ok(!(await inViewport(this.page, sel, 0)), `Element "${sel}" should not be in viewport.`);
314
+ });