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
package/docs/README.md
ADDED
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
# Webship-js Documentation
|
|
2
|
+
|
|
3
|
+
Webship-js is a BDD-first browser-automation harness built on Playwright + Cucumber-js. Feature files in plain Gherkin; selectors that survive redesigns; smart waits that never sleep.
|
|
4
|
+
|
|
5
|
+
**411 built-in steps** across **36 step files**. **288 example scenarios / 1,406 step executions** in the bundled suite, all green on chromium, firefox, and webkit.
|
|
6
|
+
|
|
7
|
+
## Reading order
|
|
8
|
+
|
|
9
|
+
### Webship-js essentials (custom)
|
|
10
|
+
|
|
11
|
+
| Doc | Topic |
|
|
12
|
+
| --- | --- |
|
|
13
|
+
| [00 Quick start](00-quick-start.md) | 5-minute path for newcomers |
|
|
14
|
+
| [01 Getting started](01-getting-started.md) | Install, project layout, run modes |
|
|
15
|
+
| [02 BBR smart waits](02-bbr-smart-waits.md) | Why we never `sleep N seconds` |
|
|
16
|
+
| [03 Selector registry](03-selector-registry.md) | Named selectors + CMS / framework presets |
|
|
17
|
+
| [04 Step reference](04-step-reference.md) | Every built-in step, by topic |
|
|
18
|
+
| [05 Web-first assertions](05-web-first-assertions.md) | Auto-retrying matchers |
|
|
19
|
+
| [06 Networking & dialogs](06-network-and-dialogs.md) | Request mocking, alerts, prompts |
|
|
20
|
+
| [07 Auth state](07-auth-state.md) | Save / restore login |
|
|
21
|
+
| [08 Clock mocking](08-clock-mocking.md) | Control time |
|
|
22
|
+
| [09 API testing](09-api-testing.md) | Direct HTTP from BDD |
|
|
23
|
+
| [10 Accessibility](10-accessibility.md) | POUR smoke checks |
|
|
24
|
+
| [11 Debugging](11-debugging.md) | Screenshots, headed, traces, reports |
|
|
25
|
+
| [12 AI agent guide](12-ai-agent-guide.md) | Wisdom + recipes from the Recipes book v1.0.30 (TDD AI / SPDD / Three Amigos / golden rules) |
|
|
26
|
+
| [13 FAQ](13-faq.md) | Common questions for newcomers |
|
|
27
|
+
| [14 Recipes cookbook](14-recipes-cookbook.md) | 20 paste-and-go scenarios |
|
|
28
|
+
| [15 Tag conventions](15-tag-conventions.md) | Standard tags + CI lane patterns |
|
|
29
|
+
| [16 CI / CD setup](16-ci-cd.md) | Per-provider setup steps and config notes |
|
|
30
|
+
|
|
31
|
+
### Reference (mirrored from webship.co/docs/webship-js/2.0.x)
|
|
32
|
+
|
|
33
|
+
| Doc | Topic |
|
|
34
|
+
| --- | --- |
|
|
35
|
+
| [Overview](overview.md) | Webship-js v2.0.x at a glance |
|
|
36
|
+
| [Install](install-webship-js.md) | Install Webship-js |
|
|
37
|
+
| [Install — DDEV](install-webship-js/ddev-webship-js.md) | DDEV-Webship-js variant |
|
|
38
|
+
| [Global settings](global-settings.md) | `cucumber.js` `worldParameters` reference |
|
|
39
|
+
| [Commands](commands.md) | CLI commands |
|
|
40
|
+
| [Assertions](assertions.md) | Built-in assertions |
|
|
41
|
+
| [Step definitions](step-definitions.md) | Step-definition catalogue (28 sub-pages under `step-definitions/`) |
|
|
42
|
+
| [API step definitions](api-step-definitions.md) | REST step definitions |
|
|
43
|
+
| [Advanced screenshots](advanced-screenshots.md) | Per-size, full-page, named (3 sub-pages under `advanced-screenshots/`) |
|
|
44
|
+
| [Advanced selectors](advanced-selectors.md) | Named selector registry, position assertions |
|
|
45
|
+
| [Diffy step definitions](diffy-step-definitions.md) | Visual-diff workflow (10 sub-pages under `diffy-step-definitions/`) |
|
|
46
|
+
|
|
47
|
+
## At a glance
|
|
48
|
+
|
|
49
|
+
```gherkin
|
|
50
|
+
Feature: Smoke
|
|
51
|
+
|
|
52
|
+
Background:
|
|
53
|
+
Given I restore the auth state from "tests/auth/admin.json"
|
|
54
|
+
|
|
55
|
+
@javascript
|
|
56
|
+
Scenario: Dashboard renders without JS errors
|
|
57
|
+
Given I am on "/dashboard"
|
|
58
|
+
And I wait until the network is idle
|
|
59
|
+
Then the page should have a main landmark
|
|
60
|
+
And "<#user-list>" should have a count of 5 within 5 seconds
|
|
61
|
+
And "<.notification>" should not be visible
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## Source layout
|
|
65
|
+
|
|
66
|
+
```
|
|
67
|
+
webship-js/
|
|
68
|
+
├── docs/ <— You are here
|
|
69
|
+
├── tests/
|
|
70
|
+
│ ├── features/ <— Your *.feature files
|
|
71
|
+
│ ├── selectors/ <— CMS / framework JSON presets
|
|
72
|
+
│ └── step-definitions/ <— Built-in steps (auto-loaded)
|
|
73
|
+
│ ├── webship.js # World setup, hooks, shared helpers (smartSettle, modal, selectors, date tokens)
|
|
74
|
+
│ ├── a11y.steps.js (26) # axe-core audits + WCAG hygiene probes
|
|
75
|
+
│ ├── action.steps.js (7) # press / click / follow / attach
|
|
76
|
+
│ ├── api.steps.js (22) # REST long form (base URL, headers, query, body, JSON Pointer)
|
|
77
|
+
│ ├── assertion.steps.js (14) # see / not see, in row, in element, response, count
|
|
78
|
+
│ ├── auth.steps.js (3) # save / restore / clear storageState
|
|
79
|
+
│ ├── clock.steps.js (7) # install / advance / pause / set system time
|
|
80
|
+
│ ├── cookie.steps.js (12) # cookie exists / equals / contains
|
|
81
|
+
│ ├── debug.steps.js (2) # print URL / last response (diagnostic)
|
|
82
|
+
│ ├── dialog.steps.js (8) # native alert / confirm / prompt
|
|
83
|
+
│ ├── element.steps.js (19) # focus / scroll-to / dispatch / count / position
|
|
84
|
+
│ ├── field.steps.js (27) # field state, checkbox, radio, select-list
|
|
85
|
+
│ ├── file-download.steps.js (8) # capture + assert filename / mime / path
|
|
86
|
+
│ ├── form.steps.js (13) # fill / select / check / uncheck / radio
|
|
87
|
+
│ ├── iframe.steps.js (10) # frameLocator switch + scoped click / fill / assert
|
|
88
|
+
│ ├── input.steps.js (9) # hover / drag / dbl / right-click / tap / viewport
|
|
89
|
+
│ ├── javascript.steps.js (4) # JS error tracker + assertion (warn / fail / off)
|
|
90
|
+
│ ├── keyboard.steps.js (4) # single key + combos with alias normalisation
|
|
91
|
+
│ ├── link.steps.js (9) # href / title / target / rel
|
|
92
|
+
│ ├── metatag.steps.js (3) # description / keywords / OG / Twitter
|
|
93
|
+
│ ├── modal.steps.js (9) # HTML modal visibility / content / interactions
|
|
94
|
+
│ ├── navigation.steps.js (11) # homepage / paths / history / URL assertions
|
|
95
|
+
│ ├── network.steps.js (10) # route stubs / mocks / delays / offline
|
|
96
|
+
│ ├── path.steps.js (8) # URL path / query / fragment
|
|
97
|
+
│ ├── response.steps.js (4) # response header inspection
|
|
98
|
+
│ ├── responsive.steps.js (5) # named breakpoints + explicit viewport
|
|
99
|
+
│ ├── rest.steps.js (5) # REST short form
|
|
100
|
+
│ ├── screenshot.steps.js (6) # manual + auto-on-failure + per-step capture
|
|
101
|
+
│ ├── scroll.steps.js (12) # page + scoped element scroll
|
|
102
|
+
│ ├── selectors.steps.js (22) # named CSS / XPath registry + 22 CMS / framework presets
|
|
103
|
+
│ ├── storage.steps.js (9) # local / session storage
|
|
104
|
+
│ ├── table.steps.js (8) # data-table row / column assertions
|
|
105
|
+
│ ├── video.steps.js (4) # start / stop / save webm recording
|
|
106
|
+
│ ├── wait.steps.js (21) # every wait phrasing — all BBR-backed
|
|
107
|
+
│ ├── web-first.steps.js (12) # auto-retrying matchers (`within N seconds`)
|
|
108
|
+
│ ├── xml.steps.js (20) # XPath equals / contains / count / attr
|
|
109
|
+
│ └── yaml.steps.js (38) # multi-doc + types + numerics + JSON Schema + diff
|
|
110
|
+
├── examples/ <— Static HTML fixtures
|
|
111
|
+
├── cucumber.js <— Profiles + worldParameters
|
|
112
|
+
└── playwright.config.ts <— Browser launch + context options
|
|
113
|
+
```
|
|
@@ -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)
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
|
|
2
|
+
# Then I take screenshot
|
|
3
|
+
|
|
4
|
+
## Description
|
|
5
|
+
|
|
6
|
+
"Capture a full-page screenshot at the current viewport. Held in-memory (and optionally written to DIFFY_SCREENSHOTS_DIR) until 'send screenshots to diffy with name' uploads the batch."
|
|
7
|
+
|
|
8
|
+
## Gherkin Step Definition
|
|
9
|
+
|
|
10
|
+
```
|
|
11
|
+
Then(/^(?:I |we )?take screenshot$)
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
## Usage Examples
|
|
15
|
+
|
|
16
|
+
- `Then I take screenshot`
|
|
17
|
+
- `Then we take screenshot`
|
|
18
|
+
- `And I take screenshot`
|
|
19
|
+
- `And we take screenshot`
|
|
20
|
+
- `Then take screenshot`
|
|
21
|
+
- `And take screenshot`
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
|
|
2
|
+
# Then I take screenshots for all breakpoints
|
|
3
|
+
|
|
4
|
+
## Description
|
|
5
|
+
|
|
6
|
+
This step definition resizes the browser window to each configured breakpoint and captures a screenshot at each breakpoint. The breakpoints are sourced from the `DIFFY_BREAKPOINTS` environment variable or `worldParameters.diffy.breakpoints`.
|
|
7
|
+
|
|
8
|
+
## Gherkin Step Pattern
|
|
9
|
+
|
|
10
|
+
```
|
|
11
|
+
Then(/^(?:I |we )?take screenshots for all breakpoints$)
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
## Usage Examples
|
|
15
|
+
|
|
16
|
+
- `Then I take screenshots for all breakpoints`
|
|
17
|
+
- `Then we take screenshots for all breakpoints`
|
|
18
|
+
- `And I take screenshots for all breakpoints`
|
|
19
|
+
- `And we take screenshots for all breakpoints`
|
|
20
|
+
- `Then take screenshots for all breakpoints`
|
|
21
|
+
- `And take screenshots for all breakpoints`
|
|
22
|
+
|
|
23
|
+
## Configuration
|
|
24
|
+
|
|
25
|
+
Breakpoints are configured via:
|
|
26
|
+
- `DIFFY_BREAKPOINTS` environment variable, or
|
|
27
|
+
- `worldParameters.diffy.breakpoints` parameter
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
|
|
2
|
+
# Then send screenshots to diffy with name "value"
|
|
3
|
+
|
|
4
|
+
## Overview
|
|
5
|
+
This step definition uploads all captured screenshots to Diffy as a named custom snapshot. Upon successful execution, it clears both the in-memory buffer and on-disk screenshotsDir.
|
|
6
|
+
|
|
7
|
+
## Gherkin Pattern
|
|
8
|
+
```
|
|
9
|
+
Then (I |we )*send screenshots to diffy with name "([^"]*)"
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
## Examples
|
|
13
|
+
|
|
14
|
+
```
|
|
15
|
+
Then send screenshots to diffy with name "baseline"
|
|
16
|
+
Then send screenshots to diffy with name "changed"
|
|
17
|
+
Then send screenshots to diffy with name "homepage-release-2.0"
|
|
18
|
+
Then send screenshots to diffy with name "after-deploy"
|
|
19
|
+
Then send screenshots to diffy with name "smoke-run"
|
|
20
|
+
Then send screenshots to diffy with name "webship.co-prod"
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## Parameters
|
|
24
|
+
- **name** (required): A custom snapshot identifier string passed in quotes
|
|
25
|
+
|
|
26
|
+
## Functionality
|
|
27
|
+
The step captures all previously taken screenshots and uploads them to Diffy with the specified snapshot name. After successful upload, it automatically clears both the internal screenshot buffer and the local screenshots directory.
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
|
|
2
|
+
# Then upload folder "URL" to diffy as "snapshotName"
|
|
3
|
+
|
|
4
|
+
## Description
|
|
5
|
+
|
|
6
|
+
This step uploads all PNG and WebP images from a local directory to Diffy as a named custom snapshot. The breakpoint dimensions are extracted from image width metadata, while the URL slug is determined from the filename.
|
|
7
|
+
|
|
8
|
+
## Gherkin Pattern
|
|
9
|
+
|
|
10
|
+
```
|
|
11
|
+
Then (I |we )*upload folder "([^"]*)" to diffy as "([^"]*)"
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
## Examples
|
|
15
|
+
|
|
16
|
+
```gherkin
|
|
17
|
+
Then upload folder "./screenshots/baseline" to diffy as "baseline"
|
|
18
|
+
Then upload folder "./screenshots/changed" to diffy as "changed"
|
|
19
|
+
Then upload folder "./reports/screenshots" to diffy as "nightly"
|
|
20
|
+
Then upload folder "/tmp/webship-shots" to diffy as "webship.co-snapshot"
|
|
21
|
+
Then upload folder "./out/homepage" to diffy as "homepage-release-2.0"
|
|
22
|
+
Then upload folder "./diffy/before" to diffy as "before-deploy"
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
## Parameters
|
|
26
|
+
|
|
27
|
+
- **Folder Path**: Local directory containing PNG/WebP files (required)
|
|
28
|
+
- **Snapshot Name**: Label for the uploaded custom snapshot in Diffy (required)
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
|
|
2
|
+
# Then wait for diffy comparison to complete
|
|
3
|
+
|
|
4
|
+
## Description
|
|
5
|
+
|
|
6
|
+
This step polls the most recently created Diffy comparison until it reaches a terminal state. The default timeout is set to `DIFFY_MAX_WAIT` seconds, which defaults to 1200 seconds.
|
|
7
|
+
|
|
8
|
+
## Gherkin Syntax
|
|
9
|
+
|
|
10
|
+
```
|
|
11
|
+
Then (I |we )*wait for diffy comparison to complete
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
## Examples
|
|
15
|
+
|
|
16
|
+
- `Then wait for diffy comparison to complete`
|
|
17
|
+
- `And wait for diffy comparison to complete`
|
|
18
|
+
- `Then I wait for diffy comparison to complete`
|
|
19
|
+
- `Then we wait for diffy comparison to complete`
|
|
20
|
+
- `And I wait for diffy comparison to complete`
|
|
21
|
+
- `And we wait for diffy comparison to complete`
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
|
|
2
|
+
# When I resize window to "number"
|
|
3
|
+
|
|
4
|
+
## Step Definition
|
|
5
|
+
|
|
6
|
+
```
|
|
7
|
+
When(/^(?:I |we )?resize window to "([^"]*)")
|
|
8
|
+
```
|
|
9
|
+
|
|
10
|
+
## Description
|
|
11
|
+
|
|
12
|
+
"Resize browser viewport to a breakpoint width (plus Diffy window padding)."
|
|
13
|
+
|
|
14
|
+
## Examples
|
|
15
|
+
|
|
16
|
+
```
|
|
17
|
+
When I resize window to "1200"
|
|
18
|
+
When we resize window to "640"
|
|
19
|
+
When I resize window to "320"
|
|
20
|
+
When we resize window to "768"
|
|
21
|
+
When I resize window to "1024"
|
|
22
|
+
When we resize window to "1440"
|
|
23
|
+
When I resize window to "1920"
|
|
24
|
+
When we resize window to "375"
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
## Parameters
|
|
28
|
+
|
|
29
|
+
- `number`: The viewport width in pixels to resize the browser window to
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
|
|
2
|
+
# Diffy Step Definitions
|
|
3
|
+
|
|
4
|
+
## Overview
|
|
5
|
+
|
|
6
|
+
This documentation page describes Diffy Step Definitions for Webship JS 2.0.x. The feature enables opt-in visual-regression testing capabilities, allowing developers to capture full-page Playwright screenshots at multiple breakpoints and upload them to Diffy for comparison via REST API.
|
|
7
|
+
|
|
8
|
+
**Key characteristic:** "Kept in a separate folder (tests/step-definitions-diffy/) so the default npm test run does not load them."
|
|
9
|
+
|
|
10
|
+
## Available Step Definitions
|
|
11
|
+
|
|
12
|
+
- [Then I take screenshot](/docs/webship-js/2.0.x/diffy-step-definitions/then-i-take-screenshot)
|
|
13
|
+
- [Then I take screenshots for all breakpoints](/docs/webship-js/2.0.x/diffy-step-definitions/then-i-take-screenshots-all-breakpoints)
|
|
14
|
+
- [Then compare diffy "ENV1" with "ENV2"](/docs/webship-js/2.0.x/diffy-step-definitions/then-compare-diffy-env1-env2)
|
|
15
|
+
- [Then create diffy comparison](/docs/webship-js/2.0.x/diffy-step-definitions/then-create-diffy-comparison)
|
|
16
|
+
- [Then create diffy comparison with name "value"](/docs/webship-js/2.0.x/diffy-step-definitions/then-create-diffy-comparison-name-value)
|
|
17
|
+
- [Then create diffy screenshot from "environment name" environment](/docs/webship-js/2.0.x/diffy-step-definitions/then-create-diffy-screenshot-environment-name)
|
|
18
|
+
- [Then send screenshots to diffy with name "value"](/docs/webship-js/2.0.x/diffy-step-definitions/then-send-screenshots-diffy-name-value)
|
|
19
|
+
- [Then upload folder "URL" to diffy as "snapshotName"](/docs/webship-js/2.0.x/diffy-step-definitions/then-upload-folder-url-diffy-snapshotname)
|
|
20
|
+
- [Then wait for diffy comparison to complete](/docs/webship-js/2.0.x/diffy-step-definitions/then-wait-diffy-comparison-complete)
|
|
21
|
+
- [When I resize window to "number"](/docs/webship-js/2.0.x/diffy-step-definitions/when-i-resize-window-number)
|