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,296 @@
1
+ 'use strict';
2
+
3
+ // Web-first assertion steps — each matcher polls the live page until the
4
+ // condition holds or the per-step timeout elapses. The assertion IS the
5
+ // wait, so no `wait for AJAX` is required between an action and its check.
6
+ //
7
+ // Pattern (all steps): "<selector>" should [not] be <state> [within N seconds]
8
+ // Default budget is 5s; override with the trailing "within N seconds" clause.
9
+
10
+ const { Then, When } = require('@cucumber/cucumber');
11
+ const assert = require('assert');
12
+
13
+ function parseTimeout(secondsStr) {
14
+ const n = secondsStr ? parseInt(secondsStr, 10) : 0;
15
+ return n > 0 ? n * 1000 : 5000;
16
+ }
17
+
18
+ // Poll fn() until it returns truthy, or timeout. fn() returns a value;
19
+ // `predicate` decides pass/fail. Returns the last value seen.
20
+ async function poll(fn, predicate, timeout, message) {
21
+ const deadline = Date.now() + timeout;
22
+ let last;
23
+ while (Date.now() < deadline) {
24
+ try {
25
+ last = await fn();
26
+ if (predicate(last)) return last;
27
+ } catch (e) {
28
+ last = e;
29
+ }
30
+ await new Promise((r) => setTimeout(r, 100));
31
+ }
32
+ throw new Error(`${message} (last seen: ${typeof last === 'object' ? JSON.stringify(last) : String(last)})`);
33
+ }
34
+
35
+ async function checkState(locator, state) {
36
+ switch (state) {
37
+ case 'visible': return locator.first().isVisible();
38
+ case 'hidden': return !(await locator.first().isVisible().catch(() => false));
39
+ case 'attached': return (await locator.count()) > 0;
40
+ case 'focused': return locator.first().evaluate((el) => el === document.activeElement);
41
+ case 'enabled': return locator.first().isEnabled();
42
+ case 'disabled': return locator.first().isDisabled();
43
+ case 'editable': return locator.first().isEditable();
44
+ }
45
+ return false;
46
+ }
47
+
48
+ // ---------------------------------------------------------------------------
49
+ // State matchers
50
+ // ---------------------------------------------------------------------------
51
+
52
+ /**
53
+ * Auto-retrying state assertion. Polls the live page until the matcher passes
54
+ * or the budget elapses. Default budget 5 s.
55
+ *
56
+ * Example #1: Then "#dashboard" should be visible
57
+ * Example #2: Then ".success-banner" should be visible within 10 seconds
58
+ * Example #3: And "[data-testid=signup-cta]" should be focused
59
+ * Example #4: Then "button.submit" should be enabled
60
+ * Example #5: Then "input#email" should be editable
61
+ *
62
+ */
63
+ Then(/^"([^"]*)" should be (visible|hidden|attached|focused|enabled|disabled|editable)(?: within (\d+) seconds?)?$/, async function (selector, state, sec) {
64
+ const loc = this.page.locator(selector);
65
+ await poll(
66
+ () => checkState(loc, state),
67
+ (v) => v === true,
68
+ parseTimeout(sec),
69
+ `Expected "${selector}" to be ${state}`
70
+ );
71
+ });
72
+
73
+ /**
74
+ * Auto-retrying negated state assertion.
75
+ *
76
+ * Example #1: Then "#loading-spinner" should not be visible
77
+ * Example #2: Then ".error" should not be visible within 5 seconds
78
+ * Example #3: And "button.submit" should not be disabled
79
+ * Example #4: Then "input#email" should not be editable
80
+ * Example #5: Then "[data-testid=password]" should not be focused
81
+ *
82
+ */
83
+ Then(/^"([^"]*)" should not be (visible|hidden|attached|focused|enabled|disabled|editable)(?: within (\d+) seconds?)?$/, async function (selector, state, sec) {
84
+ const loc = this.page.locator(selector);
85
+ await poll(
86
+ () => checkState(loc, state),
87
+ (v) => v === false,
88
+ parseTimeout(sec),
89
+ `Expected "${selector}" to not be ${state}`
90
+ );
91
+ });
92
+
93
+ /**
94
+ * Assert an element's bounding box overlaps the visible viewport rectangle.
95
+ *
96
+ * Example #1: Then "#hero" should be in the viewport
97
+ * Example #2: Then "[data-testid=cta]" should be in the viewport within 3 seconds
98
+ * Example #3: When I scroll to the element "#footer"
99
+ * Then "#footer" should be in the viewport
100
+ * Example #4: Then "h1" should be in the viewport
101
+ * Example #5: Then ".banner" should be in the viewport
102
+ *
103
+ */
104
+ Then(/^"([^"]*)" should be in the viewport(?: within (\d+) seconds?)?$/, async function (selector, sec) {
105
+ const loc = this.page.locator(selector).first();
106
+ await poll(
107
+ async () => loc.evaluate((el) => {
108
+ const r = el.getBoundingClientRect();
109
+ return r.bottom > 0 && r.top < (window.innerHeight || 0)
110
+ && r.right > 0 && r.left < (window.innerWidth || 0);
111
+ }),
112
+ (v) => v === true,
113
+ parseTimeout(sec),
114
+ `Expected "${selector}" to be in viewport`
115
+ );
116
+ });
117
+
118
+ /**
119
+ * Assert an element is OUTSIDE the visible viewport rectangle.
120
+ *
121
+ * Example #1: Then "#footer" should not be in the viewport
122
+ * Example #2: Then "[data-testid=hidden]" should not be in the viewport within 3 seconds
123
+ * Example #3: And ".off-screen" should not be in the viewport
124
+ * Example #4: Then "section.below-fold" should not be in the viewport
125
+ * Example #5: When I scroll to the top
126
+ * Then "#footer" should not be in the viewport
127
+ *
128
+ */
129
+ Then(/^"([^"]*)" should not be in the viewport(?: within (\d+) seconds?)?$/, async function (selector, sec) {
130
+ const loc = this.page.locator(selector).first();
131
+ await poll(
132
+ async () => loc.evaluate((el) => {
133
+ const r = el.getBoundingClientRect();
134
+ return r.bottom > 0 && r.top < (window.innerHeight || 0)
135
+ && r.right > 0 && r.left < (window.innerWidth || 0);
136
+ }).catch(() => false),
137
+ (v) => v === false,
138
+ parseTimeout(sec),
139
+ `Expected "${selector}" to not be in viewport`
140
+ );
141
+ });
142
+
143
+ /**
144
+ * Assert exactly N elements match a selector (auto-retry).
145
+ *
146
+ * Example #1: Then ".product-card" should have a count of 12
147
+ * Example #2: Then ".error" should have a count of 0 within 5 seconds
148
+ * Example #3: And "tr" should have a count of 21
149
+ * Example #4: Then "[data-testid=item]" should have a count of 5
150
+ * Example #5: Then ".feed-item" should have a count of 25 within 10 seconds
151
+ *
152
+ */
153
+ Then(/^"([^"]*)" should have a count of (\d+)(?: within (\d+) seconds?)?$/, async function (selector, count, sec) {
154
+ const expected = parseInt(count, 10);
155
+ const loc = this.page.locator(selector);
156
+ await poll(
157
+ () => loc.count(),
158
+ (v) => v === expected,
159
+ parseTimeout(sec),
160
+ `Expected "${selector}" count to be ${expected}`
161
+ );
162
+ });
163
+
164
+ /**
165
+ * Assert an element's textContent equals an expected string (trimmed).
166
+ *
167
+ * Example #1: Then "h1" should have text "Welcome"
168
+ * Example #2: Then ".badge" should have text "12" within 3 seconds
169
+ * Example #3: And ".total" should have text "$99.00"
170
+ * Example #4: Then "[data-testid=subtitle]" should have text "Premium"
171
+ * Example #5: Then ".alert" should have text "Saved"
172
+ *
173
+ */
174
+ Then(/^"([^"]*)" should have text "([^"]*)"(?: within (\d+) seconds?)?$/, async function (selector, text, sec) {
175
+ const loc = this.page.locator(selector).first();
176
+ await poll(
177
+ () => loc.textContent(),
178
+ (v) => (v || '').trim() === text,
179
+ parseTimeout(sec),
180
+ `Expected "${selector}" text to be "${text}"`
181
+ );
182
+ });
183
+
184
+ /**
185
+ * Assert an element's textContent contains an expected substring.
186
+ *
187
+ * Example #1: Then "h1" should contain text "Welcome"
188
+ * Example #2: Then ".badge" should contain text "unread" within 3 seconds
189
+ * Example #3: And ".total" should contain text "$99"
190
+ * Example #4: Then "[data-testid=subtitle]" should contain text "Premium"
191
+ * Example #5: Then ".alert" should contain text "Saved"
192
+ *
193
+ */
194
+ Then(/^"([^"]*)" should contain text "([^"]*)"(?: within (\d+) seconds?)?$/, async function (selector, text, sec) {
195
+ const loc = this.page.locator(selector).first();
196
+ await poll(
197
+ () => loc.textContent(),
198
+ (v) => (v || '').includes(text),
199
+ parseTimeout(sec),
200
+ `Expected "${selector}" to contain text "${text}"`
201
+ );
202
+ });
203
+
204
+ /**
205
+ * Assert an input's `value` property equals an expected string.
206
+ *
207
+ * Example #1: Then "#email" should have value "alice@example.com"
208
+ * Example #2: Then "input[name=q]" should have value "laptops"
209
+ * Example #3: And "[data-testid=phone]" should have value "0790000000"
210
+ * Example #4: Then "#bio" should have value "" within 3 seconds
211
+ * Example #5: Then "select#country" should have value "JO"
212
+ *
213
+ */
214
+ Then(/^"([^"]*)" should have value "([^"]*)"(?: within (\d+) seconds?)?$/, async function (selector, value, sec) {
215
+ const loc = this.page.locator(selector).first();
216
+ await poll(
217
+ () => loc.inputValue(),
218
+ (v) => v === value,
219
+ parseTimeout(sec),
220
+ `Expected "${selector}" value to be "${value}"`
221
+ );
222
+ });
223
+
224
+ /**
225
+ * Assert an element's attribute equals an expected value.
226
+ *
227
+ * Example #1: Then "#tab-1" should have attribute "aria-selected" with value "true"
228
+ * Example #2: Then "[data-testid=cta]" should have attribute "data-state" with value "open"
229
+ * Example #3: And "img.logo" should have attribute "alt" with value "Webship.co"
230
+ * Example #4: Then "a.signup" should have attribute "href" with value "/signup"
231
+ * Example #5: Then "input#email" should have attribute "type" with value "email"
232
+ *
233
+ */
234
+ Then(/^"([^"]*)" should have attribute "([^"]*)" with value "([^"]*)"(?: within (\d+) seconds?)?$/, async function (selector, attr, value, sec) {
235
+ const loc = this.page.locator(selector).first();
236
+ await poll(
237
+ () => loc.getAttribute(attr),
238
+ (v) => v === value,
239
+ parseTimeout(sec),
240
+ `Expected "${selector}" attribute "${attr}" to be "${value}"`
241
+ );
242
+ });
243
+
244
+ /**
245
+ * Assert an element's `class` attribute contains a class token.
246
+ *
247
+ * Example #1: Then "#tab-1" should have class "is-active"
248
+ * Example #2: Then ".modal" should have class "show" within 3 seconds
249
+ * Example #3: And ".dropdown" should have class "open"
250
+ * Example #4: Then "tr.row-1" should have class "selected"
251
+ * Example #5: Then "[data-testid=card]" should have class "highlighted"
252
+ *
253
+ */
254
+ Then(/^"([^"]*)" should have class "([^"]*)"(?: within (\d+) seconds?)?$/, async function (selector, cls, sec) {
255
+ const loc = this.page.locator(selector).first();
256
+ await poll(
257
+ () => loc.getAttribute('class'),
258
+ (v) => (v || '').split(/\s+/).includes(cls),
259
+ parseTimeout(sec),
260
+ `Expected "${selector}" to have class "${cls}"`
261
+ );
262
+ });
263
+
264
+ /**
265
+ * Click an element by its accessible role + name (Playwright `getByRole`).
266
+ *
267
+ * Example #1: When I click the "Sign in" button
268
+ * Example #2: When I click the "Profile" link
269
+ * Example #3: And we click the "Notifications" tab
270
+ * Example #4: When I click the "Subscribe" checkbox
271
+ * Example #5: When I click the "Premium" radio
272
+ *
273
+ */
274
+ When(/^(I |we )*click the "([^"]*)" (button|link|tab|menuitem|checkbox|radio|option)$/, async function (pronoun, name, role) {
275
+ await this.page.getByRole(role, { name }).first().click();
276
+ });
277
+
278
+ /**
279
+ * Assert a role-addressed element is visible (auto-retry).
280
+ *
281
+ * Example #1: Then the "Save changes" button should be visible
282
+ * Example #2: Then the "Profile" link should be visible within 5 seconds
283
+ * Example #3: And the "Privacy" tab should be visible
284
+ * Example #4: Then the "I agree" checkbox should be visible
285
+ * Example #5: Then the "Premium" radio should be visible
286
+ *
287
+ */
288
+ Then(/^the "([^"]*)" (button|link|tab|menuitem|checkbox|radio|option) should be visible(?: within (\d+) seconds?)?$/, async function (name, role, sec) {
289
+ const loc = this.page.getByRole(role, { name }).first();
290
+ await poll(
291
+ () => loc.isVisible(),
292
+ (v) => v === true,
293
+ parseTimeout(sec),
294
+ `Expected ${role} "${name}" to be visible`
295
+ );
296
+ });