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,352 @@
1
+ 'use strict';
2
+
3
+ // All page-level assertion step definitions live here:
4
+ // see / not see text, in element, in row, link href, response body, response
5
+ // status code, element existence, CSS property, regex matching, count.
6
+ //
7
+ // Field-level (checkbox/radio/field-contains) assertions live in field.steps.js.
8
+ // URL/path assertions live in navigation.steps.js.
9
+ // Modal assertions live in modal.steps.js.
10
+
11
+ const { Then } = require('@cucumber/cucumber');
12
+ const assert = require('assert');
13
+ const axios = require('axios');
14
+ const { buildSelector, getLocatorText } = require('./webship');
15
+
16
+ // ---------------------------------------------------------------------------
17
+ // Plain page-text
18
+ // ---------------------------------------------------------------------------
19
+
20
+ /**
21
+ * Assert that text is or is not present on the page.
22
+ *
23
+ * Example #1: Then I should see "Welcome"
24
+ * Example #2: Then we should see "Your accounts for the group is public"
25
+ * Example #3: Then I should not see "Access denied"
26
+ * Example #4: Then we should not see "Edit layout"
27
+ *
28
+ */
29
+ Then(/^(I |we )*should( not)* see "([^"]*)?"$/, async function (pronounCase, notCase, expectedText) {
30
+ if (notCase) {
31
+ const text = await this.page.locator('body').textContent() || '';
32
+ assert.ok(!text.includes(expectedText), `Page should NOT contain "${expectedText}" but it does.`);
33
+ } else {
34
+ await this.page.locator('body').filter({ hasText: expectedText }).waitFor({ timeout: 5000 });
35
+ }
36
+ });
37
+
38
+ /**
39
+ * Assert that page contains or does not contain text matching a regex pattern.
40
+ *
41
+ * Example #1: Then I should see text matching "^T\w+"
42
+ * Example #2: Then I should not see text matching "^O\w+"
43
+ * Example #3: And we should see text matching "\d{4}"
44
+ *
45
+ */
46
+ Then(/^(I |we )*should( not)* see text matching "([^"]*)?"$/, async function (pronounCase, notCase, textPattern) {
47
+ const bodyText = await this.page.evaluate(() => document.body.innerText || '');
48
+ const regex = new RegExp(textPattern);
49
+ if (notCase) {
50
+ assert.ok(!regex.test(bodyText), `Page text should NOT match "${textPattern}" but it does.`);
51
+ } else {
52
+ assert.ok(regex.test(bodyText), `Page text should match "${textPattern}" but it does not.`);
53
+ }
54
+ });
55
+
56
+ // ---------------------------------------------------------------------------
57
+ // Table-row text
58
+ // ---------------------------------------------------------------------------
59
+
60
+ /**
61
+ * Assert text is or is not visible inside a table row identified by text.
62
+ *
63
+ * Example #1: Then I should see "Active" in the "John Smith" row
64
+ * Example #2: Then I should see "In Stock" in the "Product A" row
65
+ * Example #3: Then we should see "Processing" in the "Order #12345" row
66
+ * Example #4: And I should see "Admin" in the "john.smith@example.com" row
67
+ * Example #5: Then I should not see "Admin" in the "Jane Doe" row
68
+ * Example #6: Then I should not see "Out of Stock" in the "Product A" row
69
+ * Example #7: And I should not see "Inactive" in the "john.smith@example.com" row
70
+ *
71
+ */
72
+ Then(/^(I |we )*should( not)* see "([^"]*)?" in( the)* "([^"]*)?" row$/, async function (pronounCase, notCase, expectedText, theCase, rowIdentifier) {
73
+ const found = await this.page.evaluate(({ id, text }) => {
74
+ const rows = Array.from(document.querySelectorAll('tr'));
75
+ return rows.filter(r => r.textContent.includes(id)).some(r => r.textContent.includes(text));
76
+ }, { id: rowIdentifier, text: expectedText });
77
+ if (notCase) {
78
+ assert.ok(!found, `Found "${expectedText}" in the "${rowIdentifier}" row, but it should not be there.`);
79
+ } else {
80
+ assert.ok(found, `Could not find "${expectedText}" in the "${rowIdentifier}" row.`);
81
+ }
82
+ });
83
+
84
+ // ---------------------------------------------------------------------------
85
+ // Element existence + content
86
+ // ---------------------------------------------------------------------------
87
+
88
+ /**
89
+ * Assert that an element with a given label exists (or does not) on the page.
90
+ *
91
+ * Example #1: Then I should see a "Username" element
92
+ * Example #2: Then I should not see a "Username" element
93
+ * Example #3: And we should see an "Email" element
94
+ *
95
+ */
96
+ Then(/^(I |we )*should( not)* see (a|an) "([^"]*)?" element$/, async function (pronounCase, notCase, aAnCase, element) {
97
+ if (notCase) {
98
+ const text = await this.page.locator('body').textContent() || '';
99
+ assert.ok(!text.includes(element), `Page should NOT contain element text "${element}" but it does.`);
100
+ } else {
101
+ const loc = this.page.getByText(element, { exact: true }).first();
102
+ const forAttr = await loc.getAttribute('for').catch(() => null);
103
+ if (forAttr) {
104
+ await this.page.locator('#' + forAttr).waitFor({ state: 'visible', timeout: 3000 });
105
+ } else {
106
+ await loc.waitFor({ state: 'visible', timeout: 3000 });
107
+ }
108
+ }
109
+ });
110
+
111
+ /**
112
+ * Assert that an element, identified by attribute, exists (or does not) on the page.
113
+ *
114
+ * Example #1: Then I should see a "uname" element by its "id" attr
115
+ * Example #2: Then I should see a "pwordcss" element by attr
116
+ * Example #3: Then I should not see an "emailId" element by its "id" attr
117
+ * Example #4: And I should not see a "countryCss" element by attr
118
+ *
119
+ */
120
+ Then(/^(I |we )*should( not)* see (a|an) "([^"]*)?" element by( its)*(?: "([^"]*)?")* (attribute|attr)$/, async function (pronounCase, notCase, aAnCase, attrValue, itsCase, attr, attrWord) {
121
+ const loc = this.page.locator(buildSelector(attrValue, attr));
122
+ if (notCase) {
123
+ assert.strictEqual(await loc.count(), 0, `Element should NOT be present but it is.`);
124
+ } else {
125
+ await loc.first().waitFor({ state: 'visible', timeout: 3000 });
126
+ }
127
+ });
128
+
129
+ /**
130
+ * Assert that an element (found by its label) contains or does not contain text.
131
+ *
132
+ * Example #1: Then I should see "John Smith" in the "Username" element
133
+ * Example #2: Then I should not see "Joe Smith" in the "Username" element
134
+ * Example #3: And we should see "1234" in the "Password" element
135
+ *
136
+ */
137
+ Then(/^(I |we )*should( not)* see "([^"]*)?" in( the)* "([^"]*)?" element$/, async function (pronounCase, notCase, expectedText, theCase, element) {
138
+ const forAttr = await this.page.getByText(element, { exact: true }).getAttribute('for').catch(() => null);
139
+ const loc = this.page.locator(forAttr ? '#' + forAttr : element).first();
140
+ await loc.waitFor({ timeout: 5000 });
141
+ const content = await getLocatorText(loc);
142
+ if (notCase) {
143
+ assert.ok(!content.includes(expectedText), `Element should NOT contain "${expectedText}" but it does.`);
144
+ } else {
145
+ assert.ok(content.includes(expectedText), `Element should contain "${expectedText}" but it does not.`);
146
+ }
147
+ });
148
+
149
+ /**
150
+ * Assert that an element (found by its attribute) contains or does not contain text.
151
+ *
152
+ * Example #1: Then I should see "John Smith" in the "uname" element by its "id" attr
153
+ * Example #2: Then I should see "1234" in the "pwordcss" element by attr
154
+ * Example #3: Then I should not see "John Smith" in the "uname" element by its "id" attr
155
+ * Example #4: Then I should not see "1234" in the "pwordcss" element by attr
156
+ *
157
+ */
158
+ Then(/^(I |we )*should( not)* see "([^"]*)?" in( the)* "([^"]*)?" element by( its)*(?: "([^"]*)?")* (attribute|attr)$/, async function (pronounCase, notCase, expectedText, theCase, attrValue, itsCase, attr, attrWord) {
159
+ const loc = this.page.locator(buildSelector(attrValue, attr)).first();
160
+ await loc.waitFor({ timeout: 10000 });
161
+ const content = await getLocatorText(loc);
162
+ if (notCase) {
163
+ assert.ok(!content.includes(expectedText), `Element should NOT contain "${expectedText}" but it does.`);
164
+ } else {
165
+ assert.ok(content.includes(expectedText), `Element should contain "${expectedText}" but it does not.`);
166
+ }
167
+ });
168
+
169
+ /**
170
+ * Assert that an element's text content does or does not match a regex.
171
+ *
172
+ * Example #1: Then I should see text matching "\d{4}" in the "#year" element
173
+ * Example #2: Then I should see text matching "\$\d+\.\d{2}" in the "#price" element
174
+ * Example #3: Then I should not see text matching "Error" in the "#status" element
175
+ * Example #4: Then we should see text matching "^[A-Z][a-z]+ [A-Z][a-z]+$" in the "#full-name" element
176
+ * Example #5: Then I should see text matching "(0?[1-9]|[12][0-9]|3[01])[\/\-](0?[1-9]|1[012])[\/\-]\d{4}" in the "#date" element
177
+ *
178
+ */
179
+ Then(/^(I |we )*should( not)* see text matching "([^"]*)?" in( the)* "([^"]*)?" element$/, async function (pronounCase, notCase, textPattern, theCase, element) {
180
+ const loc = this.page.locator(element).first();
181
+ await loc.waitFor({ timeout: 5000 });
182
+ const text = await getLocatorText(loc);
183
+ const regex = new RegExp(textPattern);
184
+ if (notCase) {
185
+ assert.ok(!regex.test(text), `Element "${element}" text should NOT match "${textPattern}" but it does.`);
186
+ } else {
187
+ assert.ok(regex.test(text), `Element "${element}" text should match "${textPattern}" but it does not.`);
188
+ }
189
+ });
190
+
191
+ /**
192
+ * Assert that an element has or does not have a specific CSS property.
193
+ *
194
+ * Example #1: Then the "body" element should contain "color:white;"
195
+ * Example #2: Then the "body" element should not contain "color:white;"
196
+ * Example #3: Then the "#uname" element should not contain "border:solid 5px red;"
197
+ * Example #4: Then the "pword" element should not contain "font-size: 26px;"
198
+ *
199
+ */
200
+ Then(/^(the )*"([^"]*)?" element should( not)* contain "([^"]*)?"$/, async function (theCase, selectorRaw, notCase, elementCss) {
201
+ const cssClean = elementCss.replace(/;$/, '');
202
+ const colonIdx = cssClean.indexOf(':');
203
+ const cssProperty = cssClean.substring(0, colonIdx).trim();
204
+ const expectedValue = cssClean.substring(colonIdx + 1).trim();
205
+
206
+ const loc = this.page.locator(buildSelector(selectorRaw)).first();
207
+ await loc.waitFor({ timeout: 10000 });
208
+ const matches = await loc.evaluate((el, { prop, expectedVal }) => {
209
+ function colorToRgb(color) {
210
+ const canvas = document.createElement('canvas');
211
+ canvas.width = canvas.height = 1;
212
+ const ctx = canvas.getContext('2d');
213
+ ctx.fillStyle = 'rgb(1, 2, 3)';
214
+ ctx.fillStyle = color.trim();
215
+ ctx.fillRect(0, 0, 1, 1);
216
+ const d = ctx.getImageData(0, 0, 1, 1).data;
217
+ return 'rgb(' + d[0] + ', ' + d[1] + ', ' + d[2] + ')';
218
+ }
219
+ function isValidColor(value) { return colorToRgb(value) !== 'rgb(1, 2, 3)'; }
220
+ function normalizeColorTokens(value) {
221
+ return value.replace(/rgb\([^)]+\)|rgba\([^)]+\)|#[0-9a-fA-F]+|\b[a-zA-Z]+\b/g,
222
+ (token) => isValidColor(token) ? colorToRgb(token) : token);
223
+ }
224
+ function tokenize(value) {
225
+ const tokens = [], regex = /rgb\([^)]+\)|rgba\([^)]+\)|[^\s]+/g;
226
+ let m;
227
+ while ((m = regex.exec(value)) !== null) tokens.push(m[0]);
228
+ return tokens;
229
+ }
230
+ const computed = window.getComputedStyle(el).getPropertyValue(prop).trim();
231
+ return tokenize(normalizeColorTokens(expectedVal.toLowerCase()))
232
+ .every(token => normalizeColorTokens(computed.toLowerCase()).includes(token));
233
+ }, { prop: cssProperty, expectedVal: expectedValue });
234
+
235
+ if (notCase) {
236
+ assert.ok(!matches, `Element should NOT have CSS "${cssProperty}: ${expectedValue}" but it does.`);
237
+ } else {
238
+ assert.ok(matches, `Element should have CSS "${cssProperty}: ${expectedValue}".`);
239
+ }
240
+ });
241
+
242
+ /**
243
+ * Assert the exact number of elements matching a CSS selector.
244
+ *
245
+ * Example #1: Then I should see 3 "li" elements
246
+ * Example #2: Then I should see 1 "h1" element
247
+ * Example #3: Then we should see 5 ".card" elements
248
+ * Example #4: Then I should see 0 ".error" elements
249
+ * Example #5: And I should see 10 "table tr" elements
250
+ * Example #6: Then I should see 2 "nav a" elements
251
+ * Example #7: Then we should see 4 "ul li" elements
252
+ * Example #8: Then I should see 1 "form" element
253
+ * Example #9: And should see 6 ".product" elements
254
+ * Example #10: Then I should see 8 "[data-testid='row']" elements
255
+ */
256
+ Then(/^(I |we )*should see (\d+) "([^"]*)" elements?$/, async function (pronounCase, num, selector) {
257
+ const expected = parseInt(num, 10);
258
+ const actual = await this.page.locator(selector).count();
259
+ if (actual !== expected) {
260
+ throw new Error(`Expected ${expected} "${selector}" element(s), got ${actual}.`);
261
+ }
262
+ });
263
+
264
+ // ---------------------------------------------------------------------------
265
+ // Link href
266
+ // ---------------------------------------------------------------------------
267
+
268
+ /**
269
+ * Assert that a link (located by its visible text) contains the given URL.
270
+ *
271
+ * Example #1: Then the "Login" link should contain "/log-in"
272
+ * Example #2: And the "About Us" link should contain "/about"
273
+ * Example #3: Then "Home" link should contain "/"
274
+ *
275
+ */
276
+ Then(/^(the )*"([^"]*)?" link should contain "([^"]*)?"$/, async function (theCase, element, url) {
277
+ const loc = this.page.getByText(element, { exact: true }).first();
278
+ await loc.waitFor({ timeout: 5000 });
279
+ const href = await loc.evaluate(el => el.href || el.getAttribute('href') || '');
280
+ assert.ok(href.includes(url), `Expected link "${element}" href to contain "${url}" but got "${href}"`);
281
+ });
282
+
283
+ /**
284
+ * Assert that a link located by its attribute contains the given URL.
285
+ *
286
+ * Example #1: Then the "#about-us-id" link should contain "about" by attr
287
+ * Example #2: And the "aboutUs" link should contain "about" by its "class" attribute
288
+ * Example #3: And the ".contactUs" link should contain "/contact-" by attr
289
+ *
290
+ */
291
+ Then(/^(the )*"([^"]*)?" link should contain "([^"]*)?" by( its)*(?: "([^"]*)?")* (attribute|attr)$/, async function (theCase, attrValue, url, itsCase, attr, attrWord) {
292
+ const loc = this.page.locator(buildSelector(attrValue, attr)).first();
293
+ await loc.waitFor({ timeout: 5000 });
294
+ const href = await loc.evaluate(el => el.href || el.getAttribute('href') || '');
295
+ assert.ok(href.includes(url), `Expected element href to contain "${url}" but got "${href}"`);
296
+ });
297
+
298
+ // ---------------------------------------------------------------------------
299
+ // Response body / status
300
+ // ---------------------------------------------------------------------------
301
+
302
+ /**
303
+ * Assert that the rendered HTML response contains or does not contain text.
304
+ *
305
+ * Reads the entire `<html>` text — useful for checking text that lives in
306
+ * `<head>` (meta descriptions, JSON-LD), `<noscript>`, or hidden regions.
307
+ *
308
+ * Example #1: Then the response should contain "Welcome visitor"
309
+ * Example #2: Then the response should not contain "Access denied"
310
+ * Example #3: And the response should contain "<title>Home</title>"
311
+ * Example #4: Then the response should contain "<html"
312
+ * Example #5: When I am on "/about"
313
+ * Then the response should contain "Our mission"
314
+ * And the response should not contain "TODO"
315
+ *
316
+ */
317
+ Then(/^(the )*response should( not)* contain "([^"]*)?"$/, async function (theCase, notCase, expectedText) {
318
+ const text = await this.page.locator('html').textContent() || '';
319
+ if (notCase) {
320
+ assert.ok(!text.includes(expectedText), `Response should NOT contain "${expectedText}" but it does.`);
321
+ } else {
322
+ assert.ok(text.includes(expectedText), `Response should contain "${expectedText}" but it does not.`);
323
+ }
324
+ });
325
+
326
+ /**
327
+ * Assert that the current page's response status is or is not a given code.
328
+ *
329
+ * Example #1: Then the response status code should be 200
330
+ * Example #2: And the response status code should not be 404
331
+ * Example #3: Then the response status code should be 301
332
+ *
333
+ */
334
+ Then(/^(the )*response status code should( not)* be (\d+)$/, async function (theCase, notCase, expectedStatusCode) {
335
+ const currentURL = this.page.url();
336
+ try {
337
+ const response = await axios.get(currentURL);
338
+ const status = response.status;
339
+ if (notCase) {
340
+ assert.notStrictEqual(status, parseInt(expectedStatusCode), `Status code should NOT be ${expectedStatusCode}`);
341
+ } else {
342
+ assert.strictEqual(status, parseInt(expectedStatusCode), `Expected status ${expectedStatusCode} but got ${status}`);
343
+ }
344
+ } catch (error) {
345
+ const status = error.response ? error.response.status : null;
346
+ if (notCase) {
347
+ if (status !== null) assert.notStrictEqual(status, parseInt(expectedStatusCode));
348
+ } else {
349
+ assert.strictEqual(status, parseInt(expectedStatusCode), `Expected status ${expectedStatusCode} but got ${status}`);
350
+ }
351
+ }
352
+ });
@@ -0,0 +1,124 @@
1
+ 'use strict';
2
+
3
+ // Authentication-state helpers built on Playwright's `storageState` API.
4
+ //
5
+ // Save the cookies + localStorage of an authenticated context to a JSON file
6
+ // once, then restore that snapshot in later scenarios so each test does not
7
+ // have to walk through the login UI. This is the single biggest speedup
8
+ // available for suites that touch authenticated pages — typical savings of
9
+ // 1-3 seconds per scenario.
10
+ //
11
+ // Recommended layout:
12
+ //
13
+ // tests/auth/admin.json
14
+ // tests/auth/editor.json
15
+ // tests/auth/customer.json
16
+ //
17
+ // Recommended setup feature: tag a one-shot scenario `@auth-setup`, run it
18
+ // once via `npx cucumber-js --tags @auth-setup` after every credential
19
+ // rotation, and let everyday scenarios restore the snapshot.
20
+
21
+ const { Given, When } = require('@cucumber/cucumber');
22
+ const path = require('path');
23
+ const fs = require('fs');
24
+
25
+ function resolveStoragePath(p) {
26
+ return path.isAbsolute(p) ? p : path.join(process.cwd(), p);
27
+ }
28
+
29
+ /**
30
+ * Save the current browser context's cookies + localStorage to a JSON file.
31
+ *
32
+ * Run this AFTER a successful interactive login. The destination file is
33
+ * created (with parent directories) if it does not exist; existing files are
34
+ * overwritten.
35
+ *
36
+ * Example #1: When I save the auth state to "tests/auth/admin.json"
37
+ * Example #2: Given I am on "/login"
38
+ * When I fill in "admin@example.com" for "Email"
39
+ * And I fill in "secret" for "Password"
40
+ * And I press "Sign in"
41
+ * And I wait until the URL contains "/dashboard"
42
+ * Then I save the auth state to "tests/auth/admin.json"
43
+ * Example #3: When I save the auth state to "tests/auth/editor.json"
44
+ * Example #4: When we save the auth state to "tests/auth/customer.json"
45
+ * Example #5: When I save the auth state to "/tmp/admin-state.json"
46
+ *
47
+ */
48
+ When(/^(I |we )*save the auth state to "([^"]*)"$/, async function (pronoun, target) {
49
+ const file = resolveStoragePath(target);
50
+ fs.mkdirSync(path.dirname(file), { recursive: true });
51
+ await this.context.storageState({ path: file });
52
+ });
53
+
54
+ /**
55
+ * Restore cookies + localStorage from a previously saved JSON file.
56
+ *
57
+ * The current browser context is closed and a fresh one is opened with the
58
+ * saved state. The webship-js init script (AJAX/timer/mutation tracker) is
59
+ * re-installed automatically so smart waits keep working. Subsequent steps
60
+ * proceed against the restored, authenticated session.
61
+ *
62
+ * Example #1: Given I restore the auth state from "tests/auth/admin.json"
63
+ * Example #2: Given I restore the auth state from "tests/auth/editor.json"
64
+ * And I am on "/admin/products"
65
+ * Example #3: Given I restore the auth state from "tests/auth/customer.json"
66
+ * And I am on "/account/orders"
67
+ * Example #4: Given we restore the auth state from "tests/auth/admin.json"
68
+ * Example #5: Given I restore the auth state from "tests/auth/admin.json"
69
+ * And I am on "/dashboard"
70
+ * Then "<#user-list>" should have a count of 5 within 5 seconds
71
+ *
72
+ */
73
+ Given(/^(I |we )*restore the auth state from "([^"]*)"$/, async function (pronoun, source) {
74
+ const file = resolveStoragePath(source);
75
+ if (!fs.existsSync(file)) {
76
+ throw new Error(`Auth state file not found: ${file}`);
77
+ }
78
+ const playwrightConfig = require(path.join(process.cwd(), 'playwright.config'));
79
+ const newContext = await this.playwrightBrowser.newContext({
80
+ ...playwrightConfig.contextOptions,
81
+ storageState: file,
82
+ });
83
+ await newContext.addInitScript(() => {
84
+ if (window.__webshipAjaxInstalled) return;
85
+ window.__webshipAjaxInstalled = true;
86
+ window.__webshipAjaxCount = 0;
87
+ window.__webshipPendingTimers = 0;
88
+ window.__webshipLastMutation = Date.now();
89
+ });
90
+ if (this.context) await this.context.close();
91
+ this.context = newContext;
92
+ this.page = await this.context.newPage();
93
+ });
94
+
95
+ /**
96
+ * Clear cookies and localStorage / sessionStorage for the current context.
97
+ *
98
+ * Use to anonymize a session mid-scenario, e.g. after asserting a logged-in
99
+ * action you may want to verify the same path returns 302 / login form for
100
+ * an anonymous visitor.
101
+ *
102
+ * Example #1: Given I clear the auth state
103
+ * Example #2: Given I restore the auth state from "tests/auth/admin.json"
104
+ * And I am on "/dashboard"
105
+ * Given I clear the auth state
106
+ * When I am on "/dashboard"
107
+ * Then I should see "Sign in"
108
+ * Example #3: Given we clear the auth state
109
+ * Example #4: When I press "Logout"
110
+ * And I clear the auth state
111
+ * Example #5: Given I clear the auth state
112
+ * When I am on the homepage
113
+ * Then I should see "Login"
114
+ *
115
+ */
116
+ Given(/^(I |we )*clear the auth state$/, async function () {
117
+ await this.context.clearCookies();
118
+ try {
119
+ await this.page.evaluate(() => {
120
+ try { localStorage.clear(); } catch { /* no-op */ }
121
+ try { sessionStorage.clear(); } catch { /* no-op */ }
122
+ });
123
+ } catch { /* page may not be on a real URL yet */ }
124
+ });
@@ -0,0 +1,128 @@
1
+ 'use strict';
2
+
3
+ // Clock / time-mocking steps backed by Playwright's `page.clock` API.
4
+ //
5
+ // Useful for testing relative-time UIs ("5 minutes ago"), debounced inputs,
6
+ // throttled re-renders, scheduled UI changes (toast auto-dismiss, session
7
+ // timeout), and any flow gated on `Date.now()` or `setTimeout`.
8
+ //
9
+ // Once the fake clock is installed, page-level `Date.now()` and `new Date()`
10
+ // return the fake time, and pending timers stay paused until explicitly
11
+ // advanced.
12
+
13
+ const { Given, When } = require('@cucumber/cucumber');
14
+
15
+ /**
16
+ * Install a fake clock anchored at an ISO 8601 instant.
17
+ *
18
+ * After this step, `Date.now()` inside the page returns the fake time and
19
+ * `setTimeout` / `setInterval` callbacks queue but do not fire until you
20
+ * advance the clock.
21
+ *
22
+ * Example #1: Given the system time is "2026-05-08T10:00:00Z"
23
+ * Example #2: Given the system time is "2026-01-01T00:00:00Z"
24
+ * And I am on "/feed"
25
+ * Example #3: Given the system time is "2026-12-31T23:59:55Z"
26
+ * And I am on "/countdown"
27
+ * Example #4: Given the system time is "2026-05-08T10:00:00Z"
28
+ * And I am on "/feed"
29
+ * And "<.timestamp>" should have text "just now"
30
+ * Example #5: Given the system time is "2026-07-04T12:00:00-04:00"
31
+ * And I am on "/holiday-banner"
32
+ *
33
+ */
34
+ Given(/^the system time is "([^"]*)"$/, async function (iso) {
35
+ await this.page.clock.install({ time: new Date(iso) });
36
+ });
37
+
38
+ /**
39
+ * Advance the fake clock forward by N milliseconds, firing every queued
40
+ * `setTimeout` / `setInterval` callback scheduled within that interval.
41
+ *
42
+ * Example #1: When I advance the clock by 500 ms
43
+ * Example #2: When I advance the clock by 1500 ms
44
+ * Example #3: When we advance the clock by 250 ms
45
+ * Example #4: And I advance the clock by 100 ms
46
+ * Example #5: When I advance the clock by 60000 ms
47
+ *
48
+ */
49
+ When(/^(I |we )*advance the clock by (\d+) ?ms$/, async function (pronoun, ms) {
50
+ await this.page.clock.runFor(parseInt(ms, 10));
51
+ });
52
+
53
+ /**
54
+ * Advance the fake clock forward by N seconds.
55
+ *
56
+ * Example #1: When I advance the clock by 30 seconds
57
+ * Example #2: When I advance the clock by 5 seconds
58
+ * Example #3: When we advance the clock by 1 second
59
+ * Example #4: And I advance the clock by 10 seconds
60
+ * Example #5: When I advance the clock by 90 seconds
61
+ *
62
+ */
63
+ When(/^(I |we )*advance the clock by (\d+) seconds?$/, async function (pronoun, seconds) {
64
+ await this.page.clock.runFor(parseInt(seconds, 10) * 1000);
65
+ });
66
+
67
+ /**
68
+ * Advance the fake clock forward by N minutes.
69
+ *
70
+ * Example #1: When I advance the clock by 5 minutes
71
+ * Example #2: When I advance the clock by 1 minute
72
+ * Example #3: When we advance the clock by 14 minutes
73
+ * Example #4: And I advance the clock by 30 minutes
74
+ * Example #5: When I advance the clock by 60 minutes
75
+ *
76
+ */
77
+ When(/^(I |we )*advance the clock by (\d+) minutes?$/, async function (pronoun, minutes) {
78
+ await this.page.clock.runFor(parseInt(minutes, 10) * 60 * 1000);
79
+ });
80
+
81
+ /**
82
+ * Pause the fake clock — no further timer callbacks fire until resumed or
83
+ * explicitly advanced. Useful between actions when you do not want a long
84
+ * tick to fire mid-step.
85
+ *
86
+ * Example #1: When I pause the clock
87
+ * Example #2: Given the system time is "2026-05-08T10:00:00Z"
88
+ * When I pause the clock
89
+ * Example #3: When we pause the clock
90
+ * Example #4: And I pause the clock
91
+ * Example #5: When I pause the clock
92
+ * Then "<.timer>" should have text "00:00"
93
+ *
94
+ */
95
+ When(/^(I |we )*pause the clock$/, async function () {
96
+ await this.page.clock.pauseAt(await this.page.evaluate(() => Date.now()));
97
+ });
98
+
99
+ /**
100
+ * Resume the fake clock from the current paused time.
101
+ *
102
+ * Example #1: When I resume the clock
103
+ * Example #2: When I pause the clock
104
+ * And I resume the clock
105
+ * Example #3: When we resume the clock
106
+ * Example #4: And I resume the clock
107
+ * Example #5: When I resume the clock
108
+ * And I advance the clock by 5 seconds
109
+ *
110
+ */
111
+ When(/^(I |we )*resume the clock$/, async function () {
112
+ await this.page.clock.resume();
113
+ });
114
+
115
+ /**
116
+ * Set the fake clock to a specific time WITHOUT advancing through it. Use
117
+ * `advance` if you want pending timers in the gap to fire.
118
+ *
119
+ * Example #1: When I set the system time to "2026-05-08T12:30:00Z"
120
+ * Example #2: When I set the system time to "2026-12-31T23:59:55Z"
121
+ * Example #3: When we set the system time to "2026-01-01T00:00:00Z"
122
+ * Example #4: And I set the system time to "2026-07-04T08:00:00-04:00"
123
+ * Example #5: When I set the system time to "2027-01-01T00:00:00Z"
124
+ *
125
+ */
126
+ When(/^(I |we )*set the system time to "([^"]*)"$/, async function (pronoun, iso) {
127
+ await this.page.clock.setSystemTime(new Date(iso));
128
+ });