webship-js 2.0.2 → 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 (162) hide show
  1. package/AGENTS.md +109 -0
  2. package/CLAUDE.md +317 -0
  3. package/bin/generate-reports.js +181 -9
  4. package/cucumber.js +10 -4
  5. package/docs/00-quick-start.md +102 -0
  6. package/docs/01-getting-started.md +102 -0
  7. package/docs/02-bbr-smart-waits.md +77 -0
  8. package/docs/03-selector-registry.md +95 -0
  9. package/docs/04-step-reference.md +728 -0
  10. package/docs/05-web-first-assertions.md +91 -0
  11. package/docs/06-network-and-dialogs.md +83 -0
  12. package/docs/07-auth-state.md +75 -0
  13. package/docs/08-clock-mocking.md +59 -0
  14. package/docs/09-api-testing.md +114 -0
  15. package/docs/10-accessibility.md +167 -0
  16. package/docs/11-debugging.md +129 -0
  17. package/docs/12-ai-agent-guide.md +338 -0
  18. package/docs/13-faq.md +236 -0
  19. package/docs/14-recipes-cookbook.md +255 -0
  20. package/docs/15-tag-conventions.md +76 -0
  21. package/docs/advanced-screenshots/then-i-save-fullscreen-screenshot.md +36 -0
  22. package/docs/advanced-screenshots/then-i-save-width-x-height-screenshot.md +34 -0
  23. package/docs/advanced-screenshots/when-i-save-screenshot-name-filename.md +45 -0
  24. package/docs/advanced-screenshots.md +52 -0
  25. package/docs/advanced-selectors.md +18 -0
  26. package/docs/api-step-definitions.md +45 -0
  27. package/docs/diffy-step-definitions/then-compare-diffy-env1-env2.md +30 -0
  28. package/docs/diffy-step-definitions/then-create-diffy-comparison-name-value.md +21 -0
  29. package/docs/diffy-step-definitions/then-create-diffy-comparison.md +25 -0
  30. package/docs/diffy-step-definitions/then-create-diffy-screenshot-environment-name.md +35 -0
  31. package/docs/diffy-step-definitions/then-i-take-screenshot.md +21 -0
  32. package/docs/diffy-step-definitions/then-i-take-screenshots-all-breakpoints.md +27 -0
  33. package/docs/diffy-step-definitions/then-send-screenshots-diffy-name-value.md +27 -0
  34. package/docs/diffy-step-definitions/then-upload-folder-url-diffy-snapshotname.md +28 -0
  35. package/docs/diffy-step-definitions/then-wait-diffy-comparison-complete.md +21 -0
  36. package/docs/diffy-step-definitions/when-i-resize-window-number.md +29 -0
  37. package/docs/diffy-step-definitions.md +21 -0
  38. package/docs/global-settings.md +244 -0
  39. package/docs/index.md +104 -0
  40. package/docs/install-webship-js/ddev-webship-js.md +52 -0
  41. package/docs/install-webship-js.md +35 -0
  42. package/docs/overview.md +41 -0
  43. package/docs/step-definitions/given-i-am-anonymous-user.md +67 -0
  44. package/docs/step-definitions/given-i-am-homepage.md +68 -0
  45. package/docs/step-definitions/given-i-am-specific-page.md +72 -0
  46. package/docs/step-definitions/then-i-should-be.md +56 -0
  47. package/docs/step-definitions/then-i-should-see.md +62 -0
  48. package/docs/step-definitions/then-item-checkbox.md +54 -0
  49. package/docs/step-definitions/then-item-link-should-contain-url.md +84 -0
  50. package/docs/step-definitions/then-item-should-contain.md +67 -0
  51. package/docs/step-definitions/then-radio-button-value-should-be-selected.md +68 -0
  52. package/docs/step-definitions/then-response-status-code-should-be-number.md +69 -0
  53. package/docs/step-definitions/then-value-radio-button-selected.md +62 -0
  54. package/docs/step-definitions/when-i-attach-file-file-name-element.md +71 -0
  55. package/docs/step-definitions/when-i-check-checkbox.md +60 -0
  56. package/docs/step-definitions/when-i-click-link.md +51 -0
  57. package/docs/step-definitions/when-i-click-operation-text-row.md +71 -0
  58. package/docs/step-definitions/when-i-fill.md +59 -0
  59. package/docs/step-definitions/when-i-go-homepage.md +60 -0
  60. package/docs/step-definitions/when-i-go-specific-page.md +67 -0
  61. package/docs/step-definitions/when-i-move-backward-one-page.md +49 -0
  62. package/docs/step-definitions/when-i-move-forward-one-page.md +58 -0
  63. package/docs/step-definitions/when-i-press-button.md +58 -0
  64. package/docs/step-definitions/when-i-reload-page.md +51 -0
  65. package/docs/step-definitions/when-i-scroll.md +73 -0
  66. package/docs/step-definitions/when-i-select-option-select-list.md +53 -0
  67. package/docs/step-definitions/when-i-select-radio-button-value.md +62 -0
  68. package/docs/step-definitions/when-i-uncheck-checkbox.md +57 -0
  69. package/docs/step-definitions/when-i-wait-ajax-finish.md +64 -0
  70. package/docs/step-definitions/when-i-wait.md +62 -0
  71. package/docs/step-definitions.md +50 -0
  72. package/examples/a11y.html +31 -0
  73. package/examples/cookies.html +10 -0
  74. package/examples/date.html +12 -0
  75. package/examples/element.html +11 -0
  76. package/examples/field.html +24 -0
  77. package/examples/keyboard.html +11 -0
  78. package/examples/links.html +9 -0
  79. package/examples/modal.html +14 -0
  80. package/examples/path.html +3 -0
  81. package/examples/table.html +13 -0
  82. package/package.json +10 -3
  83. package/playwright.config.ts +3 -2
  84. package/tests/features/a11y.feature +39 -0
  85. package/tests/features/cookie.feature +13 -0
  86. package/tests/features/date.feature +11 -0
  87. package/tests/features/element.feature +16 -0
  88. package/tests/features/field.feature +25 -0
  89. package/tests/features/keyboard.feature +10 -0
  90. package/tests/features/link.feature +11 -0
  91. package/tests/features/modal-advanced-example.feature +1 -1
  92. package/tests/features/modal.feature +11 -0
  93. package/tests/features/path.feature +16 -0
  94. package/tests/features/response.feature +8 -0
  95. package/tests/features/responsive.feature +10 -0
  96. package/tests/features/table.feature +18 -0
  97. package/tests/features/wait.feature +7 -0
  98. package/tests/features/yaml.feature +102 -0
  99. package/tests/reports/README.md +55 -0
  100. package/tests/selectors/_canonical-keys.json +113 -0
  101. package/tests/selectors/back-end-selectors.json +7 -1
  102. package/tests/selectors/cms-contentful-admin.json +35 -0
  103. package/tests/selectors/cms-craft-admin.json +39 -0
  104. package/tests/selectors/cms-drupal-cms-gin.json +56 -0
  105. package/tests/selectors/cms-drupal-core-claro.json +50 -0
  106. package/tests/selectors/cms-generic-admin.json +34 -0
  107. package/tests/selectors/cms-ghost-admin.json +34 -0
  108. package/tests/selectors/cms-joomla-admin.json +41 -0
  109. package/tests/selectors/cms-magento2-admin.json +32 -0
  110. package/tests/selectors/cms-prestashop-admin.json +38 -0
  111. package/tests/selectors/cms-shopify-admin.json +25 -0
  112. package/tests/selectors/cms-strapi-admin.json +42 -0
  113. package/tests/selectors/cms-typo3-admin.json +41 -0
  114. package/tests/selectors/cms-woocommerce-front.json +50 -0
  115. package/tests/selectors/cms-wordpress-admin.json +31 -0
  116. package/tests/selectors/framework-ant-design.json +80 -0
  117. package/tests/selectors/framework-bootstrap.json +86 -0
  118. package/tests/selectors/framework-bulma.json +74 -0
  119. package/tests/selectors/framework-chakra.json +58 -0
  120. package/tests/selectors/framework-foundation.json +51 -0
  121. package/tests/selectors/framework-material-ui.json +72 -0
  122. package/tests/selectors/framework-shadcn.json +51 -0
  123. package/tests/selectors/framework-tailwind.json +40 -0
  124. package/tests/selectors/framework-vuetify.json +61 -0
  125. package/tests/step-definitions/a11y.steps.js +798 -0
  126. package/tests/step-definitions/action.steps.js +167 -0
  127. package/tests/step-definitions/{webship-api.js → api.steps.js} +24 -7
  128. package/tests/step-definitions/assertion.steps.js +352 -0
  129. package/tests/step-definitions/auth.steps.js +124 -0
  130. package/tests/step-definitions/clock.steps.js +128 -0
  131. package/tests/step-definitions/cookie.steps.js +216 -0
  132. package/tests/step-definitions/debug.steps.js +31 -0
  133. package/tests/step-definitions/dialog.steps.js +193 -0
  134. package/tests/step-definitions/element.steps.js +314 -0
  135. package/tests/step-definitions/field.steps.js +653 -0
  136. package/tests/step-definitions/file-download.steps.js +193 -0
  137. package/tests/step-definitions/form.steps.js +333 -0
  138. package/tests/step-definitions/iframe.steps.js +178 -0
  139. package/tests/step-definitions/input.steps.js +163 -0
  140. package/tests/step-definitions/javascript.steps.js +71 -0
  141. package/tests/step-definitions/keyboard.steps.js +78 -0
  142. package/tests/step-definitions/link.steps.js +142 -0
  143. package/tests/step-definitions/metatag.steps.js +91 -0
  144. package/tests/step-definitions/modal.steps.js +219 -0
  145. package/tests/step-definitions/navigation.steps.js +218 -0
  146. package/tests/step-definitions/network.steps.js +238 -0
  147. package/tests/step-definitions/path.steps.js +141 -0
  148. package/tests/step-definitions/response.steps.js +98 -0
  149. package/tests/step-definitions/responsive.steps.js +123 -0
  150. package/tests/step-definitions/rest.steps.js +111 -0
  151. package/tests/step-definitions/{webship-screenshot.js → screenshot.steps.js} +1 -5
  152. package/tests/step-definitions/scroll.steps.js +189 -0
  153. package/tests/step-definitions/{webship-selectors.js → selectors.steps.js} +46 -11
  154. package/tests/step-definitions/storage.steps.js +194 -0
  155. package/tests/step-definitions/table.steps.js +181 -0
  156. package/tests/step-definitions/wait.steps.js +400 -0
  157. package/tests/step-definitions/web-first.steps.js +296 -0
  158. package/tests/step-definitions/webship.js +552 -1507
  159. package/tests/step-definitions/xml.steps.js +409 -0
  160. package/tests/step-definitions/yaml.steps.js +911 -0
  161. package/tests/step-definitions-diffy/webship-diffy.js +0 -13
  162. package/tsconfig.json +19 -3
@@ -0,0 +1,193 @@
1
+ 'use strict';
2
+
3
+ // Browser dialog handlers (alert / confirm / prompt / beforeunload).
4
+ // Mirrors Playwright's `page.on('dialog')` API with BDD-friendly phrasing.
5
+ //
6
+ // Attach a handler BEFORE the action that triggers the dialog. Handlers
7
+ // queue dialog messages onto `this._lastDialog` so assertions can inspect
8
+ // them after the action completes.
9
+
10
+ const { Given, Then } = require('@cucumber/cucumber');
11
+ const assert = require('assert');
12
+
13
+ // Single shared attach() — handles single-shot ("next") and persistent
14
+ // ("all") variants via the `once` flag.
15
+ function attach(world, action, promptInput, once) {
16
+ if (world._dialogHandler) {
17
+ try { world.page.off('dialog', world._dialogHandler); } catch { /* ignore */ }
18
+ }
19
+ world._lastDialog = null;
20
+ world._dialogHandler = async (dialog) => {
21
+ world._lastDialog = {
22
+ type: dialog.type(),
23
+ message: dialog.message(),
24
+ defaultValue: dialog.defaultValue(),
25
+ };
26
+ try {
27
+ if (action === 'accept') {
28
+ if (typeof promptInput === 'string' && dialog.type() === 'prompt') {
29
+ await dialog.accept(promptInput);
30
+ } else {
31
+ await dialog.accept();
32
+ }
33
+ } else {
34
+ await dialog.dismiss();
35
+ }
36
+ } catch { /* dialog may have closed already */ }
37
+ if (once) {
38
+ try { world.page.off('dialog', world._dialogHandler); } catch { /* ignore */ }
39
+ world._dialogHandler = null;
40
+ }
41
+ };
42
+ world.page.on('dialog', world._dialogHandler);
43
+ }
44
+
45
+ /**
46
+ * Auto-accept the next native browser dialog (alert / confirm / prompt).
47
+ *
48
+ * Example #1: Given I will accept the next dialog
49
+ * When I click "Delete"
50
+ * Example #2: Given we will accept the next dialog
51
+ * When I press "Confirm"
52
+ * Example #3: Given I will accept the next dialog
53
+ * When I click "Save changes"
54
+ * Then I should see "Saved"
55
+ * Example #4: Given I will accept the next dialog
56
+ * When I follow "Leave page"
57
+ * Example #5: Given I will accept the next dialog
58
+ * When I press "Reset password"
59
+ * Then the last dialog type should be "confirm"
60
+ *
61
+ */
62
+ Given(/^(I |we )*will accept the next dialog$/, function () {
63
+ attach(this, 'accept', undefined, true);
64
+ });
65
+
66
+ /**
67
+ * Auto-dismiss the next native browser dialog.
68
+ *
69
+ * Example #1: Given I will dismiss the next dialog
70
+ * When I click "Leave page"
71
+ * Example #2: Given we will dismiss the next dialog
72
+ * When I press "Cancel reset"
73
+ * Example #3: Given I will dismiss the next dialog
74
+ * When I follow "Other site"
75
+ * Then I should be on the homepage
76
+ * Example #4: Given I will dismiss the next dialog
77
+ * When I press "Delete"
78
+ * Then "<.row>" should still be visible
79
+ * Example #5: Given I will dismiss the next dialog
80
+ * When I close the tab
81
+ *
82
+ */
83
+ Given(/^(I |we )*will dismiss the next dialog$/, function () {
84
+ attach(this, 'dismiss', undefined, true);
85
+ });
86
+
87
+ /**
88
+ * Auto-accept the next prompt with the supplied text input.
89
+ *
90
+ * Example #1: Given I will accept the next dialog with "alice@example.com"
91
+ * When I press "Reset password"
92
+ * Example #2: Given I will accept the next dialog with "Yes"
93
+ * When I click "Continue"
94
+ * Example #3: Given we will accept the next dialog with "Bug report"
95
+ * When I press "Open feedback prompt"
96
+ * Example #4: Given I will accept the next dialog with "12345"
97
+ * When I follow "Set order ID"
98
+ * Example #5: Given I will accept the next dialog with "https://example.com"
99
+ * When I press "Add link"
100
+ *
101
+ */
102
+ Given(/^(I |we )*will accept the next dialog with "([^"]*)"$/, function (pronoun, input) {
103
+ attach(this, 'accept', input, true);
104
+ });
105
+
106
+ /**
107
+ * Assert the most recently captured dialog message equals an expected value.
108
+ *
109
+ * Example #1: Then the last dialog message should be "Are you sure?"
110
+ * Example #2: Then the last dialog message should be "Delete this item?"
111
+ * Example #3: And the last dialog message should be "Leave site?"
112
+ * Example #4: Then the last dialog message should be "Save changes?"
113
+ * Example #5: When I press "Reset"
114
+ * Then the last dialog message should be "Reset all settings?"
115
+ *
116
+ */
117
+ Then(/^the last dialog message should be "([^"]*)"$/, function (text) {
118
+ assert.ok(this._lastDialog, 'No dialog has been captured.');
119
+ assert.strictEqual(this._lastDialog.message, text,
120
+ `Expected dialog message "${text}", got "${this._lastDialog.message}".`);
121
+ });
122
+
123
+ /**
124
+ * Assert the most recently captured dialog message contains an expected substring.
125
+ *
126
+ * Example #1: Then the last dialog message should contain "Are you sure"
127
+ * Example #2: Then the last dialog message should contain "delete"
128
+ * Example #3: And the last dialog message should contain "leave"
129
+ * Example #4: Then the last dialog message should contain "save"
130
+ * Example #5: When I click "Cancel order"
131
+ * Then the last dialog message should contain "cancel"
132
+ *
133
+ */
134
+ Then(/^the last dialog message should contain "([^"]*)"$/, function (text) {
135
+ assert.ok(this._lastDialog, 'No dialog has been captured.');
136
+ assert.ok(this._lastDialog.message.includes(text),
137
+ `Dialog message "${this._lastDialog.message}" does not contain "${text}".`);
138
+ });
139
+
140
+ /**
141
+ * Assert the most recently captured dialog type matches one of `alert`,
142
+ * `confirm`, `prompt`, or `beforeunload`.
143
+ *
144
+ * Example #1: Then the last dialog type should be "confirm"
145
+ * Example #2: Then the last dialog type should be "alert"
146
+ * Example #3: And the last dialog type should be "prompt"
147
+ * Example #4: Then the last dialog type should be "beforeunload"
148
+ * Example #5: When I press "Reset password"
149
+ * Then the last dialog type should be "prompt"
150
+ *
151
+ */
152
+ Then(/^the last dialog type should be "([^"]*)"$/, function (type) {
153
+ assert.ok(this._lastDialog, 'No dialog has been captured.');
154
+ assert.strictEqual(this._lastDialog.type, type,
155
+ `Expected dialog type "${type}", got "${this._lastDialog.type}".`);
156
+ });
157
+
158
+ /**
159
+ * Auto-accept EVERY native browser dialog raised in this scenario.
160
+ *
161
+ * Persistent variant of "I will accept the next dialog" — handler stays
162
+ * attached for the rest of the scenario.
163
+ *
164
+ * Example #1: Given I accept all confirmation dialogs
165
+ * Example #2: Given we accept all confirmation dialogs
166
+ * When I click "Delete all"
167
+ * Example #3: And I accept all confirmation dialogs
168
+ * Example #4: Given I accept all confirmation dialogs
169
+ * When I press "Reset settings"
170
+ * Example #5: Given I accept all confirmation dialogs
171
+ * When I follow "Discard changes"
172
+ *
173
+ */
174
+ Given(/^(I |we )*accept all confirmation dialogs$/, function () {
175
+ attach(this, 'accept', undefined, false);
176
+ });
177
+
178
+ /**
179
+ * Auto-dismiss EVERY native browser dialog raised in this scenario.
180
+ *
181
+ * Example #1: Given I do not accept any confirmation dialogs
182
+ * Example #2: Given we do not accept any confirmation dialogs
183
+ * When I click "Delete"
184
+ * Example #3: And I do not accept any confirmation dialogs
185
+ * Example #4: Given I do not accept any confirmation dialogs
186
+ * When I press "Cancel reset"
187
+ * Example #5: Given I do not accept any confirmation dialogs
188
+ * When I follow "Leave page"
189
+ *
190
+ */
191
+ Given(/^(I |we )*do not accept any confirmation dialogs$/, function () {
192
+ attach(this, 'dismiss', undefined, false);
193
+ });
@@ -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
+ });