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.
- package/.circleci/config.yml +7 -31
- package/.drone.yml +68 -0
- package/.harness/webship-js-pipeline.yml +101 -0
- package/.semaphore/semaphore.yml +58 -0
- package/.teamcity/pom.xml +52 -0
- package/.teamcity/settings.kts +92 -0
- package/.travis.yml +24 -3
- package/AGENTS.md +109 -0
- package/CLAUDE.md +317 -0
- package/Jenkinsfile +54 -0
- package/azure-pipelines.yml +82 -0
- package/bamboo-specs/bamboo.yml +131 -0
- package/bin/generate-reports.js +181 -9
- package/buildspec.yml +56 -0
- package/cloudbuild.yaml +49 -0
- package/codefresh.yml +77 -0
- package/cucumber.js +48 -5
- 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 +799 -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/16-ci-cd.md +879 -0
- package/docs/README.md +113 -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 +295 -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/element.html +11 -0
- package/examples/field.html +24 -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/video-demo.html +43 -0
- package/package.json +10 -3
- 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/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/video.feature +18 -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 +7 -1
- 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/step-definitions/a11y.steps.js +800 -0
- package/tests/step-definitions/action.steps.js +167 -0
- package/tests/step-definitions/{webship-api.js → api.steps.js} +41 -23
- package/tests/step-definitions/assertion.steps.js +352 -0
- package/tests/step-definitions/auth.steps.js +126 -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 +39 -0
- package/tests/step-definitions/dialog.steps.js +193 -0
- package/tests/step-definitions/element.steps.js +356 -0
- package/tests/step-definitions/field.steps.js +653 -0
- package/tests/step-definitions/file-download.steps.js +211 -0
- package/tests/step-definitions/form.steps.js +333 -0
- package/tests/step-definitions/iframe.steps.js +228 -0
- package/tests/step-definitions/input.steps.js +202 -0
- package/tests/step-definitions/javascript.steps.js +232 -0
- package/tests/step-definitions/keyboard.steps.js +112 -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 +244 -0
- package/tests/step-definitions/navigation.steps.js +218 -0
- package/tests/step-definitions/network.steps.js +280 -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 +125 -0
- package/tests/step-definitions/rest.steps.js +111 -0
- package/tests/step-definitions/{webship-screenshot.js → screenshot.steps.js} +1 -5
- package/tests/step-definitions/scroll.steps.js +189 -0
- package/tests/step-definitions/{webship-selectors.js → selectors.steps.js} +64 -27
- package/tests/step-definitions/storage.steps.js +194 -0
- package/tests/step-definitions/table.steps.js +181 -0
- package/tests/step-definitions/video.steps.js +178 -0
- package/tests/step-definitions/wait.steps.js +400 -0
- package/tests/step-definitions/web-first.steps.js +298 -0
- package/tests/step-definitions/webship.js +741 -1477
- package/tests/step-definitions/xml.steps.js +411 -0
- package/tests/step-definitions/yaml.steps.js +913 -0
- package/tests/step-definitions-diffy/webship-diffy.js +0 -13
- package/tsconfig.json +19 -3
- package/videos/README.md +32 -0
- 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.
|
package/docs/overview.md
ADDED
|
@@ -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
|
+
|