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,255 @@
1
+ # Recipes Cookbook
2
+
3
+ 20 paste-and-go scenarios covering the most common testing needs. Drop
4
+ them straight into a `.feature` file, swap selectors / text for your
5
+ app, run.
6
+
7
+ ---
8
+
9
+ ## 1. Sign in (happy path)
10
+
11
+ ```gherkin
12
+ Scenario: Sign in with valid credentials
13
+ Given I am on "/login"
14
+ When I fill in "Email" with "alice@example.com"
15
+ And I fill in "Password" with "s3cret"
16
+ And I press "Sign in"
17
+ Then I should see "Dashboard"
18
+ ```
19
+
20
+ ## 2. Sign in (validation error)
21
+
22
+ ```gherkin
23
+ Scenario: Sign in fails with empty password
24
+ Given I am on "/login"
25
+ When I fill in "Email" with "alice@example.com"
26
+ And I press "Sign in"
27
+ Then I should see "Password is required"
28
+ And I should be on "/login"
29
+ ```
30
+
31
+ ## 3. Sign up with required fields
32
+
33
+ ```gherkin
34
+ Scenario: Sign up
35
+ Given I am on "/signup"
36
+ When I fill in the following:
37
+ | Name | Alice |
38
+ | Email | alice@example.com |
39
+ | Password | s3cret |
40
+ And I check "I agree to terms"
41
+ And I press "Create account"
42
+ Then I should see "Welcome, Alice"
43
+ ```
44
+
45
+ ## 4. Search
46
+
47
+ ```gherkin
48
+ Scenario: Find a product by keyword
49
+ Given I am on the homepage
50
+ When I fill in "Search" with "laptop"
51
+ And I press the key "Enter"
52
+ Then ".product-card" should have a count of 12 within 5 seconds
53
+ And I should see "Results for \"laptop\""
54
+ ```
55
+
56
+ ## 5. Logout
57
+
58
+ ```gherkin
59
+ Scenario: Logout returns to homepage
60
+ Given I restore the auth state from "tests/auth/admin.json"
61
+ And I am on "/dashboard"
62
+ When I click "Sign out"
63
+ Then I should be on the homepage
64
+ And I should see "Sign in"
65
+ ```
66
+
67
+ ## 6. Add to cart
68
+
69
+ ```gherkin
70
+ Scenario: Add a product to cart
71
+ Given I am on "/products/laptop-pro"
72
+ When I press "Add to cart"
73
+ And I follow "View cart"
74
+ Then I should see "Laptop Pro" in the "Cart" element
75
+ And the URL should match "/cart"
76
+ ```
77
+
78
+ ## 7. Modal open + close
79
+
80
+ ```gherkin
81
+ Scenario: Open and close the help modal
82
+ Given I am on the homepage
83
+ When I click "Help"
84
+ And I wait for the modal to appear
85
+ Then I should see "How can we help?" in the modal
86
+ When I close the modal
87
+ Then I should not see the modal
88
+ ```
89
+
90
+ ## 8. Native confirm dialog
91
+
92
+ ```gherkin
93
+ Scenario: Confirm deletion
94
+ Given I am on "/admin/users"
95
+ And I will accept the next dialog
96
+ When I click "Delete" in the "alice@example.com" row
97
+ Then the last dialog message should contain "delete"
98
+ And I should see "User removed"
99
+ ```
100
+
101
+ ## 9. Pagination
102
+
103
+ ```gherkin
104
+ Scenario: Navigate to second page of results
105
+ Given I am on "/blog"
106
+ When I follow "Next"
107
+ Then current url should have the "page" parameter with the "2" value
108
+ And ".post" should have a count of 10
109
+ ```
110
+
111
+ ## 10. Sortable table
112
+
113
+ ```gherkin
114
+ Scenario: Sort orders by total descending
115
+ Given I restore the auth state from "tests/auth/admin.json"
116
+ And I am on "/admin/orders"
117
+ When I click "Total"
118
+ And I click "Total"
119
+ Then the table "#orders" should be sorted by "Total" in "descending" order
120
+ ```
121
+
122
+ ## 11. Form file upload
123
+
124
+ ```gherkin
125
+ Scenario: Upload a profile photo
126
+ Given I restore the auth state from "tests/auth/customer.json"
127
+ And I am on "/account"
128
+ When I attach the file "avatar.png" to "#avatar"
129
+ And I press "Save"
130
+ Then I should see "Avatar updated"
131
+ ```
132
+
133
+ ## 12. API mock + UI assertion
134
+
135
+ ```gherkin
136
+ Scenario: Dashboard renders mocked user list
137
+ Given the URL "**/api/users" returns the JSON:
138
+ """
139
+ {"users": [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]}
140
+ """
141
+ When I am on "/users"
142
+ Then ".user" should have a count of 2 within 5 seconds
143
+ And I should see "Alice"
144
+ And I should see "Bob"
145
+ ```
146
+
147
+ ## 13. Block third-party tracking
148
+
149
+ ```gherkin
150
+ Scenario: Page renders without tracking scripts
151
+ Given the URL "**/google-analytics.com/**" is blocked
152
+ And I start recording network requests
153
+ When I am on the homepage
154
+ Then no request to "**/google-analytics.com/**" should have been made
155
+ ```
156
+
157
+ ## 14. Mobile viewport smoke
158
+
159
+ ```gherkin
160
+ Scenario: Mobile menu collapses
161
+ Given I am on the homepage
162
+ When I set the viewport to the "mobile" breakpoint
163
+ Then "<nav .mobile-toggle>" should be visible
164
+ And "<nav .desktop-menu>" should not be visible
165
+ ```
166
+
167
+ ## 15. Accessibility AA gate
168
+
169
+ ```gherkin
170
+ @a11y
171
+ Scenario: Page meets WCAG 2.1 AA
172
+ Given I am on "/checkout"
173
+ Then the page should pass an accessibility audit at level "AA"
174
+ And the page should have a title
175
+ And user zoom should be allowed
176
+ ```
177
+
178
+ ## 16. Keyboard navigation
179
+
180
+ ```gherkin
181
+ Scenario: Tab order is correct on the login form
182
+ Given I am on "/login"
183
+ And I focus on the element "body"
184
+ When I press the key "Tab"
185
+ Then the focused element should match "#email"
186
+ When I press the key "Tab"
187
+ Then the focused element should match "#password"
188
+ When I press the key "Tab"
189
+ Then the focused element should match "button[type=submit]"
190
+ ```
191
+
192
+ ## 17. SPA navigation without full reload
193
+
194
+ ```gherkin
195
+ Scenario: SPA route changes without full page load
196
+ Given I am on the homepage
197
+ When I follow "Pricing"
198
+ And I wait until the URL contains "/pricing"
199
+ Then I should see "Plans"
200
+ And the page should have exactly one h1
201
+ ```
202
+
203
+ ## 18. Wait for AJAX-loaded content
204
+
205
+ ```gherkin
206
+ Scenario: Live search returns results
207
+ Given I am on "/search"
208
+ When I fill in "Search" with "laptops"
209
+ Then I wait until at least 1 element matches ".result"
210
+ And I should see "results"
211
+ ```
212
+
213
+ ## 19. JSON-API response check
214
+
215
+ ```gherkin
216
+ Scenario: Health endpoint returns OK
217
+ When I send a GET request to "/api/health"
218
+ Then the API response code should be 200
219
+ And the JSON property "status" should be "ok"
220
+ ```
221
+
222
+ ## 20. End-to-end checkout (composite)
223
+
224
+ ```gherkin
225
+ Scenario: Customer completes checkout
226
+ Given I restore the auth state from "tests/auth/customer.json"
227
+ And I am on "/products/laptop-pro"
228
+ When I press "Add to cart"
229
+ And I follow "Checkout"
230
+ And I fill in the following:
231
+ | Card number | 4242 4242 4242 4242 |
232
+ | Expiry | 12/30 |
233
+ | CVV | 123 |
234
+ And I press "Place order"
235
+ And I wait until the URL contains "/orders/"
236
+ Then I should see "Order confirmed"
237
+ And I send a GET request to "/api/orders?latest=1"
238
+ And the API response code should be 200
239
+ And the JSON property "orders.0.status" should be "Pending"
240
+ ```
241
+
242
+ ---
243
+
244
+ ## How to adapt these
245
+
246
+ 1. Find the scenario closest to your goal.
247
+ 2. Swap selectors (`#email`, `.product-card`, …) for your real ones.
248
+ 3. Swap text labels (`"Sign in"`, `"Add to cart"`) for your real copy.
249
+ 4. Run. Fix any red. Iterate.
250
+
251
+ If you find yourself rewriting the same setup three times, extract it
252
+ into a `Background:` block. If you find yourself rewriting the same
253
+ selector three times, register it in `tests/selectors/your-app.json`.
254
+
255
+ That's the entire cookbook.
@@ -0,0 +1,76 @@
1
+ # Tag Conventions
2
+
3
+ Tags drive what runs in CI, what gets retried, what's currently broken.
4
+ Keep them consistent across the suite.
5
+
6
+ ## Standard tags
7
+
8
+ | Tag | Meaning |
9
+ | --- | --- |
10
+ | `@critical` | Must pass on every PR. Smoke set. Run with `--tags "@critical"` first in CI. |
11
+ | `@smoke` | Synonym for `@critical` when feature owners prefer it. Pick one and stick with it. |
12
+ | `@auth` | Touches authentication / sessions. |
13
+ | `@security` | Asserts a Safeguard (CSRF, rate limit, token expiry). |
14
+ | `@a11y` | Accessibility check (axe-core, focus order, ARIA). Run with `--tags "@a11y"` to gate the a11y suite. |
15
+ | `@i18n` | Multi-locale check (Arabic / RTL / French / etc). |
16
+ | `@perf` | Performance budget (page load, request count). |
17
+ | `@flaky` | Known-unstable. CI retries it once via `--retry` + `--retryTagFilter "@flaky"`. **Never** ship long-term `@flaky` — fix the root cause. |
18
+ | `@wip` | Work in progress. CI excludes with `--tags "not @wip"`. |
19
+ | `@desktop` / `@mobile` | Viewport-locked variants. |
20
+ | `@external` | Hits a third-party service. Skip in offline test runs. |
21
+ | `@auth-setup` | One-shot scenarios that produce auth state files. Run manually after credential rotation. |
22
+
23
+ ## How to apply
24
+
25
+ Tags go on `Feature:` (apply to every scenario) or on a single
26
+ `Scenario:`.
27
+
28
+ ```gherkin
29
+ @auth
30
+ Feature: Sign in
31
+
32
+ @critical
33
+ Scenario: Successful login
34
+ Given I am on "/login"
35
+ ...
36
+
37
+ @flaky
38
+ Scenario: Concurrent login from two devices
39
+ ...
40
+
41
+ @wip
42
+ Scenario: Sign in with Apple
43
+ ...
44
+ ```
45
+
46
+ ## Recommended CI lanes
47
+
48
+ ```bash
49
+ # Smoke gate — every PR.
50
+ npx cucumber-js --tags "@critical and not @wip"
51
+
52
+ # Full suite — main branch / nightly.
53
+ npx cucumber-js --tags "not @wip and not @auth-setup"
54
+
55
+ # Accessibility lane.
56
+ npx cucumber-js --tags "@a11y"
57
+
58
+ # Flaky lane — separate report, allowed to fail without blocking.
59
+ npx cucumber-js --tags "@flaky" --retry 2
60
+
61
+ # Pre-release security gate.
62
+ npx cucumber-js --tags "@security or @auth"
63
+ ```
64
+
65
+ ## Tag hygiene rules
66
+
67
+ 1. **No `@skip`.** If a scenario should not run, fix it or delete it.
68
+ `@wip` is a temporary excuse, not a bin.
69
+ 2. **`@flaky` is a debt marker.** Each `@flaky` should have an open
70
+ issue. Removing the tag is part of the fix.
71
+ 3. **Don't tag what's obvious.** Every scenario in `auth.feature`
72
+ doesn't need `@auth` — tag the file.
73
+ 4. **One source of truth.** Don't invent project-specific synonyms
74
+ (`@blocker`, `@must-pass`, `@p0`). Pick `@critical` and stick with it.
75
+ 5. **Document custom tags.** If your project needs a tag not in this
76
+ list, add a row to this page.
@@ -0,0 +1,36 @@
1
+
2
+ # Then I save fullscreen screenshot
3
+
4
+ ## Step Definition
5
+
6
+ ```
7
+ Then (I |we )*save fullscreen screenshot
8
+ ```
9
+
10
+ ## Description
11
+
12
+ "Save a full-page screenshot (entire scrollable area)."
13
+
14
+ ## Examples
15
+
16
+ **Example #1:**
17
+ ```
18
+ Then I save fullscreen screenshot
19
+ ```
20
+
21
+ **Example #2:**
22
+ ```
23
+ Then save fullscreen screenshot
24
+ ```
25
+
26
+ **Example #3:**
27
+ ```
28
+ Given I am on "/news"
29
+ Then I save fullscreen screenshot
30
+ ```
31
+
32
+ **Example #4:**
33
+ ```
34
+ Given we are on homepage
35
+ Then we save fullscreen screenshot
36
+ ```
@@ -0,0 +1,34 @@
1
+
2
+ # Then I save "width" x "height" screenshot
3
+
4
+ ## Description
5
+ Resize the viewport to specified dimensions and capture a screenshot.
6
+
7
+ ## Gherkin Syntax
8
+ ```
9
+ Then (I |we )*save (\d+) x (\d+) screenshot
10
+ ```
11
+
12
+ ## Examples
13
+
14
+ **Example #1:**
15
+ ```
16
+ Then I save 1440 x 900 screenshot
17
+ ```
18
+
19
+ **Example #2:**
20
+ ```
21
+ Then we save 1200 x 800 screenshot
22
+ ```
23
+
24
+ **Example #3:**
25
+ ```
26
+ Given I am on "/about-us"
27
+ Then I save 1440 x 900 screenshot
28
+ ```
29
+
30
+ ## Parameters
31
+ - First numeric parameter: viewport width (in pixels)
32
+ - Second numeric parameter: viewport height (in pixels)
33
+
34
+ The step adjusts the browser window to the specified dimensions before capturing the screenshot.
@@ -0,0 +1,45 @@
1
+
2
+ # When I save screenshot with name "filename"
3
+
4
+ ## Description
5
+ Save a screenshot using an explicit filename (tokens supported).
6
+
7
+ ## Gherkin Step Syntax
8
+ ```
9
+ When (I |we )*save screenshot with name "([^"]*)"
10
+ ```
11
+
12
+ ## Examples
13
+
14
+ **Example #1:**
15
+ ```
16
+ When I save screenshot with name "homepage.png"
17
+ ```
18
+
19
+ **Example #2:**
20
+ ```
21
+ When we save screenshot with name "webship-home"
22
+ ```
23
+
24
+ **Example #3:**
25
+ ```
26
+ When save screenshot with name "un-landing-{datetime}.png"
27
+ ```
28
+
29
+ **Example #4:**
30
+ ```
31
+ Given I am on "/news"
32
+ When I save screenshot with name "news-latest.png"
33
+ ```
34
+
35
+ **Example #5:**
36
+ ```
37
+ Given I am on "/un.org"
38
+ When I save screenshot with name "un-home.png"
39
+ ```
40
+
41
+ ## Key Features
42
+ - Supports explicit filename specification
43
+ - Allows optional "I" or "we" pronouns
44
+ - Supports token substitution (e.g., `{datetime}`)
45
+ - Flexible filename formats (with or without extensions)
@@ -0,0 +1,52 @@
1
+
2
+ # Advanced Screenshots
3
+
4
+ ## Overview
5
+
6
+ This documentation page covers screenshot capture functionality in Webship JS 2.0.x. The feature enables testers to capture PNG screenshots during Cucumber scenarios using Playwright, supporting fullscreen, custom viewport, and named captures.
7
+
8
+ ## Key Features
9
+
10
+ **Auto-capture hooks** activate screenshots in two scenarios:
11
+ - On failed steps (with `failedPrefix` prepended)
12
+ - On every step when scenarios are tagged `@screenshots`
13
+
14
+ **Filename tokens** can be used in `with name "..."` steps or configuration keys like `filenamePattern` and `filenamePatternFailed`.
15
+
16
+ ## Configuration
17
+
18
+ Settings reside in `cucumber.js` under `worldParameters.screenshot`. Each key accepts environment variable overrides:
19
+
20
+ ```javascript
21
+ worldParameters: {
22
+ screenshot: {
23
+ dir: './screenshots',
24
+ purge: false,
25
+ onFailed: true,
26
+ onEveryStep: false,
27
+ alwaysFullscreen: false,
28
+ failedPrefix: 'failed_',
29
+ filenamePattern: '{datetime}.{feature_file}.feature_{step_line}.{ext}',
30
+ filenamePatternFailed: '{failed_prefix}{datetime}.{feature_file}.feature_{step_line}.{ext}',
31
+ infoTypes: '',
32
+ },
33
+ }
34
+ ```
35
+
36
+ ## Priority Chain
37
+
38
+ 1. Environment variables (`WEBSHIP_SCREENSHOT_*`)
39
+ 2. cucumber.js project defaults
40
+ 3. Built-in defaults
41
+
42
+ ## Output
43
+
44
+ Each capture generates two files:
45
+ - `.png` — Screenshot via Playwright
46
+ - `.html` — Raw page HTML with optional metadata
47
+
48
+ ## Sub-pages
49
+
50
+ - [Then I save "width" x "height" screenshot](/docs/webship-js/2.0.x/advanced-screenshots/then-i-save-width-x-height-screenshot)
51
+ - [Then I save fullscreen screenshot](/docs/webship-js/2.0.x/advanced-screenshots/then-i-save-fullscreen-screenshot)
52
+ - [When I save screenshot with name "filename"](/docs/webship-js/2.0.x/advanced-screenshots/when-i-save-screenshot-name-filename)
@@ -0,0 +1,18 @@
1
+
2
+ # Advanced Selectors
3
+
4
+ ## Overview
5
+
6
+ This documentation page describes a unified selector system for Webship-JS 2.0.x that consolidates CSS selectors, XPath selectors, layout components, viewport breakpoints, and relative-position assertions into a single module.
7
+
8
+ ## Key Features
9
+
10
+ The advanced selectors system unifies multiple selector types through these capabilities:
11
+
12
+ - **Unified Resolution**: Combines CSS and XPath selectors with consistent priority ordering where "css → xpath" applies, with latest registration overriding previous entries for identical names.
13
+
14
+ - **Auto-Retrying Assertions**: Replaces manual visibility checks with "Playwright's auto-retrying wait states" rather than legacy DOM inspection methods.
15
+
16
+ - **Accessibility-First Locators**: Leverages Playwright semantic helpers like `getByLabel`, `getByPlaceholder`, and `getByRole()` chained via `.or()` to match user interaction patterns.
17
+
18
+ - **Standardized Breakpoints**: Implements xs/sm/md/lg/xl/xxl/xxxl viewport scales aligned with Bootstrap 5.3 conventions.
@@ -0,0 +1,45 @@
1
+
2
+ # API Step Definitions
3
+
4
+ ## Overview
5
+
6
+ webship-js ships native HTTP / REST API step definitions powered by
7
+ Playwright's request fixture and `axios`. They share the browser
8
+ context's cookie jar so the same scenario can mix UI actions and
9
+ direct API calls.
10
+
11
+ ## Available API Step Definitions
12
+
13
+ The documentation lists 22 distinct step definition categories:
14
+
15
+ **Authentication & Headers:**
16
+ - Given I am authenticating as "username" with "pa$$word" password
17
+ - Given I set header "Header-Name" with value "Some-Value"
18
+ - Given I set the following headers
19
+ - Given I set the header "Header-Name" to "Header-Value"
20
+
21
+ **Request Configuration:**
22
+ - Given I set placeholder "{{placeholder}}" to "value"
23
+ - Given I set the request body to 'JSON-data'
24
+ - Given I set the request body with
25
+ - Given the API base URL is "url"
26
+
27
+ **HTTP Methods:**
28
+ - When I send a METHOD request to "endpoint"
29
+ - When I send a METHOD request to "endpoint" with body
30
+ - When I send a METHOD request to "endpoint" with form data
31
+ - When I send a METHOD request to "endpoint" with values
32
+
33
+ **Response Assertions:**
34
+ - Then print API response
35
+ - Then the API response code should be {number}
36
+ - Then the API response should contain "text"
37
+ - Then the API response should contain json
38
+ - Then the API response should not contain "text"
39
+ - Then the response should be valid JSON
40
+ - Then the response header "response header" should be "value"
41
+
42
+ **JSON Response Validation:**
43
+ - Then the JSON response should have "propertyPath" equal to "value"
44
+ - Then the JSON response should have property "propertyPath"
45
+ - Then the JSON response should not have property "propertyPath"
@@ -0,0 +1,30 @@
1
+
2
+ # Then compare diffy "ENV1" with "ENV2"
3
+
4
+ ## Description
5
+
6
+ This step initiates a Diffy comparison between two project environments. When either environment is specified as "custom", the step uses the `DIFFY_ENV1_URL` and `DIFFY_ENV2_URL` environment variables.
7
+
8
+ ## Gherkin Step Pattern
9
+
10
+ ```
11
+ Then (I |we )*compare diffy "([^"]*)" with "([^"]*)"
12
+ ```
13
+
14
+ ## Examples
15
+
16
+ ```
17
+ Then compare diffy "prod" with "stage"
18
+ Then compare diffy "production" with "staging"
19
+ Then compare diffy "prod" with "dev"
20
+ Then compare diffy "stage" with "dev"
21
+ Then compare diffy "prod" with "baseline"
22
+ Then compare diffy "baseline" with "custom"
23
+ Then compare diffy "custom" with "custom"
24
+ Then compare diffy "production" with "development"
25
+ ```
26
+
27
+ ## Parameters
28
+
29
+ - **First Environment**: The initial environment name for comparison
30
+ - **Second Environment**: The environment to compare against (uses custom URLs when "custom" is specified)
@@ -0,0 +1,21 @@
1
+
2
+ # Then create diffy comparison with name "value"
3
+
4
+ ## Description
5
+ This step definition creates a named Diffy comparison using the last two uploaded snapshots.
6
+
7
+ ## Gherkin Pattern
8
+ ```
9
+ Then (I |we )*create diffy comparison with name "([^"]*)"
10
+ ```
11
+
12
+ ## Examples
13
+ - `Then create diffy comparison with name "release-2.0"`
14
+ - `Then create diffy comparison with name "nightly"`
15
+ - `Then create diffy comparison with name "smoke-run-42"`
16
+ - `Then create diffy comparison with name "webship.co-regression"`
17
+ - `Then create diffy comparison with name "before-vs-after"`
18
+ - `Then create diffy comparison with name "homepage-baseline-vs-changed"`
19
+
20
+ ## Parameters
21
+ The step accepts a single parameter: a string value representing the name for the comparison being created.
@@ -0,0 +1,25 @@
1
+
2
+ # Then create diffy comparison
3
+
4
+ ## Description
5
+ This step generates a Diffy comparison (visual diff) by utilizing the two most recently uploaded snapshots.
6
+
7
+ ## Gherkin Syntax
8
+ ```gherkin
9
+ Then (I |we )*create diffy comparison
10
+ ```
11
+
12
+ ## Usage Examples
13
+ The step accepts several grammatical variations:
14
+
15
+ ```gherkin
16
+ Then create diffy comparison
17
+ And create diffy comparison
18
+ Then I create diffy comparison
19
+ Then we create diffy comparison
20
+ And I create diffy comparison
21
+ And we create diffy comparison
22
+ ```
23
+
24
+ ## Purpose
25
+ Creates a visual comparison report from the last pair of snapshots that were uploaded to Diffy, allowing teams to identify visual regressions between environments or versions.
@@ -0,0 +1,35 @@
1
+
2
+ # Then create diffy screenshot from "environment name" environment
3
+
4
+ ## Overview
5
+
6
+ This Webship JS step definition instructs Diffy to capture a snapshot remotely from a specified environment within your project. The step accepts both abbreviated and full environment names, including custom environments.
7
+
8
+ ## Gherkin Step Pattern
9
+
10
+ ```
11
+ Then (I |we )*create diffy screenshot from "([^"]*)" environment
12
+ ```
13
+
14
+ ## Description
15
+
16
+ "Ask Diffy to capture a snapshot remotely from a named environment on the project. Accepts short (prod/stage/dev) or long (production/staging/development) forms, plus 'custom'."
17
+
18
+ ## Examples
19
+
20
+ ```gherkin
21
+ Then create diffy screenshot from "production" environment
22
+ Then create diffy screenshot from "prod" environment
23
+ Then create diffy screenshot from "staging" environment
24
+ Then create diffy screenshot from "stage" environment
25
+ Then create diffy screenshot from "development" environment
26
+ Then create diffy screenshot from "dev" environment
27
+ Then create diffy screenshot from "custom" environment
28
+ ```
29
+
30
+ ## Supported Environment Names
31
+
32
+ - **Production**: "production" or "prod"
33
+ - **Staging**: "staging" or "stage"
34
+ - **Development**: "development" or "dev"
35
+ - **Custom**: "custom" (for user-defined environments)