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.
- package/AGENTS.md +109 -0
- package/CLAUDE.md +317 -0
- package/bin/generate-reports.js +363 -0
- package/bin/init-webship.js +343 -0
- package/bin/postinstall.js +8 -74
- package/cucumber.js +66 -2
- package/docs/00-quick-start.md +102 -0
- package/docs/01-getting-started.md +102 -0
- package/docs/02-bbr-smart-waits.md +77 -0
- package/docs/03-selector-registry.md +95 -0
- package/docs/04-step-reference.md +728 -0
- package/docs/05-web-first-assertions.md +91 -0
- package/docs/06-network-and-dialogs.md +83 -0
- package/docs/07-auth-state.md +75 -0
- package/docs/08-clock-mocking.md +59 -0
- package/docs/09-api-testing.md +114 -0
- package/docs/10-accessibility.md +167 -0
- package/docs/11-debugging.md +129 -0
- package/docs/12-ai-agent-guide.md +338 -0
- package/docs/13-faq.md +236 -0
- package/docs/14-recipes-cookbook.md +255 -0
- package/docs/15-tag-conventions.md +76 -0
- package/docs/advanced-screenshots/then-i-save-fullscreen-screenshot.md +36 -0
- package/docs/advanced-screenshots/then-i-save-width-x-height-screenshot.md +34 -0
- package/docs/advanced-screenshots/when-i-save-screenshot-name-filename.md +45 -0
- package/docs/advanced-screenshots.md +52 -0
- package/docs/advanced-selectors.md +18 -0
- package/docs/api-step-definitions.md +45 -0
- package/docs/diffy-step-definitions/then-compare-diffy-env1-env2.md +30 -0
- package/docs/diffy-step-definitions/then-create-diffy-comparison-name-value.md +21 -0
- package/docs/diffy-step-definitions/then-create-diffy-comparison.md +25 -0
- package/docs/diffy-step-definitions/then-create-diffy-screenshot-environment-name.md +35 -0
- package/docs/diffy-step-definitions/then-i-take-screenshot.md +21 -0
- package/docs/diffy-step-definitions/then-i-take-screenshots-all-breakpoints.md +27 -0
- package/docs/diffy-step-definitions/then-send-screenshots-diffy-name-value.md +27 -0
- package/docs/diffy-step-definitions/then-upload-folder-url-diffy-snapshotname.md +28 -0
- package/docs/diffy-step-definitions/then-wait-diffy-comparison-complete.md +21 -0
- package/docs/diffy-step-definitions/when-i-resize-window-number.md +29 -0
- package/docs/diffy-step-definitions.md +21 -0
- package/docs/global-settings.md +244 -0
- package/docs/index.md +104 -0
- package/docs/install-webship-js/ddev-webship-js.md +52 -0
- package/docs/install-webship-js.md +35 -0
- package/docs/overview.md +41 -0
- package/docs/step-definitions/given-i-am-anonymous-user.md +67 -0
- package/docs/step-definitions/given-i-am-homepage.md +68 -0
- package/docs/step-definitions/given-i-am-specific-page.md +72 -0
- package/docs/step-definitions/then-i-should-be.md +56 -0
- package/docs/step-definitions/then-i-should-see.md +62 -0
- package/docs/step-definitions/then-item-checkbox.md +54 -0
- package/docs/step-definitions/then-item-link-should-contain-url.md +84 -0
- package/docs/step-definitions/then-item-should-contain.md +67 -0
- package/docs/step-definitions/then-radio-button-value-should-be-selected.md +68 -0
- package/docs/step-definitions/then-response-status-code-should-be-number.md +69 -0
- package/docs/step-definitions/then-value-radio-button-selected.md +62 -0
- package/docs/step-definitions/when-i-attach-file-file-name-element.md +71 -0
- package/docs/step-definitions/when-i-check-checkbox.md +60 -0
- package/docs/step-definitions/when-i-click-link.md +51 -0
- package/docs/step-definitions/when-i-click-operation-text-row.md +71 -0
- package/docs/step-definitions/when-i-fill.md +59 -0
- package/docs/step-definitions/when-i-go-homepage.md +60 -0
- package/docs/step-definitions/when-i-go-specific-page.md +67 -0
- package/docs/step-definitions/when-i-move-backward-one-page.md +49 -0
- package/docs/step-definitions/when-i-move-forward-one-page.md +58 -0
- package/docs/step-definitions/when-i-press-button.md +58 -0
- package/docs/step-definitions/when-i-reload-page.md +51 -0
- package/docs/step-definitions/when-i-scroll.md +73 -0
- package/docs/step-definitions/when-i-select-option-select-list.md +53 -0
- package/docs/step-definitions/when-i-select-radio-button-value.md +62 -0
- package/docs/step-definitions/when-i-uncheck-checkbox.md +57 -0
- package/docs/step-definitions/when-i-wait-ajax-finish.md +64 -0
- package/docs/step-definitions/when-i-wait.md +62 -0
- package/docs/step-definitions.md +50 -0
- package/examples/a11y.html +31 -0
- package/examples/cookies.html +10 -0
- package/examples/date.html +12 -0
- package/examples/diffy/baseline.html +54 -0
- package/examples/diffy/changed.html +63 -0
- package/examples/diffy/index.html +52 -0
- package/examples/element.html +11 -0
- package/examples/field.html +24 -0
- package/examples/index.html +6 -0
- package/examples/keyboard.html +11 -0
- package/examples/links.html +9 -0
- package/examples/modal.html +14 -0
- package/examples/path.html +3 -0
- package/examples/table.html +13 -0
- package/examples/test--when--i-additionally-select.html +27 -0
- package/package.json +19 -6
- package/playwright.config.ts +3 -2
- package/tests/features/a11y.feature +39 -0
- package/tests/features/cookie.feature +13 -0
- package/tests/features/date.feature +11 -0
- package/tests/features/diffy/test--diffy-01-example-demo.feature +22 -0
- package/tests/features/diffy/test--diffy-02-all-steps.feature +52 -0
- package/tests/features/diffy/test--diffy-03-real-api.feature +21 -0
- package/tests/features/element.feature +16 -0
- package/tests/features/field.feature +25 -0
- package/tests/features/keyboard.feature +10 -0
- package/tests/features/link.feature +11 -0
- package/tests/features/modal-advanced-example.feature +1 -1
- package/tests/features/modal.feature +11 -0
- package/tests/features/path.feature +16 -0
- package/tests/features/response.feature +8 -0
- package/tests/features/responsive.feature +10 -0
- package/tests/features/table.feature +18 -0
- package/tests/features/test--then--i-save-screenshot.feature +33 -0
- package/tests/features/test--then--i-see-locator.feature +320 -0
- package/tests/features/test--then--i-should-see-n-elements.feature +24 -0
- package/tests/features/test--then--print-current-url-and-response.feature +21 -0
- package/tests/features/test--when--i-additionally-select.feature +30 -0
- package/tests/features/test--when--i-follow.feature +22 -0
- package/tests/features/wait.feature +7 -0
- package/tests/features/yaml.feature +102 -0
- package/tests/reports/README.md +55 -0
- package/tests/selectors/_canonical-keys.json +113 -0
- package/tests/selectors/back-end-selectors.json +19 -0
- package/tests/selectors/cms-contentful-admin.json +35 -0
- package/tests/selectors/cms-craft-admin.json +39 -0
- package/tests/selectors/cms-drupal-cms-gin.json +56 -0
- package/tests/selectors/cms-drupal-core-claro.json +50 -0
- package/tests/selectors/cms-generic-admin.json +34 -0
- package/tests/selectors/cms-ghost-admin.json +34 -0
- package/tests/selectors/cms-joomla-admin.json +41 -0
- package/tests/selectors/cms-magento2-admin.json +32 -0
- package/tests/selectors/cms-prestashop-admin.json +38 -0
- package/tests/selectors/cms-shopify-admin.json +25 -0
- package/tests/selectors/cms-strapi-admin.json +42 -0
- package/tests/selectors/cms-typo3-admin.json +41 -0
- package/tests/selectors/cms-woocommerce-front.json +50 -0
- package/tests/selectors/cms-wordpress-admin.json +31 -0
- package/tests/selectors/framework-ant-design.json +80 -0
- package/tests/selectors/framework-bootstrap.json +86 -0
- package/tests/selectors/framework-bulma.json +74 -0
- package/tests/selectors/framework-chakra.json +58 -0
- package/tests/selectors/framework-foundation.json +51 -0
- package/tests/selectors/framework-material-ui.json +72 -0
- package/tests/selectors/framework-shadcn.json +51 -0
- package/tests/selectors/framework-tailwind.json +40 -0
- package/tests/selectors/framework-vuetify.json +61 -0
- package/tests/selectors/front-end-selectors.json +16 -0
- package/tests/selectors/homepage-selectors.json +13 -0
- package/tests/step-definitions/a11y.steps.js +798 -0
- package/tests/step-definitions/action.steps.js +167 -0
- package/tests/step-definitions/{webship-api.js → api.steps.js} +254 -44
- package/tests/step-definitions/assertion.steps.js +352 -0
- package/tests/step-definitions/auth.steps.js +124 -0
- package/tests/step-definitions/clock.steps.js +128 -0
- package/tests/step-definitions/cookie.steps.js +216 -0
- package/tests/step-definitions/debug.steps.js +31 -0
- package/tests/step-definitions/dialog.steps.js +193 -0
- package/tests/step-definitions/element.steps.js +314 -0
- package/tests/step-definitions/field.steps.js +653 -0
- package/tests/step-definitions/file-download.steps.js +193 -0
- package/tests/step-definitions/form.steps.js +333 -0
- package/tests/step-definitions/iframe.steps.js +178 -0
- package/tests/step-definitions/input.steps.js +163 -0
- package/tests/step-definitions/javascript.steps.js +71 -0
- package/tests/step-definitions/keyboard.steps.js +78 -0
- package/tests/step-definitions/link.steps.js +142 -0
- package/tests/step-definitions/metatag.steps.js +91 -0
- package/tests/step-definitions/modal.steps.js +219 -0
- package/tests/step-definitions/navigation.steps.js +218 -0
- package/tests/step-definitions/network.steps.js +238 -0
- package/tests/step-definitions/path.steps.js +141 -0
- package/tests/step-definitions/response.steps.js +98 -0
- package/tests/step-definitions/responsive.steps.js +123 -0
- package/tests/step-definitions/rest.steps.js +111 -0
- package/tests/step-definitions/screenshot.steps.js +423 -0
- package/tests/step-definitions/scroll.steps.js +189 -0
- package/tests/step-definitions/selectors.steps.js +996 -0
- package/tests/step-definitions/storage.steps.js +194 -0
- package/tests/step-definitions/table.steps.js +181 -0
- package/tests/step-definitions/wait.steps.js +400 -0
- package/tests/step-definitions/web-first.steps.js +296 -0
- package/tests/step-definitions/webship.js +567 -923
- package/tests/step-definitions/xml.steps.js +409 -0
- package/tests/step-definitions/yaml.steps.js +911 -0
- package/tests/step-definitions-diffy/README.md +329 -0
- package/tests/step-definitions-diffy/mock-diffy-api/server.js +84 -0
- package/tests/step-definitions-diffy/webship-diffy-mock.js +31 -0
- package/tests/step-definitions-diffy/webship-diffy.js +459 -0
- package/tsconfig.json +19 -3
- package/generate-reports.js +0 -22
- package/required/cucumber.js +0 -37
- package/required/generate-reports.js +0 -22
- package/required/package.json +0 -18
- package/required/playwright.config.ts +0 -37
- package/required/tests/features/README.md +0 -1
- package/required/tests/features/check-homepage.feature +0 -8
- package/required/tests/reports/README.md +0 -1
- package/required/tests/step-definitions/README.md +0 -1
- package/required/tests/step-definitions/custom.js +0 -4
- 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)
|