webship-js 2.0.2 → 2.0.4

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 (181) hide show
  1. package/.circleci/config.yml +7 -31
  2. package/.drone.yml +68 -0
  3. package/.harness/webship-js-pipeline.yml +101 -0
  4. package/.semaphore/semaphore.yml +58 -0
  5. package/.teamcity/pom.xml +52 -0
  6. package/.teamcity/settings.kts +92 -0
  7. package/.travis.yml +24 -3
  8. package/AGENTS.md +109 -0
  9. package/CLAUDE.md +317 -0
  10. package/Jenkinsfile +54 -0
  11. package/azure-pipelines.yml +82 -0
  12. package/bamboo-specs/bamboo.yml +131 -0
  13. package/bin/generate-reports.js +181 -9
  14. package/buildspec.yml +56 -0
  15. package/cloudbuild.yaml +49 -0
  16. package/codefresh.yml +77 -0
  17. package/cucumber.js +48 -5
  18. package/docs/00-quick-start.md +102 -0
  19. package/docs/01-getting-started.md +102 -0
  20. package/docs/02-bbr-smart-waits.md +77 -0
  21. package/docs/03-selector-registry.md +95 -0
  22. package/docs/04-step-reference.md +799 -0
  23. package/docs/05-web-first-assertions.md +91 -0
  24. package/docs/06-network-and-dialogs.md +83 -0
  25. package/docs/07-auth-state.md +75 -0
  26. package/docs/08-clock-mocking.md +59 -0
  27. package/docs/09-api-testing.md +114 -0
  28. package/docs/10-accessibility.md +167 -0
  29. package/docs/11-debugging.md +129 -0
  30. package/docs/12-ai-agent-guide.md +338 -0
  31. package/docs/13-faq.md +236 -0
  32. package/docs/14-recipes-cookbook.md +255 -0
  33. package/docs/15-tag-conventions.md +76 -0
  34. package/docs/16-ci-cd.md +879 -0
  35. package/docs/README.md +113 -0
  36. package/docs/advanced-screenshots/then-i-save-fullscreen-screenshot.md +36 -0
  37. package/docs/advanced-screenshots/then-i-save-width-x-height-screenshot.md +34 -0
  38. package/docs/advanced-screenshots/when-i-save-screenshot-name-filename.md +45 -0
  39. package/docs/advanced-screenshots.md +52 -0
  40. package/docs/advanced-selectors.md +18 -0
  41. package/docs/api-step-definitions.md +45 -0
  42. package/docs/diffy-step-definitions/then-compare-diffy-env1-env2.md +30 -0
  43. package/docs/diffy-step-definitions/then-create-diffy-comparison-name-value.md +21 -0
  44. package/docs/diffy-step-definitions/then-create-diffy-comparison.md +25 -0
  45. package/docs/diffy-step-definitions/then-create-diffy-screenshot-environment-name.md +35 -0
  46. package/docs/diffy-step-definitions/then-i-take-screenshot.md +21 -0
  47. package/docs/diffy-step-definitions/then-i-take-screenshots-all-breakpoints.md +27 -0
  48. package/docs/diffy-step-definitions/then-send-screenshots-diffy-name-value.md +27 -0
  49. package/docs/diffy-step-definitions/then-upload-folder-url-diffy-snapshotname.md +28 -0
  50. package/docs/diffy-step-definitions/then-wait-diffy-comparison-complete.md +21 -0
  51. package/docs/diffy-step-definitions/when-i-resize-window-number.md +29 -0
  52. package/docs/diffy-step-definitions.md +21 -0
  53. package/docs/global-settings.md +295 -0
  54. package/docs/install-webship-js/ddev-webship-js.md +52 -0
  55. package/docs/install-webship-js.md +35 -0
  56. package/docs/overview.md +41 -0
  57. package/docs/step-definitions/given-i-am-anonymous-user.md +67 -0
  58. package/docs/step-definitions/given-i-am-homepage.md +68 -0
  59. package/docs/step-definitions/given-i-am-specific-page.md +72 -0
  60. package/docs/step-definitions/then-i-should-be.md +56 -0
  61. package/docs/step-definitions/then-i-should-see.md +62 -0
  62. package/docs/step-definitions/then-item-checkbox.md +54 -0
  63. package/docs/step-definitions/then-item-link-should-contain-url.md +84 -0
  64. package/docs/step-definitions/then-item-should-contain.md +67 -0
  65. package/docs/step-definitions/then-radio-button-value-should-be-selected.md +68 -0
  66. package/docs/step-definitions/then-response-status-code-should-be-number.md +69 -0
  67. package/docs/step-definitions/then-value-radio-button-selected.md +62 -0
  68. package/docs/step-definitions/when-i-attach-file-file-name-element.md +71 -0
  69. package/docs/step-definitions/when-i-check-checkbox.md +60 -0
  70. package/docs/step-definitions/when-i-click-link.md +51 -0
  71. package/docs/step-definitions/when-i-click-operation-text-row.md +71 -0
  72. package/docs/step-definitions/when-i-fill.md +59 -0
  73. package/docs/step-definitions/when-i-go-homepage.md +60 -0
  74. package/docs/step-definitions/when-i-go-specific-page.md +67 -0
  75. package/docs/step-definitions/when-i-move-backward-one-page.md +49 -0
  76. package/docs/step-definitions/when-i-move-forward-one-page.md +58 -0
  77. package/docs/step-definitions/when-i-press-button.md +58 -0
  78. package/docs/step-definitions/when-i-reload-page.md +51 -0
  79. package/docs/step-definitions/when-i-scroll.md +73 -0
  80. package/docs/step-definitions/when-i-select-option-select-list.md +53 -0
  81. package/docs/step-definitions/when-i-select-radio-button-value.md +62 -0
  82. package/docs/step-definitions/when-i-uncheck-checkbox.md +57 -0
  83. package/docs/step-definitions/when-i-wait-ajax-finish.md +64 -0
  84. package/docs/step-definitions/when-i-wait.md +62 -0
  85. package/docs/step-definitions.md +50 -0
  86. package/examples/a11y.html +31 -0
  87. package/examples/cookies.html +10 -0
  88. package/examples/date.html +12 -0
  89. package/examples/element.html +11 -0
  90. package/examples/field.html +24 -0
  91. package/examples/keyboard.html +11 -0
  92. package/examples/links.html +9 -0
  93. package/examples/modal.html +14 -0
  94. package/examples/path.html +3 -0
  95. package/examples/table.html +13 -0
  96. package/examples/video-demo.html +43 -0
  97. package/package.json +10 -3
  98. package/playwright.config.ts +3 -2
  99. package/tests/features/a11y.feature +39 -0
  100. package/tests/features/cookie.feature +13 -0
  101. package/tests/features/date.feature +11 -0
  102. package/tests/features/element.feature +16 -0
  103. package/tests/features/field.feature +25 -0
  104. package/tests/features/keyboard.feature +10 -0
  105. package/tests/features/link.feature +11 -0
  106. package/tests/features/modal-advanced-example.feature +1 -1
  107. package/tests/features/modal.feature +11 -0
  108. package/tests/features/path.feature +16 -0
  109. package/tests/features/response.feature +8 -0
  110. package/tests/features/responsive.feature +10 -0
  111. package/tests/features/table.feature +18 -0
  112. package/tests/features/video.feature +18 -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 +7 -1
  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/step-definitions/a11y.steps.js +800 -0
  142. package/tests/step-definitions/action.steps.js +167 -0
  143. package/tests/step-definitions/{webship-api.js → api.steps.js} +41 -23
  144. package/tests/step-definitions/assertion.steps.js +352 -0
  145. package/tests/step-definitions/auth.steps.js +126 -0
  146. package/tests/step-definitions/clock.steps.js +128 -0
  147. package/tests/step-definitions/cookie.steps.js +216 -0
  148. package/tests/step-definitions/debug.steps.js +39 -0
  149. package/tests/step-definitions/dialog.steps.js +193 -0
  150. package/tests/step-definitions/element.steps.js +356 -0
  151. package/tests/step-definitions/field.steps.js +653 -0
  152. package/tests/step-definitions/file-download.steps.js +211 -0
  153. package/tests/step-definitions/form.steps.js +333 -0
  154. package/tests/step-definitions/iframe.steps.js +228 -0
  155. package/tests/step-definitions/input.steps.js +202 -0
  156. package/tests/step-definitions/javascript.steps.js +232 -0
  157. package/tests/step-definitions/keyboard.steps.js +112 -0
  158. package/tests/step-definitions/link.steps.js +142 -0
  159. package/tests/step-definitions/metatag.steps.js +91 -0
  160. package/tests/step-definitions/modal.steps.js +244 -0
  161. package/tests/step-definitions/navigation.steps.js +218 -0
  162. package/tests/step-definitions/network.steps.js +280 -0
  163. package/tests/step-definitions/path.steps.js +141 -0
  164. package/tests/step-definitions/response.steps.js +98 -0
  165. package/tests/step-definitions/responsive.steps.js +125 -0
  166. package/tests/step-definitions/rest.steps.js +111 -0
  167. package/tests/step-definitions/{webship-screenshot.js → screenshot.steps.js} +1 -5
  168. package/tests/step-definitions/scroll.steps.js +189 -0
  169. package/tests/step-definitions/{webship-selectors.js → selectors.steps.js} +64 -27
  170. package/tests/step-definitions/storage.steps.js +194 -0
  171. package/tests/step-definitions/table.steps.js +181 -0
  172. package/tests/step-definitions/video.steps.js +178 -0
  173. package/tests/step-definitions/wait.steps.js +400 -0
  174. package/tests/step-definitions/web-first.steps.js +298 -0
  175. package/tests/step-definitions/webship.js +741 -1477
  176. package/tests/step-definitions/xml.steps.js +411 -0
  177. package/tests/step-definitions/yaml.steps.js +913 -0
  178. package/tests/step-definitions-diffy/webship-diffy.js +0 -13
  179. package/tsconfig.json +19 -3
  180. package/videos/README.md +32 -0
  181. package/.travis-ci.yml +0 -16
@@ -0,0 +1,295 @@
1
+ # Global Settings
2
+
3
+ Webship-js draws settings from three layers, evaluated in this order:
4
+
5
+ 1. **Environment variables** (CI / shell) — highest precedence.
6
+ 2. **`worldParameters` in `cucumber.js`** — project-level defaults.
7
+ 3. **Built-in defaults** — sane fallbacks shipped with the library.
8
+
9
+ This page documents every supported setting plus its env-var override.
10
+
11
+ ---
12
+
13
+ ## Top-level `cucumber.js` keys
14
+
15
+ | Key | Type | Default | Notes |
16
+ | --- | --- | --- | --- |
17
+ | `timeout` | int (ms) | `30000` | Per-step timeout enforced by `setDefaultTimeout`. |
18
+ | `requireModule` | array | `['ts-node/register']` | TypeScript runtime support. |
19
+ | `require` | array | step-definition globs | Files Cucumber-js loads at startup. |
20
+ | `paths` | array | `['tests/features/**/*.feature']` | Where to find feature files. |
21
+ | `format` | array | pretty + JSON report | Output formatters. |
22
+ | `formatOptions` | object | colour theme | Pretty-formatter colours. |
23
+ | `worldParameters` | object | (sections below) | Everything passed to the Playwright World. |
24
+
25
+ Single profile: `default`. Run with:
26
+
27
+ ```bash
28
+ npx cucumber-js
29
+ ```
30
+
31
+ To enable `parallel`, `retry`, or `retryTagFilter`, add them inside the
32
+ `default` block (or pass `--parallel N`, `--retry N`, `--retry-tag-filter @flaky`
33
+ on the command line).
34
+
35
+ ---
36
+
37
+ ## `worldParameters` — runtime configuration
38
+
39
+ ### `launchUrl`
40
+
41
+ | Type | Default | Env override |
42
+ | --- | --- | --- |
43
+ | string | `http://localhost:8080` | `LAUNCH_URL` |
44
+
45
+ Base URL prepended to every relative path in `Given I am on "/path"`.
46
+
47
+ ### `assetsFolder`
48
+
49
+ Resolved automatically to `tests/assets/`. Used by `When I attach the
50
+ file "...".`. Override per-World by extending the world constructor;
51
+ no env var.
52
+
53
+ ### `minWaitTime` — pacing knobs
54
+
55
+ ```js
56
+ minWaitTime: {
57
+ page: 3000, // ms — page-settle budget for navigation steps
58
+ before_scenario: 0, // ms — sleep before each Scenario starts
59
+ after_scenario: 0, // ms — sleep after each Scenario ends
60
+ before_step: 0, // ms — sleep before each Step
61
+ after_step: 0, // ms — sleep after each Step
62
+ }
63
+ ```
64
+
65
+ | Key | Default | Purpose |
66
+ | --- | --- | --- |
67
+ | `page` | `3000` | Per-navigation budget for `smartSettle`. Bump for slow CI. |
68
+ | `before_scenario` | `0` | Forces a fixed delay before each Scenario. Default off — BBR auto-settle replaces it. |
69
+ | `after_scenario` | `0` | Same, after Scenario ends. |
70
+ | `before_step` | `0` | Per-step sleep. Use only for visual debugging. |
71
+ | `after_step` | `0` | Same, after each step. |
72
+
73
+ > Best practice: leave the four `*_scenario` / `*_step` keys at `0` —
74
+ > the BBR auto-settle hook handles real timing. Only raise them when
75
+ > demoing a recording in headed mode.
76
+
77
+ ### `selectors` — named selector registry
78
+
79
+ ```js
80
+ selectors: {
81
+ css: { /* name → CSS selector */ },
82
+ xpath: { /* name → XPath expression */ },
83
+ filesPath: './tests/selectors/', // base path for JSON presets
84
+ files: [], // JSON files to auto-load per scenario
85
+ offset: 60, // px — scroll offset for relative-position assertions
86
+ breakpoints: { // viewport sizes (used by responsive.steps.js)
87
+ xs: { width: 375, height: 667 },
88
+ sm: { width: 576, height: 800 },
89
+ md: { width: 768, height: 1024 },
90
+ lg: { width: 992, height: 768 },
91
+ xl: { width: 1200, height: 900, default: true },
92
+ xxl: { width: 1400, height: 900 },
93
+ xxxl: { width: 1920, height: 1080 },
94
+ },
95
+ }
96
+ ```
97
+
98
+ | Key | Default | Env override |
99
+ | --- | --- | --- |
100
+ | `css` | `{}` | — |
101
+ | `xpath` | `{}` | — |
102
+ | `filesPath` | `./tests/selectors/` | — |
103
+ | `files` | `[]` | — |
104
+ | `offset` | `60` | `WEBSHIP_SELECTORS_OFFSET` |
105
+ | `breakpoints` | xs..xxxl | `WEBSHIP_SELECTORS_BREAKPOINTS` (JSON string) |
106
+
107
+ ### `screenshot` — capture configuration
108
+
109
+ ```js
110
+ screenshot: {
111
+ dir: './screenshots',
112
+ purge: false,
113
+ onFailed: true,
114
+ onEveryStep: false,
115
+ alwaysFullscreen: false,
116
+ failedPrefix: 'failed_',
117
+ filenamePattern: '{datetime}.{feature_file}.feature_{step_line}.{ext}',
118
+ filenamePatternFailed: '{failed_prefix}{datetime}.{feature_file}.feature_{step_line}.{ext}',
119
+ infoTypes: '',
120
+ }
121
+ ```
122
+
123
+ | Key | Default | Env override |
124
+ | --- | --- | --- |
125
+ | `dir` | `./screenshots` | `WEBSHIP_SCREENSHOT_DIR` |
126
+ | `purge` | `false` | `WEBSHIP_SCREENSHOT_PURGE` |
127
+ | `onFailed` | `true` | `WEBSHIP_SCREENSHOT_ON_FAILED` |
128
+ | `onEveryStep` | `false` | `WEBSHIP_SCREENSHOT_ON_EVERY_STEP` |
129
+ | `alwaysFullscreen` | `false` | `WEBSHIP_SCREENSHOT_FULLSCREEN` |
130
+ | `failedPrefix` | `failed_` | `WEBSHIP_SCREENSHOT_FAILED_PREFIX` |
131
+ | `filenamePattern` | `{datetime}...` | `WEBSHIP_SCREENSHOT_PATTERN` |
132
+ | `filenamePatternFailed` | `{failed_prefix}...` | `WEBSHIP_SCREENSHOT_PATTERN_FAIL` |
133
+ | `infoTypes` | `''` | `WEBSHIP_SCREENSHOT_INFO_TYPES` (e.g. `"url,feature,step,datetime"`) |
134
+
135
+ Filename pattern tokens: `{datetime}`, `{date}`, `{time}`, `{feature_file}`,
136
+ `{feature}`, `{scenario}`, `{step_line}`, `{ext}`, `{failed_prefix}`,
137
+ `{url}`, `{host}`, `{path}`.
138
+
139
+ ### `video` — Playwright video recording
140
+
141
+ ```js
142
+ video: {
143
+ mode: 'off', // WEBSHIP_VIDEO — 'off' | 'on' | 'on-failure' | 'tag'
144
+ dir: './videos', // WEBSHIP_VIDEO_DIR
145
+ size: { width: 1280, height: 720 }, // recording viewport
146
+ filenamePattern: '{datetime}.{feature_file}.{scenario}.{status}.{ext}',
147
+ }
148
+ ```
149
+
150
+ Tag overrides per scenario:
151
+
152
+ | Tag | Effect |
153
+ | --- | --- |
154
+ | `@video` | Force recording on. |
155
+ | `@no-video` | Suppress recording. |
156
+
157
+ Modes:
158
+
159
+ | Mode | Behaviour |
160
+ | --- | --- |
161
+ | `off` (default) | No recording. |
162
+ | `on` | Record every scenario. |
163
+ | `on-failure` | Record every scenario, keep only failures. |
164
+ | `tag` | Record only scenarios tagged `@video`. |
165
+
166
+ Mid-scenario start / stop steps live in `video.steps.js`. Recording starts at context creation only — `When I start video recording` closes + reopens the context, losing page state. Call before any navigation.
167
+
168
+ ### `javascript` — page-error / console capture
169
+
170
+ ```js
171
+ javascript: {
172
+ mode: 'warn', // WEBSHIP_JS_ERROR_MODE — 'warn' | 'fail' | 'off'
173
+ levels: ['error'], // WEBSHIP_JS_ERROR_LEVELS (csv) — console levels to capture
174
+ ignore: '', // WEBSHIP_JS_ERROR_IGNORE — regex of messages to drop
175
+ beforeScenario: false, // WEBSHIP_JS_ERROR_BEFORE — snapshot pre-existing errors
176
+ afterScenario: true, // WEBSHIP_JS_ERROR_AFTER — report at scenario end
177
+ }
178
+ ```
179
+
180
+ Tags override `mode` per scenario:
181
+
182
+ | Tag | Effect |
183
+ | --- | --- |
184
+ | `@js-fail` / `@javascript` (legacy) | force `fail` |
185
+ | `@js-warn` | force `warn` |
186
+ | `@js-off` / `@js-errors` (legacy) | force `off` |
187
+
188
+ The explicit step `Then there should be no JavaScript errors` always asserts (independent of mode).
189
+
190
+ ### `diffy` — visual-diff integration (optional)
191
+
192
+ ```js
193
+ diffy: {
194
+ apiKey: 'mock-key',
195
+ projectId: 1,
196
+ breakpoints: '640,1200',
197
+ windowHeight: 2000,
198
+ screenshotsDir: '',
199
+ baseUrl: 'http://127.0.0.1:3099/',
200
+ maxWait: 30,
201
+ env1Url: '',
202
+ env2Url: '',
203
+ }
204
+ ```
205
+
206
+ | Key | Default | Env override |
207
+ | --- | --- | --- |
208
+ | `apiKey` | `mock-key` | `DIFFY_API_KEY` |
209
+ | `projectId` | `1` | `DIFFY_PROJECT_ID` |
210
+ | `breakpoints` | `640,1200` | `DIFFY_BREAKPOINTS` |
211
+ | `windowHeight` | `2000` | `DIFFY_WINDOW_HEIGHT` |
212
+ | `screenshotsDir` | `''` | `DIFFY_SCREENSHOTS_DIR` |
213
+ | `baseUrl` | mock server | `DIFFY_API_BASE_URL` |
214
+ | `maxWait` | `30` (seconds) | `DIFFY_MAX_WAIT` |
215
+ | `env1Url` | `''` | `DIFFY_ENV1_URL` |
216
+ | `env2Url` | `''` | `DIFFY_ENV2_URL` |
217
+
218
+ ---
219
+
220
+ ## `playwright.config.ts` — browser launch
221
+
222
+ ```ts
223
+ const config = {
224
+ browser: process.env.BROWSER || 'chromium',
225
+ launchOptions: {
226
+ headless: process.env.HEADLESS !== 'false',
227
+ slowMo: parseInt(process.env.SLOW_MO || '300', 10),
228
+ args: [...],
229
+ },
230
+ contextOptions: {
231
+ viewport: null,
232
+ ignoreHTTPSErrors: true,
233
+ },
234
+ };
235
+ ```
236
+
237
+ | Key | Default | Env override |
238
+ | --- | --- | --- |
239
+ | `browser` | `chromium` | `BROWSER` (`chromium` / `firefox` / `webkit`) |
240
+ | `launchOptions.headless` | `true` | `HEADLESS=false` for headed |
241
+ | `launchOptions.slowMo` | `300` headed: `800` | `SLOW_MO` (ms) |
242
+ | `launchOptions.args` | chromium-only flags | edit file directly |
243
+ | `contextOptions.viewport` | `null` (use browser default) | edit file directly |
244
+ | `contextOptions.ignoreHTTPSErrors` | `true` | edit file directly |
245
+
246
+ ---
247
+
248
+ ## Behaviour toggles
249
+
250
+ | Env var | Effect |
251
+ | --- | --- |
252
+ | `WEBSHIP_AUTO_SETTLE` | Set to `off` to disable the BBR auto-settle hook (`smartSettle(page, 1500)` after every state-changing step). |
253
+ | `WEBSHIP_REPORT_DISABLE` | Set to `1` to skip auto-generating the HTML report on cucumber-js process exit. |
254
+ | `WEBSHIP_REPORT_ARGS` | Extra CLI flags forwarded to `bin/generate-reports.js`. e.g. `--theme hierarchy --layout 2`. |
255
+
256
+ ---
257
+
258
+ ## Run / pacing env vars
259
+
260
+ | Env var | Default | Effect |
261
+ | --- | --- | --- |
262
+ | `LAUNCH_URL` | `http://localhost:8080` | Base URL for navigation steps. |
263
+ | `BROWSER` | `chromium` | Browser engine. |
264
+ | `HEADLESS` | `true` | `false` opens a visible browser. |
265
+ | `SLOW_MO` | `300` (headed: `800`) | Per-action delay (ms). Set to `0` for fast runs. |
266
+
267
+ ---
268
+
269
+ ## npm scripts
270
+
271
+ | Script | Description |
272
+ | --- | --- |
273
+ | `npm test` | Default profile, full pretty output, slow-mo on. |
274
+ | `npm run test:headed` | `HEADLESS=false`. Watches the browser. |
275
+ | `npm run test:fast` | `SLOW_MO=0` on the default profile. |
276
+ | `npm run test:chromium` | `BROWSER=chromium npm test`. |
277
+ | `npm run test:firefox` | `BROWSER=firefox npm test`. |
278
+ | `npm run test:webkit` | `BROWSER=webkit npm test`. |
279
+ | `npm start` | Static dev server on port 8080 (`http-server examples`). |
280
+ | `npm run generate-reports` | Manually rebuild the HTML report from the JSON output. |
281
+
282
+ ---
283
+
284
+ ## Recipe — typical CI lane
285
+
286
+ ```bash
287
+ LAUNCH_URL=https://staging.example.com \
288
+ SLOW_MO=0 \
289
+ BROWSER=chromium \
290
+ WEBSHIP_SCREENSHOT_PURGE=1 \
291
+ npx cucumber-js --tags "@critical and not @wip" --parallel 4 --retry 1 --retry-tag-filter @flaky
292
+ ```
293
+
294
+ Translation: zero slow-mo, 4 parallel processes, retry `@flaky` once,
295
+ fresh `screenshots/` each run, only `@critical` (excluding work-in-progress).
@@ -0,0 +1,52 @@
1
+
2
+ # DDEV Webship-JS
3
+
4
+ ## Overview
5
+
6
+ This add-on integrates "Webship-JS — a Playwright + Cucumber-JS Automated Functional Acceptance Testing framework" into DDEV projects, enabling automated browser testing via Gherkin `.feature` files within the DDEV environment.
7
+
8
+ ## Installation
9
+
10
+ Execute the command to add and configure the tool:
11
+
12
+ ```
13
+ ddev add-on get webship/ddev-webship-js
14
+ ```
15
+
16
+ The installation automatically scaffolds required configuration files, creates a starter feature file, installs Playwright browsers, and restarts the DDEV environment.
17
+
18
+ ### Install Dependencies
19
+
20
+ **Using npm:**
21
+ ```
22
+ ddev npm install
23
+ ```
24
+
25
+ **Using yarn:**
26
+ ```
27
+ ddev yarn install
28
+ ```
29
+
30
+ ## Running Tests
31
+
32
+ ### With npm
33
+
34
+ ```
35
+ ddev npm run test:chromium # Run all tests with Chromium
36
+ ddev npm run test:firefox # Run all tests with Firefox
37
+ ddev npm run test:webkit # Run all tests with WebKit
38
+ ```
39
+
40
+ ### With yarn
41
+
42
+ ```
43
+ ddev yarn test:chromium # Run all tests with Chromium
44
+ ddev yarn test:firefox # Run all tests with Firefox
45
+ ddev yarn test:webkit # Run all tests with WebKit
46
+ ```
47
+
48
+ ### Running Specific Tests
49
+
50
+ ```
51
+ ddev exec npx cucumber-js --config cucumber.js tests/features/example.feature
52
+ ```
@@ -0,0 +1,35 @@
1
+
2
+ # Install Webship JS
3
+
4
+ **Install Webship-js on your project. Simply execute the following command:**
5
+
6
+ ```
7
+ npm add webship-js
8
+ ```
9
+
10
+ ## Automated Functional Acceptance Testing
11
+
12
+ ```
13
+ npm test
14
+ ```
15
+
16
+ ### Boost your site's success with automated testing
17
+
18
+ #### For Commercial Professional Support
19
+
20
+ [Contact Us](/contact)
21
+
22
+ ## Documentation Structure
23
+
24
+ The page is part of the Webship JS 2.0.x documentation section, which includes:
25
+
26
+ - Global Settings
27
+ - Step Definitions
28
+ - API Step Definitions
29
+ - Advanced Screenshots
30
+ - Advanced Selectors
31
+ - Diffy Step Definitions
32
+ - Assertions
33
+ - Commands
34
+
35
+ There is also a subsection on "[DDEV Webship-JS](/docs/webship-js/2.0.x/install-webship-js/ddev-webship-js)" available under the installation guide.
@@ -0,0 +1,41 @@
1
+
2
+ # Webship JS 2.0.x
3
+
4
+ Webship-js is an Automated Functional Acceptance Testing tool that streamlines end-to-end testing for web applications. It combines [Playwright](https://playwright.dev/) and [Cucumber-js](https://github.com/cucumber/cucumber-js) with custom step definitions.
5
+
6
+ ## Key Features
7
+
8
+ **Test Script Creation:** Users can write scenarios mimicking real user interactions:
9
+
10
+ ```gherkin
11
+ Feature: Login page
12
+ Scenario: Successful Login with Valid entries
13
+ Given I am on homepage
14
+ When I go to "login.html"
15
+ And I fill in "Username" with "Smith"
16
+ And I fill in "Password" with "1$34"
17
+ And I press "Login"
18
+ Then I should see "Welcome Smith"
19
+ ```
20
+
21
+ **Test Execution:** The tool automates test script execution and verifies outcomes against actual results.
22
+
23
+ **Test Data Management:** Functionality for defining and manipulating input data sets across different test scenarios.
24
+
25
+ **Reporting and Analysis:** Generates detailed reports with passed/failed cases and exception documentation.
26
+
27
+ ## Benefits
28
+
29
+ Webship-js offers "increased testing efficiency, reduced human error, improved test coverage, and faster time-to-market."
30
+
31
+ ## Documentation Sub-pages
32
+
33
+ - [Install Webship JS](/docs/webship-js/2.0.x/install-webship-js)
34
+ - [Global Settings](/docs/webship-js/2.0.x/global-settings)
35
+ - [Step Definitions](/docs/webship-js/2.0.x/step-definitions)
36
+ - [API Step Definitions](/docs/webship-js/2.0.x/api-step-definitions)
37
+ - [Advanced Screenshots](/docs/webship-js/2.0.x/advanced-screenshots)
38
+ - [Advanced Selectors](/docs/webship-js/2.0.x/advanced-selectors)
39
+ - [Diffy Step Definitions](/docs/webship-js/2.0.x/diffy-step-definitions)
40
+ - [Assertions](/docs/webship-js/2.0.x/assertions)
41
+ - [Commands](/docs/webship-js/2.0.x/commands)
@@ -0,0 +1,67 @@
1
+
2
+ # Given I am an anonymous user
3
+
4
+ ## Step Definition
5
+
6
+ ```gherkin
7
+ Given(/^(I am |we are )?an anonymous user)
8
+ ```
9
+
10
+ ## Description
11
+
12
+ "This step ensures that the current user is not logged in." It configures the browser to simulate a guest visitor state without active session or authentication credentials.
13
+
14
+ ## Usage Examples
15
+
16
+ ```gherkin
17
+ Given I am an anonymous user
18
+ ```
19
+
20
+ ```gherkin
21
+ Given we are an anonymous user
22
+ ```
23
+
24
+ ```gherkin
25
+ Given an anonymous user
26
+ ```
27
+
28
+ ## Purpose
29
+
30
+ The step definition supports three syntactic variations to accommodate different BDD writing styles while accomplishing the same objective: establishing an unauthenticated user context for test execution.
31
+
32
+ ## More examples
33
+
34
+ <!-- generated: extended-examples -->
35
+
36
+ ### Example 1
37
+
38
+ ```gherkin
39
+ Given I am an anonymous user
40
+ When I am on "/dashboard"
41
+ Then I should see "Sign in"
42
+ ```
43
+
44
+ ### Example 2
45
+
46
+ ```gherkin
47
+ Given I am an anonymous user
48
+ When I am on the homepage
49
+ Then I should not see "Logout"
50
+ ```
51
+
52
+ ### Example 3
53
+
54
+ ```gherkin
55
+ Given I am an anonymous user
56
+ When I am on "/checkout"
57
+ Then I should be on "/login"
58
+ ```
59
+
60
+ ### Example 4
61
+
62
+ ```gherkin
63
+ Given an anonymous user
64
+ When I am on "/admin"
65
+ Then the response status code should be 403
66
+ ```
67
+
@@ -0,0 +1,68 @@
1
+
2
+ # Given I am on homepage
3
+
4
+ ## Step Definition
5
+
6
+ ```
7
+ Given (I am |we are )?on( the)* (homepage|frontpage)
8
+ ```
9
+
10
+ ## Description
11
+
12
+ This step definition establishes the initial context for test scenarios by specifying that a user is currently viewing the website's homepage. When executed, it performs necessary actions to navigate to the homepage, which may include opening a browser, entering the URL, and waiting for the page to fully load. Implementation details vary based on the testing framework and application being tested.
13
+
14
+ ## Examples
15
+
16
+ ```
17
+ Given I am on homepage
18
+
19
+ Given I am on the homepage
20
+
21
+ Given I am on frontpage
22
+
23
+ Given I am on the frontpage
24
+
25
+ Given we are on homepage
26
+
27
+ Given on the homepage
28
+
29
+ Given on homepage
30
+
31
+ Given we are on the frontpage
32
+
33
+ Given on frontpage
34
+ ```
35
+
36
+ ## More examples
37
+
38
+ <!-- generated: extended-examples -->
39
+
40
+ ### Example 1
41
+
42
+ ```gherkin
43
+ Given I am on the homepage
44
+ Then I should see "Welcome"
45
+ ```
46
+
47
+ ### Example 2
48
+
49
+ ```gherkin
50
+ Given we are on homepage
51
+ Then "<header>" should be visible
52
+ ```
53
+
54
+ ### Example 3
55
+
56
+ ```gherkin
57
+ Given on the frontpage
58
+ Then the page should have a main landmark
59
+ ```
60
+
61
+ ### Example 4
62
+
63
+ ```gherkin
64
+ Given I am on the homepage
65
+ When I follow "About"
66
+ Then I should be on "/about"
67
+ ```
68
+
@@ -0,0 +1,72 @@
1
+
2
+ # Given I am on "specific" page
3
+
4
+ ## Step Definition Pattern
5
+
6
+ ```gherkin
7
+ Given (I am |we are )*on( the)* "([^"]*)?"( page)*
8
+ ```
9
+
10
+ ## Description
11
+
12
+ This step definition establishes the initial context for test scenarios by navigating to a designated webpage. Upon execution, it performs the necessary actions to access a specific page, including launching a browser, entering the URL, and allowing the page to fully load.
13
+
14
+ ## Usage Examples
15
+
16
+ ```gherkin
17
+ Given I am on "contact"
18
+
19
+ Given we are on "user/login"
20
+
21
+ Given I am on the "/about-us" page
22
+
23
+ Given we are on the "/about-us" page
24
+
25
+ Given on "/about-us"
26
+
27
+ Given on the "/about-us" page
28
+ ```
29
+
30
+ ## Key Information
31
+
32
+ This step definition is part of the Webship JS 2.0.x documentation's Step Definitions section. It supports flexible phrasing patterns, allowing users to specify page locations using various grammatical structures. The pattern accepts optional articles ("the") and the word "page," accommodating different natural language preferences while directing the test to navigate to the specified URL or page identifier.
33
+
34
+ ## More examples
35
+
36
+ <!-- generated: extended-examples -->
37
+
38
+ ### Example 1
39
+
40
+ ```gherkin
41
+ Given I am on "/about"
42
+ Then I should see "Our mission"
43
+ ```
44
+
45
+ ### Example 2
46
+
47
+ ```gherkin
48
+ Given I am on "/products?category=laptops"
49
+ Then I should see 12 ".product-card" elements
50
+ ```
51
+
52
+ ### Example 3
53
+
54
+ ```gherkin
55
+ Given we are on the "/contact" page
56
+ Then "<form>" should be visible
57
+ ```
58
+
59
+ ### Example 4
60
+
61
+ ```gherkin
62
+ Given I am on "/blog/2026/05/launch"
63
+ Then the page should have exactly one h1
64
+ ```
65
+
66
+ ### Example 5
67
+
68
+ ```gherkin
69
+ Given on "/admin/users"
70
+ Then I should see "User list"
71
+ ```
72
+
@@ -0,0 +1,56 @@
1
+
2
+ # Then I should be
3
+
4
+ ## Overview
5
+
6
+ This step definition category is designed to verify that navigation functions correctly and users arrive at the intended pages following interactions. As stated on the page: "This step is useful for ensuring that the navigation through a website is working correctly and that the user lands on the intended page after performing certain actions or interactions."
7
+
8
+ ## Available Step Definitions
9
+
10
+ The "Then I should be" group contains four primary variations:
11
+
12
+ 1. **Then I should be on (the) homepage**
13
+ 2. **Then I should not be on (the) homepage**
14
+ 3. **Then I should be on "specific page"**
15
+ 4. **Then I should not be on "page path"**
16
+
17
+ Each step allows testers to validate whether the current page matches expected navigation outcomes.
18
+
19
+ ## Purpose
20
+
21
+ These assertions verify successful navigation by confirming the user's location within the website after executing actions like clicking links, submitting forms, or using browser controls. They serve as validation checkpoints in automated testing workflows.
22
+
23
+ ## More examples
24
+
25
+ <!-- generated: extended-examples -->
26
+
27
+ ### Example 1
28
+
29
+ ```gherkin
30
+ Then I should be on "/dashboard"
31
+ ```
32
+
33
+ ### Example 2
34
+
35
+ ```gherkin
36
+ Then I should be on the homepage
37
+ ```
38
+
39
+ ### Example 3
40
+
41
+ ```gherkin
42
+ And I should not be on the frontpage
43
+ ```
44
+
45
+ ### Example 4
46
+
47
+ ```gherkin
48
+ Then we should be on "/account"
49
+ ```
50
+
51
+ ### Example 5
52
+
53
+ ```gherkin
54
+ Then I should be on "/auth/callback"
55
+ ```
56
+