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
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)