webship-js 2.0.2 → 2.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (162) hide show
  1. package/AGENTS.md +109 -0
  2. package/CLAUDE.md +317 -0
  3. package/bin/generate-reports.js +181 -9
  4. package/cucumber.js +10 -4
  5. package/docs/00-quick-start.md +102 -0
  6. package/docs/01-getting-started.md +102 -0
  7. package/docs/02-bbr-smart-waits.md +77 -0
  8. package/docs/03-selector-registry.md +95 -0
  9. package/docs/04-step-reference.md +728 -0
  10. package/docs/05-web-first-assertions.md +91 -0
  11. package/docs/06-network-and-dialogs.md +83 -0
  12. package/docs/07-auth-state.md +75 -0
  13. package/docs/08-clock-mocking.md +59 -0
  14. package/docs/09-api-testing.md +114 -0
  15. package/docs/10-accessibility.md +167 -0
  16. package/docs/11-debugging.md +129 -0
  17. package/docs/12-ai-agent-guide.md +338 -0
  18. package/docs/13-faq.md +236 -0
  19. package/docs/14-recipes-cookbook.md +255 -0
  20. package/docs/15-tag-conventions.md +76 -0
  21. package/docs/advanced-screenshots/then-i-save-fullscreen-screenshot.md +36 -0
  22. package/docs/advanced-screenshots/then-i-save-width-x-height-screenshot.md +34 -0
  23. package/docs/advanced-screenshots/when-i-save-screenshot-name-filename.md +45 -0
  24. package/docs/advanced-screenshots.md +52 -0
  25. package/docs/advanced-selectors.md +18 -0
  26. package/docs/api-step-definitions.md +45 -0
  27. package/docs/diffy-step-definitions/then-compare-diffy-env1-env2.md +30 -0
  28. package/docs/diffy-step-definitions/then-create-diffy-comparison-name-value.md +21 -0
  29. package/docs/diffy-step-definitions/then-create-diffy-comparison.md +25 -0
  30. package/docs/diffy-step-definitions/then-create-diffy-screenshot-environment-name.md +35 -0
  31. package/docs/diffy-step-definitions/then-i-take-screenshot.md +21 -0
  32. package/docs/diffy-step-definitions/then-i-take-screenshots-all-breakpoints.md +27 -0
  33. package/docs/diffy-step-definitions/then-send-screenshots-diffy-name-value.md +27 -0
  34. package/docs/diffy-step-definitions/then-upload-folder-url-diffy-snapshotname.md +28 -0
  35. package/docs/diffy-step-definitions/then-wait-diffy-comparison-complete.md +21 -0
  36. package/docs/diffy-step-definitions/when-i-resize-window-number.md +29 -0
  37. package/docs/diffy-step-definitions.md +21 -0
  38. package/docs/global-settings.md +244 -0
  39. package/docs/index.md +104 -0
  40. package/docs/install-webship-js/ddev-webship-js.md +52 -0
  41. package/docs/install-webship-js.md +35 -0
  42. package/docs/overview.md +41 -0
  43. package/docs/step-definitions/given-i-am-anonymous-user.md +67 -0
  44. package/docs/step-definitions/given-i-am-homepage.md +68 -0
  45. package/docs/step-definitions/given-i-am-specific-page.md +72 -0
  46. package/docs/step-definitions/then-i-should-be.md +56 -0
  47. package/docs/step-definitions/then-i-should-see.md +62 -0
  48. package/docs/step-definitions/then-item-checkbox.md +54 -0
  49. package/docs/step-definitions/then-item-link-should-contain-url.md +84 -0
  50. package/docs/step-definitions/then-item-should-contain.md +67 -0
  51. package/docs/step-definitions/then-radio-button-value-should-be-selected.md +68 -0
  52. package/docs/step-definitions/then-response-status-code-should-be-number.md +69 -0
  53. package/docs/step-definitions/then-value-radio-button-selected.md +62 -0
  54. package/docs/step-definitions/when-i-attach-file-file-name-element.md +71 -0
  55. package/docs/step-definitions/when-i-check-checkbox.md +60 -0
  56. package/docs/step-definitions/when-i-click-link.md +51 -0
  57. package/docs/step-definitions/when-i-click-operation-text-row.md +71 -0
  58. package/docs/step-definitions/when-i-fill.md +59 -0
  59. package/docs/step-definitions/when-i-go-homepage.md +60 -0
  60. package/docs/step-definitions/when-i-go-specific-page.md +67 -0
  61. package/docs/step-definitions/when-i-move-backward-one-page.md +49 -0
  62. package/docs/step-definitions/when-i-move-forward-one-page.md +58 -0
  63. package/docs/step-definitions/when-i-press-button.md +58 -0
  64. package/docs/step-definitions/when-i-reload-page.md +51 -0
  65. package/docs/step-definitions/when-i-scroll.md +73 -0
  66. package/docs/step-definitions/when-i-select-option-select-list.md +53 -0
  67. package/docs/step-definitions/when-i-select-radio-button-value.md +62 -0
  68. package/docs/step-definitions/when-i-uncheck-checkbox.md +57 -0
  69. package/docs/step-definitions/when-i-wait-ajax-finish.md +64 -0
  70. package/docs/step-definitions/when-i-wait.md +62 -0
  71. package/docs/step-definitions.md +50 -0
  72. package/examples/a11y.html +31 -0
  73. package/examples/cookies.html +10 -0
  74. package/examples/date.html +12 -0
  75. package/examples/element.html +11 -0
  76. package/examples/field.html +24 -0
  77. package/examples/keyboard.html +11 -0
  78. package/examples/links.html +9 -0
  79. package/examples/modal.html +14 -0
  80. package/examples/path.html +3 -0
  81. package/examples/table.html +13 -0
  82. package/package.json +10 -3
  83. package/playwright.config.ts +3 -2
  84. package/tests/features/a11y.feature +39 -0
  85. package/tests/features/cookie.feature +13 -0
  86. package/tests/features/date.feature +11 -0
  87. package/tests/features/element.feature +16 -0
  88. package/tests/features/field.feature +25 -0
  89. package/tests/features/keyboard.feature +10 -0
  90. package/tests/features/link.feature +11 -0
  91. package/tests/features/modal-advanced-example.feature +1 -1
  92. package/tests/features/modal.feature +11 -0
  93. package/tests/features/path.feature +16 -0
  94. package/tests/features/response.feature +8 -0
  95. package/tests/features/responsive.feature +10 -0
  96. package/tests/features/table.feature +18 -0
  97. package/tests/features/wait.feature +7 -0
  98. package/tests/features/yaml.feature +102 -0
  99. package/tests/reports/README.md +55 -0
  100. package/tests/selectors/_canonical-keys.json +113 -0
  101. package/tests/selectors/back-end-selectors.json +7 -1
  102. package/tests/selectors/cms-contentful-admin.json +35 -0
  103. package/tests/selectors/cms-craft-admin.json +39 -0
  104. package/tests/selectors/cms-drupal-cms-gin.json +56 -0
  105. package/tests/selectors/cms-drupal-core-claro.json +50 -0
  106. package/tests/selectors/cms-generic-admin.json +34 -0
  107. package/tests/selectors/cms-ghost-admin.json +34 -0
  108. package/tests/selectors/cms-joomla-admin.json +41 -0
  109. package/tests/selectors/cms-magento2-admin.json +32 -0
  110. package/tests/selectors/cms-prestashop-admin.json +38 -0
  111. package/tests/selectors/cms-shopify-admin.json +25 -0
  112. package/tests/selectors/cms-strapi-admin.json +42 -0
  113. package/tests/selectors/cms-typo3-admin.json +41 -0
  114. package/tests/selectors/cms-woocommerce-front.json +50 -0
  115. package/tests/selectors/cms-wordpress-admin.json +31 -0
  116. package/tests/selectors/framework-ant-design.json +80 -0
  117. package/tests/selectors/framework-bootstrap.json +86 -0
  118. package/tests/selectors/framework-bulma.json +74 -0
  119. package/tests/selectors/framework-chakra.json +58 -0
  120. package/tests/selectors/framework-foundation.json +51 -0
  121. package/tests/selectors/framework-material-ui.json +72 -0
  122. package/tests/selectors/framework-shadcn.json +51 -0
  123. package/tests/selectors/framework-tailwind.json +40 -0
  124. package/tests/selectors/framework-vuetify.json +61 -0
  125. package/tests/step-definitions/a11y.steps.js +798 -0
  126. package/tests/step-definitions/action.steps.js +167 -0
  127. package/tests/step-definitions/{webship-api.js → api.steps.js} +24 -7
  128. package/tests/step-definitions/assertion.steps.js +352 -0
  129. package/tests/step-definitions/auth.steps.js +124 -0
  130. package/tests/step-definitions/clock.steps.js +128 -0
  131. package/tests/step-definitions/cookie.steps.js +216 -0
  132. package/tests/step-definitions/debug.steps.js +31 -0
  133. package/tests/step-definitions/dialog.steps.js +193 -0
  134. package/tests/step-definitions/element.steps.js +314 -0
  135. package/tests/step-definitions/field.steps.js +653 -0
  136. package/tests/step-definitions/file-download.steps.js +193 -0
  137. package/tests/step-definitions/form.steps.js +333 -0
  138. package/tests/step-definitions/iframe.steps.js +178 -0
  139. package/tests/step-definitions/input.steps.js +163 -0
  140. package/tests/step-definitions/javascript.steps.js +71 -0
  141. package/tests/step-definitions/keyboard.steps.js +78 -0
  142. package/tests/step-definitions/link.steps.js +142 -0
  143. package/tests/step-definitions/metatag.steps.js +91 -0
  144. package/tests/step-definitions/modal.steps.js +219 -0
  145. package/tests/step-definitions/navigation.steps.js +218 -0
  146. package/tests/step-definitions/network.steps.js +238 -0
  147. package/tests/step-definitions/path.steps.js +141 -0
  148. package/tests/step-definitions/response.steps.js +98 -0
  149. package/tests/step-definitions/responsive.steps.js +123 -0
  150. package/tests/step-definitions/rest.steps.js +111 -0
  151. package/tests/step-definitions/{webship-screenshot.js → screenshot.steps.js} +1 -5
  152. package/tests/step-definitions/scroll.steps.js +189 -0
  153. package/tests/step-definitions/{webship-selectors.js → selectors.steps.js} +46 -11
  154. package/tests/step-definitions/storage.steps.js +194 -0
  155. package/tests/step-definitions/table.steps.js +181 -0
  156. package/tests/step-definitions/wait.steps.js +400 -0
  157. package/tests/step-definitions/web-first.steps.js +296 -0
  158. package/tests/step-definitions/webship.js +552 -1507
  159. package/tests/step-definitions/xml.steps.js +409 -0
  160. package/tests/step-definitions/yaml.steps.js +911 -0
  161. package/tests/step-definitions-diffy/webship-diffy.js +0 -13
  162. package/tsconfig.json +19 -3
@@ -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)
@@ -0,0 +1,244 @@
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
+ ### `diffy` — visual-diff integration (optional)
140
+
141
+ ```js
142
+ diffy: {
143
+ apiKey: 'mock-key',
144
+ projectId: 1,
145
+ breakpoints: '640,1200',
146
+ windowHeight: 2000,
147
+ screenshotsDir: '',
148
+ baseUrl: 'http://127.0.0.1:3099/',
149
+ maxWait: 30,
150
+ env1Url: '',
151
+ env2Url: '',
152
+ }
153
+ ```
154
+
155
+ | Key | Default | Env override |
156
+ | --- | --- | --- |
157
+ | `apiKey` | `mock-key` | `DIFFY_API_KEY` |
158
+ | `projectId` | `1` | `DIFFY_PROJECT_ID` |
159
+ | `breakpoints` | `640,1200` | `DIFFY_BREAKPOINTS` |
160
+ | `windowHeight` | `2000` | `DIFFY_WINDOW_HEIGHT` |
161
+ | `screenshotsDir` | `''` | `DIFFY_SCREENSHOTS_DIR` |
162
+ | `baseUrl` | mock server | `DIFFY_API_BASE_URL` |
163
+ | `maxWait` | `30` (seconds) | `DIFFY_MAX_WAIT` |
164
+ | `env1Url` | `''` | `DIFFY_ENV1_URL` |
165
+ | `env2Url` | `''` | `DIFFY_ENV2_URL` |
166
+
167
+ ---
168
+
169
+ ## `playwright.config.ts` — browser launch
170
+
171
+ ```ts
172
+ const config = {
173
+ browser: process.env.BROWSER || 'chromium',
174
+ launchOptions: {
175
+ headless: process.env.HEADLESS !== 'false',
176
+ slowMo: parseInt(process.env.SLOW_MO || '300', 10),
177
+ args: [...],
178
+ },
179
+ contextOptions: {
180
+ viewport: null,
181
+ ignoreHTTPSErrors: true,
182
+ },
183
+ };
184
+ ```
185
+
186
+ | Key | Default | Env override |
187
+ | --- | --- | --- |
188
+ | `browser` | `chromium` | `BROWSER` (`chromium` / `firefox` / `webkit`) |
189
+ | `launchOptions.headless` | `true` | `HEADLESS=false` for headed |
190
+ | `launchOptions.slowMo` | `300` headed: `800` | `SLOW_MO` (ms) |
191
+ | `launchOptions.args` | chromium-only flags | edit file directly |
192
+ | `contextOptions.viewport` | `null` (use browser default) | edit file directly |
193
+ | `contextOptions.ignoreHTTPSErrors` | `true` | edit file directly |
194
+
195
+ ---
196
+
197
+ ## Behaviour toggles
198
+
199
+ | Env var | Effect |
200
+ | --- | --- |
201
+ | `WEBSHIP_AUTO_SETTLE` | Set to `off` to disable the BBR auto-settle hook (`smartSettle(page, 1500)` after every state-changing step). |
202
+ | `WEBSHIP_REPORT_DISABLE` | Set to `1` to skip auto-generating the HTML report on cucumber-js process exit. |
203
+ | `WEBSHIP_REPORT_ARGS` | Extra CLI flags forwarded to `bin/generate-reports.js`. e.g. `--theme hierarchy --layout 2`. |
204
+
205
+ ---
206
+
207
+ ## Run / pacing env vars
208
+
209
+ | Env var | Default | Effect |
210
+ | --- | --- | --- |
211
+ | `LAUNCH_URL` | `http://localhost:8080` | Base URL for navigation steps. |
212
+ | `BROWSER` | `chromium` | Browser engine. |
213
+ | `HEADLESS` | `true` | `false` opens a visible browser. |
214
+ | `SLOW_MO` | `300` (headed: `800`) | Per-action delay (ms). Set to `0` for fast runs. |
215
+
216
+ ---
217
+
218
+ ## npm scripts
219
+
220
+ | Script | Description |
221
+ | --- | --- |
222
+ | `npm test` | Default profile, full pretty output, slow-mo on. |
223
+ | `npm run test:headed` | `HEADLESS=false`. Watches the browser. |
224
+ | `npm run test:fast` | `SLOW_MO=0` on the default profile. |
225
+ | `npm run test:chromium` | `BROWSER=chromium npm test`. |
226
+ | `npm run test:firefox` | `BROWSER=firefox npm test`. |
227
+ | `npm run test:webkit` | `BROWSER=webkit npm test`. |
228
+ | `npm start` | Static dev server on port 8080 (`http-server examples`). |
229
+ | `npm run generate-reports` | Manually rebuild the HTML report from the JSON output. |
230
+
231
+ ---
232
+
233
+ ## Recipe — typical CI lane
234
+
235
+ ```bash
236
+ LAUNCH_URL=https://staging.example.com \
237
+ SLOW_MO=0 \
238
+ BROWSER=chromium \
239
+ WEBSHIP_SCREENSHOT_PURGE=1 \
240
+ npx cucumber-js --tags "@critical and not @wip" --parallel 4 --retry 1 --retry-tag-filter @flaky
241
+ ```
242
+
243
+ Translation: zero slow-mo, 4 parallel processes, retry `@flaky` once,
244
+ fresh `screenshots/` each run, only `@critical` (excluding work-in-progress).
package/docs/index.md ADDED
@@ -0,0 +1,104 @@
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
+ ## Reading order
6
+
7
+ ### Webship-js essentials (custom)
8
+
9
+ | Doc | Topic |
10
+ | --- | --- |
11
+ | [00 Quick start](00-quick-start.md) | 5-minute path for newcomers |
12
+ | [01 Getting started](01-getting-started.md) | Install, project layout, run modes |
13
+ | [02 BBR smart waits](02-bbr-smart-waits.md) | Why we never `sleep N seconds` |
14
+ | [03 Selector registry](03-selector-registry.md) | Named selectors + CMS / framework presets |
15
+ | [04 Step reference](04-step-reference.md) | Every built-in step, by topic |
16
+ | [05 Web-first assertions](05-web-first-assertions.md) | Auto-retrying matchers |
17
+ | [06 Networking & dialogs](06-network-and-dialogs.md) | Request mocking, alerts, prompts |
18
+ | [07 Auth state](07-auth-state.md) | Save / restore login |
19
+ | [08 Clock mocking](08-clock-mocking.md) | Control time |
20
+ | [09 API testing](09-api-testing.md) | Direct HTTP from BDD |
21
+ | [10 Accessibility](10-accessibility.md) | POUR smoke checks |
22
+ | [11 Debugging](11-debugging.md) | Screenshots, headed, traces, reports |
23
+ | [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) |
24
+ | [13 FAQ](13-faq.md) | Common questions for newcomers |
25
+ | [14 Recipes cookbook](14-recipes-cookbook.md) | 20 paste-and-go scenarios |
26
+ | [15 Tag conventions](15-tag-conventions.md) | Standard tags + CI lane patterns |
27
+
28
+ ### Reference (mirrored from webship.co/docs/webship-js/2.0.x)
29
+
30
+ | Doc | Topic |
31
+ | --- | --- |
32
+ | [Overview](overview.md) | Webship-js v2.0.x at a glance |
33
+ | [Install](install-webship-js.md) | Install Webship-js |
34
+ | [Install — DDEV](install-webship-js/ddev-webship-js.md) | DDEV-Webship-js variant |
35
+ | [Global settings](global-settings.md) | `cucumber.js` `worldParameters` reference |
36
+ | [Commands](commands.md) | CLI commands |
37
+ | [Assertions](assertions.md) | Built-in assertions |
38
+ | [Step definitions](step-definitions.md) | Step-definition catalogue (28 sub-pages under `step-definitions/`) |
39
+ | [API step definitions](api-step-definitions.md) | REST step definitions |
40
+ | [Advanced screenshots](advanced-screenshots.md) | Per-size, full-page, named (3 sub-pages under `advanced-screenshots/`) |
41
+ | [Advanced selectors](advanced-selectors.md) | Named selector registry, position assertions |
42
+ | [Diffy step definitions](diffy-step-definitions.md) | Visual-diff workflow (10 sub-pages under `diffy-step-definitions/`) |
43
+
44
+ ## At a glance
45
+
46
+ ```gherkin
47
+ Feature: Smoke
48
+
49
+ Background:
50
+ Given I restore the auth state from "tests/auth/admin.json"
51
+
52
+ @javascript
53
+ Scenario: Dashboard renders without JS errors
54
+ Given I am on "/dashboard"
55
+ And I wait until the network is idle
56
+ Then the page should have a main landmark
57
+ And "<#user-list>" should have a count of 5 within 5 seconds
58
+ And "<.notification>" should not be visible
59
+ ```
60
+
61
+ ## Source layout
62
+
63
+ ```
64
+ webship-js/
65
+ ├── docs/ <— You are here
66
+ ├── tests/
67
+ │ ├── features/ <— Your *.feature files
68
+ │ ├── selectors/ <— CMS / framework JSON presets
69
+ │ └── step-definitions/ <— Built-in steps (auto-loaded)
70
+ │ ├── webship.js # World setup, hooks, shared helpers (smartSettle, modal, selectors)
71
+ │ ├── navigation.steps.js # homepage / paths / history / URL assertions
72
+ │ ├── action.steps.js # press, click, follow, attach
73
+ │ ├── form.steps.js # fill, select, check, radio
74
+ │ ├── assertion.steps.js # see / not see, in row, in element, response, count
75
+ │ ├── api.steps.js # REST API steps
76
+ │ ├── screenshot.steps.js # Screenshot hooks
77
+ │ ├── selectors.steps.js # Named selector registry
78
+ │ ├── wait.steps.js # All wait phrasings (BBR)
79
+ │ ├── web-first.steps.js # Auto-retrying matchers
80
+ │ ├── auth.steps.js # Auth state save/restore
81
+ │ ├── clock.steps.js # Time mocking
82
+ │ ├── network.steps.js # Route stubs / blocks / delays
83
+ │ ├── dialog.steps.js # alert/confirm/prompt
84
+ │ ├── a11y.steps.js # Accessibility smoke checks
85
+ │ ├── javascript.steps.js # JS error tracking
86
+ │ ├── element.steps.js # Element interactions
87
+ │ ├── field.steps.js # Form field assertions
88
+ │ ├── cookie.steps.js # Cookie helpers
89
+ │ ├── modal.steps.js # Modal helpers
90
+ │ ├── keyboard.steps.js # Key press steps
91
+ │ ├── link.steps.js # Link assertions
92
+ │ ├── path.steps.js # URL path assertions
93
+ │ ├── response.steps.js # Response header inspection
94
+ │ ├── responsive.steps.js # Viewport breakpoints
95
+ │ ├── table.steps.js # Table assertions
96
+ │ ├── metatag.steps.js # <meta> assertions
97
+ │ ├── iframe.steps.js # Iframe context steps
98
+ │ ├── file-download.steps.js # Download capture
99
+ │ ├── rest.steps.js # REST helpers
100
+ │ └── xml.steps.js # XML body assertions
101
+ ├── examples/ <— Static HTML fixtures
102
+ ├── cucumber.js <— Profiles + worldParameters
103
+ └── playwright.config.ts <— Browser launch + context options
104
+ ```
@@ -0,0 +1,52 @@
1
+
2
+ # DDEV Webship-JS
3
+
4
+ ## Overview
5
+
6
+ This add-on integrates "Webship-JS — a Playwright + Cucumber-JS Automated Functional Acceptance Testing framework" into DDEV projects, enabling automated browser testing via Gherkin `.feature` files within the DDEV environment.
7
+
8
+ ## Installation
9
+
10
+ Execute the command to add and configure the tool:
11
+
12
+ ```
13
+ ddev add-on get webship/ddev-webship-js
14
+ ```
15
+
16
+ The installation automatically scaffolds required configuration files, creates a starter feature file, installs Playwright browsers, and restarts the DDEV environment.
17
+
18
+ ### Install Dependencies
19
+
20
+ **Using npm:**
21
+ ```
22
+ ddev npm install
23
+ ```
24
+
25
+ **Using yarn:**
26
+ ```
27
+ ddev yarn install
28
+ ```
29
+
30
+ ## Running Tests
31
+
32
+ ### With npm
33
+
34
+ ```
35
+ ddev npm run test:chromium # Run all tests with Chromium
36
+ ddev npm run test:firefox # Run all tests with Firefox
37
+ ddev npm run test:webkit # Run all tests with WebKit
38
+ ```
39
+
40
+ ### With yarn
41
+
42
+ ```
43
+ ddev yarn test:chromium # Run all tests with Chromium
44
+ ddev yarn test:firefox # Run all tests with Firefox
45
+ ddev yarn test:webkit # Run all tests with WebKit
46
+ ```
47
+
48
+ ### Running Specific Tests
49
+
50
+ ```
51
+ ddev exec npx cucumber-js --config cucumber.js tests/features/example.feature
52
+ ```
@@ -0,0 +1,35 @@
1
+
2
+ # Install Webship JS
3
+
4
+ **Install Webship-js on your project. Simply execute the following command:**
5
+
6
+ ```
7
+ npm add webship-js
8
+ ```
9
+
10
+ ## Automated Functional Acceptance Testing
11
+
12
+ ```
13
+ npm test
14
+ ```
15
+
16
+ ### Boost your site's success with automated testing
17
+
18
+ #### For Commercial Professional Support
19
+
20
+ [Contact Us](/contact)
21
+
22
+ ## Documentation Structure
23
+
24
+ The page is part of the Webship JS 2.0.x documentation section, which includes:
25
+
26
+ - Global Settings
27
+ - Step Definitions
28
+ - API Step Definitions
29
+ - Advanced Screenshots
30
+ - Advanced Selectors
31
+ - Diffy Step Definitions
32
+ - Assertions
33
+ - Commands
34
+
35
+ There is also a subsection on "[DDEV Webship-JS](/docs/webship-js/2.0.x/install-webship-js/ddev-webship-js)" available under the installation guide.
@@ -0,0 +1,41 @@
1
+
2
+ # Webship JS 2.0.x
3
+
4
+ Webship-js is an Automated Functional Acceptance Testing tool that streamlines end-to-end testing for web applications. It combines [Playwright](https://playwright.dev/) and [Cucumber-js](https://github.com/cucumber/cucumber-js) with custom step definitions.
5
+
6
+ ## Key Features
7
+
8
+ **Test Script Creation:** Users can write scenarios mimicking real user interactions:
9
+
10
+ ```gherkin
11
+ Feature: Login page
12
+ Scenario: Successful Login with Valid entries
13
+ Given I am on homepage
14
+ When I go to "login.html"
15
+ And I fill in "Username" with "Smith"
16
+ And I fill in "Password" with "1$34"
17
+ And I press "Login"
18
+ Then I should see "Welcome Smith"
19
+ ```
20
+
21
+ **Test Execution:** The tool automates test script execution and verifies outcomes against actual results.
22
+
23
+ **Test Data Management:** Functionality for defining and manipulating input data sets across different test scenarios.
24
+
25
+ **Reporting and Analysis:** Generates detailed reports with passed/failed cases and exception documentation.
26
+
27
+ ## Benefits
28
+
29
+ Webship-js offers "increased testing efficiency, reduced human error, improved test coverage, and faster time-to-market."
30
+
31
+ ## Documentation Sub-pages
32
+
33
+ - [Install Webship JS](/docs/webship-js/2.0.x/install-webship-js)
34
+ - [Global Settings](/docs/webship-js/2.0.x/global-settings)
35
+ - [Step Definitions](/docs/webship-js/2.0.x/step-definitions)
36
+ - [API Step Definitions](/docs/webship-js/2.0.x/api-step-definitions)
37
+ - [Advanced Screenshots](/docs/webship-js/2.0.x/advanced-screenshots)
38
+ - [Advanced Selectors](/docs/webship-js/2.0.x/advanced-selectors)
39
+ - [Diffy Step Definitions](/docs/webship-js/2.0.x/diffy-step-definitions)
40
+ - [Assertions](/docs/webship-js/2.0.x/assertions)
41
+ - [Commands](/docs/webship-js/2.0.x/commands)