webship-js 2.0.1 → 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 (194) hide show
  1. package/AGENTS.md +109 -0
  2. package/CLAUDE.md +317 -0
  3. package/bin/generate-reports.js +363 -0
  4. package/bin/init-webship.js +343 -0
  5. package/bin/postinstall.js +8 -74
  6. package/cucumber.js +66 -2
  7. package/docs/00-quick-start.md +102 -0
  8. package/docs/01-getting-started.md +102 -0
  9. package/docs/02-bbr-smart-waits.md +77 -0
  10. package/docs/03-selector-registry.md +95 -0
  11. package/docs/04-step-reference.md +728 -0
  12. package/docs/05-web-first-assertions.md +91 -0
  13. package/docs/06-network-and-dialogs.md +83 -0
  14. package/docs/07-auth-state.md +75 -0
  15. package/docs/08-clock-mocking.md +59 -0
  16. package/docs/09-api-testing.md +114 -0
  17. package/docs/10-accessibility.md +167 -0
  18. package/docs/11-debugging.md +129 -0
  19. package/docs/12-ai-agent-guide.md +338 -0
  20. package/docs/13-faq.md +236 -0
  21. package/docs/14-recipes-cookbook.md +255 -0
  22. package/docs/15-tag-conventions.md +76 -0
  23. package/docs/advanced-screenshots/then-i-save-fullscreen-screenshot.md +36 -0
  24. package/docs/advanced-screenshots/then-i-save-width-x-height-screenshot.md +34 -0
  25. package/docs/advanced-screenshots/when-i-save-screenshot-name-filename.md +45 -0
  26. package/docs/advanced-screenshots.md +52 -0
  27. package/docs/advanced-selectors.md +18 -0
  28. package/docs/api-step-definitions.md +45 -0
  29. package/docs/diffy-step-definitions/then-compare-diffy-env1-env2.md +30 -0
  30. package/docs/diffy-step-definitions/then-create-diffy-comparison-name-value.md +21 -0
  31. package/docs/diffy-step-definitions/then-create-diffy-comparison.md +25 -0
  32. package/docs/diffy-step-definitions/then-create-diffy-screenshot-environment-name.md +35 -0
  33. package/docs/diffy-step-definitions/then-i-take-screenshot.md +21 -0
  34. package/docs/diffy-step-definitions/then-i-take-screenshots-all-breakpoints.md +27 -0
  35. package/docs/diffy-step-definitions/then-send-screenshots-diffy-name-value.md +27 -0
  36. package/docs/diffy-step-definitions/then-upload-folder-url-diffy-snapshotname.md +28 -0
  37. package/docs/diffy-step-definitions/then-wait-diffy-comparison-complete.md +21 -0
  38. package/docs/diffy-step-definitions/when-i-resize-window-number.md +29 -0
  39. package/docs/diffy-step-definitions.md +21 -0
  40. package/docs/global-settings.md +244 -0
  41. package/docs/index.md +104 -0
  42. package/docs/install-webship-js/ddev-webship-js.md +52 -0
  43. package/docs/install-webship-js.md +35 -0
  44. package/docs/overview.md +41 -0
  45. package/docs/step-definitions/given-i-am-anonymous-user.md +67 -0
  46. package/docs/step-definitions/given-i-am-homepage.md +68 -0
  47. package/docs/step-definitions/given-i-am-specific-page.md +72 -0
  48. package/docs/step-definitions/then-i-should-be.md +56 -0
  49. package/docs/step-definitions/then-i-should-see.md +62 -0
  50. package/docs/step-definitions/then-item-checkbox.md +54 -0
  51. package/docs/step-definitions/then-item-link-should-contain-url.md +84 -0
  52. package/docs/step-definitions/then-item-should-contain.md +67 -0
  53. package/docs/step-definitions/then-radio-button-value-should-be-selected.md +68 -0
  54. package/docs/step-definitions/then-response-status-code-should-be-number.md +69 -0
  55. package/docs/step-definitions/then-value-radio-button-selected.md +62 -0
  56. package/docs/step-definitions/when-i-attach-file-file-name-element.md +71 -0
  57. package/docs/step-definitions/when-i-check-checkbox.md +60 -0
  58. package/docs/step-definitions/when-i-click-link.md +51 -0
  59. package/docs/step-definitions/when-i-click-operation-text-row.md +71 -0
  60. package/docs/step-definitions/when-i-fill.md +59 -0
  61. package/docs/step-definitions/when-i-go-homepage.md +60 -0
  62. package/docs/step-definitions/when-i-go-specific-page.md +67 -0
  63. package/docs/step-definitions/when-i-move-backward-one-page.md +49 -0
  64. package/docs/step-definitions/when-i-move-forward-one-page.md +58 -0
  65. package/docs/step-definitions/when-i-press-button.md +58 -0
  66. package/docs/step-definitions/when-i-reload-page.md +51 -0
  67. package/docs/step-definitions/when-i-scroll.md +73 -0
  68. package/docs/step-definitions/when-i-select-option-select-list.md +53 -0
  69. package/docs/step-definitions/when-i-select-radio-button-value.md +62 -0
  70. package/docs/step-definitions/when-i-uncheck-checkbox.md +57 -0
  71. package/docs/step-definitions/when-i-wait-ajax-finish.md +64 -0
  72. package/docs/step-definitions/when-i-wait.md +62 -0
  73. package/docs/step-definitions.md +50 -0
  74. package/examples/a11y.html +31 -0
  75. package/examples/cookies.html +10 -0
  76. package/examples/date.html +12 -0
  77. package/examples/diffy/baseline.html +54 -0
  78. package/examples/diffy/changed.html +63 -0
  79. package/examples/diffy/index.html +52 -0
  80. package/examples/element.html +11 -0
  81. package/examples/field.html +24 -0
  82. package/examples/index.html +6 -0
  83. package/examples/keyboard.html +11 -0
  84. package/examples/links.html +9 -0
  85. package/examples/modal.html +14 -0
  86. package/examples/path.html +3 -0
  87. package/examples/table.html +13 -0
  88. package/examples/test--when--i-additionally-select.html +27 -0
  89. package/package.json +19 -6
  90. package/playwright.config.ts +3 -2
  91. package/tests/features/a11y.feature +39 -0
  92. package/tests/features/cookie.feature +13 -0
  93. package/tests/features/date.feature +11 -0
  94. package/tests/features/diffy/test--diffy-01-example-demo.feature +22 -0
  95. package/tests/features/diffy/test--diffy-02-all-steps.feature +52 -0
  96. package/tests/features/diffy/test--diffy-03-real-api.feature +21 -0
  97. package/tests/features/element.feature +16 -0
  98. package/tests/features/field.feature +25 -0
  99. package/tests/features/keyboard.feature +10 -0
  100. package/tests/features/link.feature +11 -0
  101. package/tests/features/modal-advanced-example.feature +1 -1
  102. package/tests/features/modal.feature +11 -0
  103. package/tests/features/path.feature +16 -0
  104. package/tests/features/response.feature +8 -0
  105. package/tests/features/responsive.feature +10 -0
  106. package/tests/features/table.feature +18 -0
  107. package/tests/features/test--then--i-save-screenshot.feature +33 -0
  108. package/tests/features/test--then--i-see-locator.feature +320 -0
  109. package/tests/features/test--then--i-should-see-n-elements.feature +24 -0
  110. package/tests/features/test--then--print-current-url-and-response.feature +21 -0
  111. package/tests/features/test--when--i-additionally-select.feature +30 -0
  112. package/tests/features/test--when--i-follow.feature +22 -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 +19 -0
  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/selectors/front-end-selectors.json +16 -0
  142. package/tests/selectors/homepage-selectors.json +13 -0
  143. package/tests/step-definitions/a11y.steps.js +798 -0
  144. package/tests/step-definitions/action.steps.js +167 -0
  145. package/tests/step-definitions/{webship-api.js → api.steps.js} +254 -44
  146. package/tests/step-definitions/assertion.steps.js +352 -0
  147. package/tests/step-definitions/auth.steps.js +124 -0
  148. package/tests/step-definitions/clock.steps.js +128 -0
  149. package/tests/step-definitions/cookie.steps.js +216 -0
  150. package/tests/step-definitions/debug.steps.js +31 -0
  151. package/tests/step-definitions/dialog.steps.js +193 -0
  152. package/tests/step-definitions/element.steps.js +314 -0
  153. package/tests/step-definitions/field.steps.js +653 -0
  154. package/tests/step-definitions/file-download.steps.js +193 -0
  155. package/tests/step-definitions/form.steps.js +333 -0
  156. package/tests/step-definitions/iframe.steps.js +178 -0
  157. package/tests/step-definitions/input.steps.js +163 -0
  158. package/tests/step-definitions/javascript.steps.js +71 -0
  159. package/tests/step-definitions/keyboard.steps.js +78 -0
  160. package/tests/step-definitions/link.steps.js +142 -0
  161. package/tests/step-definitions/metatag.steps.js +91 -0
  162. package/tests/step-definitions/modal.steps.js +219 -0
  163. package/tests/step-definitions/navigation.steps.js +218 -0
  164. package/tests/step-definitions/network.steps.js +238 -0
  165. package/tests/step-definitions/path.steps.js +141 -0
  166. package/tests/step-definitions/response.steps.js +98 -0
  167. package/tests/step-definitions/responsive.steps.js +123 -0
  168. package/tests/step-definitions/rest.steps.js +111 -0
  169. package/tests/step-definitions/screenshot.steps.js +423 -0
  170. package/tests/step-definitions/scroll.steps.js +189 -0
  171. package/tests/step-definitions/selectors.steps.js +996 -0
  172. package/tests/step-definitions/storage.steps.js +194 -0
  173. package/tests/step-definitions/table.steps.js +181 -0
  174. package/tests/step-definitions/wait.steps.js +400 -0
  175. package/tests/step-definitions/web-first.steps.js +296 -0
  176. package/tests/step-definitions/webship.js +567 -923
  177. package/tests/step-definitions/xml.steps.js +409 -0
  178. package/tests/step-definitions/yaml.steps.js +911 -0
  179. package/tests/step-definitions-diffy/README.md +329 -0
  180. package/tests/step-definitions-diffy/mock-diffy-api/server.js +84 -0
  181. package/tests/step-definitions-diffy/webship-diffy-mock.js +31 -0
  182. package/tests/step-definitions-diffy/webship-diffy.js +459 -0
  183. package/tsconfig.json +19 -3
  184. package/generate-reports.js +0 -22
  185. package/required/cucumber.js +0 -37
  186. package/required/generate-reports.js +0 -22
  187. package/required/package.json +0 -18
  188. package/required/playwright.config.ts +0 -37
  189. package/required/tests/features/README.md +0 -1
  190. package/required/tests/features/check-homepage.feature +0 -8
  191. package/required/tests/reports/README.md +0 -1
  192. package/required/tests/step-definitions/README.md +0 -1
  193. package/required/tests/step-definitions/custom.js +0 -4
  194. package/required/tsconfig.json +0 -12
@@ -0,0 +1,329 @@
1
+ # Diffy step definitions (opt-in)
2
+
3
+ Captures screenshots with Playwright and uploads them to
4
+ [Diffy](https://diffy.website) for visual-regression comparison via the Diffy
5
+ REST API (`https://app.diffy.website/api/`).
6
+
7
+ Kept in a separate folder so the default `npm test` run does **not** load them.
8
+ Projects opt in only when they want visual-regression coverage.
9
+
10
+ ## Adopt Diffy in a webship-js test project
11
+
12
+ > New to webship-js in your own project? First install and wire it up using
13
+ > the official docs:
14
+ >
15
+ > - **Install Webship JS** — https://webship.co/docs/webship-js/2.0.x/install-webship-js
16
+ > - **Global Settings (`cucumber.js`)** — https://webship.co/docs/webship-js/2.0.x/global-settings
17
+ > - **Step Definitions** — https://webship.co/docs/webship-js/2.0.x/step-definitions
18
+ >
19
+ > Once webship-js is running in your project, the steps below add the Diffy
20
+ > layer on top.
21
+
22
+ The `tests/step-definitions-diffy/` folder ships with this repo — nothing to
23
+ copy. Projects opt in by loading it in `cucumber.js`.
24
+
25
+ No extra npm packages required: `webship-diffy.js` uses the existing `axios`
26
+ dependency plus Node 20+ built-ins (`FormData`, `Blob`, `fs`, `http`).
27
+
28
+ ### 1. Edit `cucumber.js` — load the Diffy step definitions
29
+
30
+ Uncomment the `tests/step-definitions-diffy/**/*.js` line in `require:` and
31
+ uncomment the `diffy` block inside `worldParameters` to set project defaults.
32
+
33
+ ```js
34
+ module.exports = {
35
+ default: {
36
+ timeout: 30000,
37
+ requireModule: ['ts-node/register'],
38
+ require: [
39
+ 'tests/step-definitions/**/*.js',
40
+ // 'tests/step-definitions-diffy/**/*.js', // diff
41
+ ],
42
+ paths: ['tests/features/**/*.feature'],
43
+ format: [
44
+ '@cucumber/pretty-formatter',
45
+ 'json:tests/reports/cucumber_report.json',
46
+ ],
47
+ formatOptions: {
48
+ colorsEnabled: true,
49
+ theme: {
50
+ 'feature keyword': ['bold', 'blue'],
51
+ 'feature name': ['blue', 'underline'],
52
+ 'feature description': ['blueBright'],
53
+ 'scenario keyword': ['bold', 'magenta'],
54
+ 'scenario name': ['magenta', 'underline'],
55
+ 'step keyword': ['bold', 'green'],
56
+ 'step text': ['greenBright', 'italic'],
57
+ },
58
+ },
59
+ worldParameters: {
60
+ launchUrl: process.env.LAUNCH_URL || 'http://localhost:8080',
61
+ minWaitTime: {
62
+ page: 3000,
63
+ before_scenario: 0,
64
+ after_scenario: 0,
65
+ before_step: 0,
66
+ after_step: 0,
67
+ },
68
+ // Diffy (optional). Env vars (DIFFY_API_KEY, DIFFY_PROJECT_ID, …)
69
+ // always override these values. Never commit a real apiKey — prefer env.
70
+ // diffy: {
71
+ // apiKey: '', // DIFFY_API_KEY
72
+ // projectId: '', // DIFFY_PROJECT_ID
73
+ // breakpoints: '640,1200', // DIFFY_BREAKPOINTS
74
+ // windowHeight: 2000, // DIFFY_WINDOW_HEIGHT
75
+ // screenshotsDir: '', // DIFFY_SCREENSHOTS_DIR
76
+ // baseUrl: 'https://app.diffy.website/api/', // DIFFY_API_BASE_URL
77
+ // maxWait: 1200, // DIFFY_MAX_WAIT (seconds)
78
+ // env1Url: '', // DIFFY_ENV1_URL (custom env)
79
+ // env2Url: '', // DIFFY_ENV2_URL (custom env)
80
+ // },
81
+ },
82
+ },
83
+ };
84
+ ```
85
+
86
+ ### 2. Create a Diffy project and collect credentials
87
+
88
+ - Sign up or log in at https://app.diffy.website
89
+ - Create a project (set base URL + breakpoints that match your tests)
90
+ - Note the numeric **project id** shown in the project URL/settings
91
+ - Copy an **API key** from https://app.diffy.website/#/keys
92
+
93
+ ### 3. Export Diffy env vars
94
+
95
+ Add to `.env`, CI secrets, or your shell:
96
+
97
+ ```bash
98
+ export DIFFY_API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
99
+ export DIFFY_PROJECT_ID="00000"
100
+ export DIFFY_BREAKPOINTS="640,1200" # must match project config
101
+ export DIFFY_WINDOW_HEIGHT="2000" # optional
102
+ export DIFFY_MAX_WAIT="1200" # optional, polling timeout (s)
103
+ ```
104
+
105
+ Or inline per run:
106
+
107
+ ```bash
108
+ DIFFY_API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" DIFFY_PROJECT_ID="00000" DIFFY_API_BASE_URL="https://app.diffy.website/api/" npm test
109
+ ```
110
+
111
+ **Do not commit keys.** Put them in `.env.local` (git-ignored), CI secrets
112
+ manager, or a vault. See the full variable table below for every supported
113
+ option.
114
+
115
+ ### 4. Write or copy a Diffy feature file
116
+
117
+ Start from a colocated example:
118
+
119
+ ```bash
120
+ cp tests/features/diffy/test--diffy-01-example-demo.feature \
121
+ tests/features/diffy/my-visual-regression.feature
122
+ ```
123
+
124
+ Edit it to list the pages you want compared. Keep the `@diffy` tag on each
125
+ scenario.
126
+
127
+ ### 5. Run
128
+
129
+ ```bash
130
+ # Run all features including Diffy scenarios.
131
+ npm test
132
+
133
+ # Run only Diffy-tagged scenarios.
134
+ npx cucumber-js --config cucumber.js --tags "@diffy"
135
+
136
+ # Diffy real-API subset (requires live key + allowed URLs in the project)
137
+ npx cucumber-js --config cucumber.js --tags "@diffy and @real-api"
138
+ ```
139
+
140
+ ### 6. CI hookup (optional)
141
+
142
+ Typical CI flow: run baseline on main → run candidate on PR branch →
143
+ `create diffy comparison with name "PR-<number>"` → fail job if the comparison
144
+ reports changes above your threshold. See the
145
+ [automation docs](https://docs.diffy.website/automation/overview) for worked
146
+ examples (GitHub Actions, CircleCI, Tugboat, Platform.sh).
147
+
148
+ ### Remove Diffy later (reversible)
149
+
150
+ ```bash
151
+ rm -rf tests/step-definitions-diffy
152
+ rm -rf tests/features/diffy
153
+ # then comment out or remove 'tests/step-definitions-diffy/**/*.js' in cucumber.js require:
154
+ ```
155
+
156
+ ## Environment variables
157
+
158
+ | Variable | Purpose | Default |
159
+ | ----------------------- | ------------------------------------------------------------ | ------------------------------------ |
160
+ | `DIFFY_API_KEY` | Diffy API key ([keys page](https://app.diffy.website/#/keys)) | *required* |
161
+ | `DIFFY_PROJECT_ID` | Diffy project id | *required* |
162
+ | `DIFFY_BREAKPOINTS` | Comma list of breakpoints, e.g. `"640,1200"` | `1200` |
163
+ | `DIFFY_WINDOW_HEIGHT` | Default viewport height | `2000` |
164
+ | `DIFFY_SCREENSHOTS_DIR` | On-disk copy of screenshots (debugging) | *unset* |
165
+ | `DIFFY_API_BASE_URL` | Override API base URL (useful for mocking) | `https://app.diffy.website/api/` |
166
+ | `DIFFY_MAX_WAIT` | Seconds to poll `diffs/{id}` before failing | `1200` |
167
+ | `DIFFY_ENV1_URL` | Custom env1 URL for `compare diffy "custom" with ...` | *unset* |
168
+ | `DIFFY_ENV2_URL` | Custom env2 URL for `compare diffy ... with "custom"` | *unset* |
169
+
170
+ ## Steps
171
+
172
+ | Step | Diffy API call |
173
+ |------|----------------|
174
+ | `When I resize window to "<px>"` | — (Playwright viewport) |
175
+ | `Then I take screenshot` | — (buffered in World) |
176
+ | `Then I take screenshots for all breakpoints` | — (loops `DIFFY_BREAKPOINTS`) |
177
+ | `Then send screenshots to diffy with name "<name>"` | `POST projects/{id}/create-custom-snapshot` |
178
+ | `Then create diffy comparison` | `POST projects/{id}/diffs` |
179
+ | `Then create diffy comparison with name "<name>"` | `POST projects/{id}/diffs` |
180
+ | `Then create diffy screenshot from "<env>" environment` | `POST projects/{id}/screenshots` |
181
+ | `Then compare diffy "<env1>" with "<env2>"` | `POST projects/{id}/compare` |
182
+ | `Then upload folder "<path>" to diffy as "<name>"` | `POST projects/{id}/create-custom-snapshot` (functional test) |
183
+ | `Then wait for diffy comparison to complete` | `GET diffs/{id}` (polling) |
184
+
185
+ ## Example
186
+
187
+ ```gherkin
188
+ @diffy
189
+ Feature: Visual regression
190
+ Scenario: Compare two pages across breakpoints
191
+ Given I am on "/"
192
+ Then I take screenshots for all breakpoints
193
+
194
+ Given I am on "/about-us"
195
+ Then I take screenshots for all breakpoints
196
+ Then send screenshots to diffy with name "baseline"
197
+
198
+ Given I am on "/"
199
+ When I resize window to "1200"
200
+ Then I take screenshot
201
+ Then send screenshots to diffy with name "feature-branch"
202
+
203
+ Then create diffy comparison with name "PR-42"
204
+ Then wait for diffy comparison to complete
205
+ ```
206
+
207
+ Run:
208
+
209
+ ```bash
210
+ export DIFFY_API_KEY=your-key
211
+ export DIFFY_PROJECT_ID=30542
212
+ export DIFFY_BREAKPOINTS="640,1200"
213
+ npm test
214
+ ```
215
+
216
+ ## Reference feature files
217
+
218
+ Located in `tests/features/diffy/`. All scenarios tagged `@diffy`.
219
+
220
+ | File | Purpose | Extra tag |
221
+ |------|---------|-----------|
222
+ | `test--diffy-01-example-demo.feature` | Canonical example using bundled `/diffy/baseline.html` + `/diffy/changed.html` | `@example` |
223
+ | `test--diffy-02-all-steps.feature` | Smoke test of every step definition | `@smoke` + sub-tags |
224
+ | `test--diffy-03-real-api.feature` | Minimal run against the real Diffy API | `@real-api` |
225
+
226
+ Bundled example pages live in `examples/diffy/baseline.html` and
227
+ `examples/diffy/changed.html` (with a local index at
228
+ `examples/diffy/index.html`). The `changed` page shows deliberate visual
229
+ regressions (palette shift, new badge, added section, pricing change) so
230
+ Diffy has real differences to report.
231
+
232
+ ---
233
+
234
+ ## Diffy links
235
+
236
+ ### Product
237
+ - Home — https://diffy.website
238
+ - Pricing — https://diffy.website/pricing
239
+ - Free-tier sign-up — https://app.diffy.website/#/register
240
+ - Sign-in — https://app.diffy.website
241
+ - API keys page — https://app.diffy.website/#/keys
242
+
243
+ ### Documentation home
244
+ - Docs — https://docs.diffy.website
245
+ - Welcome / IP allow-list — https://docs.diffy.website/features/welcome
246
+ - Legacy docs (outdated, kept for reference) — https://diffy.website/documentation
247
+
248
+ ### Features
249
+ - Playwright integration — https://docs.diffy.website/features/playwright-integration
250
+ - Figma comparison — https://docs.diffy.website/features/figma
251
+ - Mask and exclude regions — https://docs.diffy.website/features/mask-and-exclude
252
+ - JavaScript snippets — https://docs.diffy.website/features/javascript-snippets
253
+ - HTTP headers — https://docs.diffy.website/features/http-headers
254
+ - Cookies — https://docs.diffy.website/features/cookies
255
+ - CSS overrides — https://docs.diffy.website/features/css-overrides
256
+ - Mock content — https://docs.diffy.website/features/mock-content
257
+ - Tags — https://docs.diffy.website/features/tags
258
+ - Project-from-YAML — https://docs.diffy.website/features/configure-project-from-yaml-file
259
+ - Zapier / Jira / Trello / Basecamp — https://docs.diffy.website/features/zapier-integration-jira-trello-basecamp-integrations
260
+
261
+ ### Dealing with dynamic elements
262
+ - Overview — https://docs.diffy.website/features/dealing-with-dynamic-elements
263
+ - Freeze carousels / sliders — https://docs.diffy.website/features/dealing-with-dynamic-elements/freeze-carousels-sliders
264
+ - Cookie-policy popups — https://docs.diffy.website/features/dealing-with-dynamic-elements/cookies-policy-popups
265
+ - Misc JavaScript snippets — https://docs.diffy.website/features/dealing-with-dynamic-elements/misc-javascript-snippets
266
+
267
+ ### Bypass firewalls / protections
268
+ - Overview (Cloudfront / Akamai / Incapsula) — https://docs.diffy.website/features/bypass-protection-cloudfront-akamai-incapsula
269
+ - Akamai — https://docs.diffy.website/features/bypass-protection-cloudfront-akamai-incapsula/bypass-akamai-protection
270
+ - Imperva / Incapsula — https://docs.diffy.website/features/bypass-protection-cloudfront-akamai-incapsula/bypass-imperva-incapsula-protection
271
+
272
+ ### Local development
273
+ - Overview — https://docs.diffy.website/features/local-development
274
+ - DDEV add-on — https://docs.diffy.website/features/local-development/ddev-add-on
275
+ - Lando integration — https://docs.diffy.website/features/local-development/lando-integration
276
+ - Docksal — https://docs.diffy.website/features/local-development/docksal
277
+ - Standalone Docker container — https://docs.diffy.website/features/local-development/standalone-docker-container
278
+ - ngrok — https://docs.diffy.website/features/local-development/ngrok
279
+
280
+ ### CI / CD automation
281
+ - Automation overview — https://docs.diffy.website/automation/overview
282
+ - GitHub + Pantheon + CircleCI — https://docs.diffy.website/automation/github-pantheon-circleci
283
+ - GitHub + Pantheon + GitHub Actions — https://docs.diffy.website/automation/github-pantheon-github-actions
284
+ - GitHub + Tugboat — https://docs.diffy.website/automation/github-tugboat
285
+ - Platform.sh + GitHub Actions — https://docs.diffy.website/automation/platformsh-github-action
286
+
287
+ ### Tutorials
288
+ - Comparison review — https://docs.diffy.website/tutorials/comparison-review
289
+
290
+ ### Source code / packages
291
+ - diffy-cli (PHP, packaged as `diffy.phar`) — https://github.com/DiffyWebsite/diffy-cli
292
+ - diffy-cli releases — https://github.com/DiffyWebsite/diffy-cli/releases
293
+ - DiffyWebsite org — https://github.com/DiffyWebsite
294
+
295
+ ### Diffy REST API reference (endpoints used by these steps)
296
+
297
+ Base URL: `https://app.diffy.website/api/` (override with `DIFFY_API_BASE_URL`).
298
+
299
+ | Method | Path | Purpose |
300
+ |--------|------|---------|
301
+ | `POST` | `auth/key` | Exchange API key for a short-lived bearer token |
302
+ | `POST` | `projects` | Create a project |
303
+ | `POST` | `projects/{id}` | Update a project |
304
+ | `GET` | `projects/{id}` | Read project settings |
305
+ | `GET` | `projects` | List projects |
306
+ | `POST` | `projects/{id}/screenshots` | Trigger server-side screenshot run |
307
+ | `GET` | `projects/{id}/screenshots` | List snapshots |
308
+ | `POST` | `projects/{id}/create-custom-snapshot` | Upload custom PNGs (multipart) |
309
+ | `PUT` | `projects/{id}/set-base-line-set/{screenshotId}` | Promote snapshot to baseline |
310
+ | `POST` | `projects/{id}/diffs` | Create a diff between two snapshot ids |
311
+ | `POST` | `projects/{id}/compare` | Server-side env-to-env compare |
312
+ | `GET` | `projects/{id}/diffs?page=N` | List diffs |
313
+ | `GET` | `diffs/{id}` | Diff status + result |
314
+ | `GET` | `snapshots/{id}` | Snapshot detail |
315
+
316
+ All authenticated calls carry `Authorization: Bearer <token>`. The token comes
317
+ from `POST auth/key` with `{"key": "<DIFFY_API_KEY>"}` and is refreshed lazily
318
+ inside `webship-diffy.js`.
319
+
320
+ ### Diffy-side IPs (allow-list in CDN / firewall)
321
+
322
+ From [Welcome](https://docs.diffy.website/features/welcome):
323
+
324
+ - IPv4: `138.201.56.149`
325
+ - IPv6: `2a01:4f8:172:1189::2`
326
+
327
+ ### Support / contact
328
+ - Email — info@diffy.website
329
+ - Issue trackers: file bugs against the matching repo above (cli, behat, php, etc.)
@@ -0,0 +1,84 @@
1
+ 'use strict';
2
+
3
+ const http = require('http');
4
+
5
+ let server = null;
6
+ const PORT = 3099;
7
+ const HOST = '127.0.0.1';
8
+
9
+ function createMockServer() {
10
+ server = http.createServer((req, res) => {
11
+ let body = '';
12
+ req.on('data', chunk => { body += chunk; });
13
+ req.on('end', () => {
14
+ res.setHeader('Content-Type', 'application/json');
15
+ res.statusCode = 200;
16
+
17
+ const { method, url } = req;
18
+
19
+ // POST auth/key → bearer token
20
+ if (method === 'POST' && url.includes('auth/key')) {
21
+ res.end(JSON.stringify({ token: 'mock-diffy-token' }));
22
+ return;
23
+ }
24
+
25
+ // POST projects/{id}/create-custom-snapshot → snapshot id
26
+ if (method === 'POST' && url.includes('create-custom-snapshot')) {
27
+ res.end(JSON.stringify({ id: 1 }));
28
+ return;
29
+ }
30
+
31
+ // POST projects/{id}/screenshots → snapshot id
32
+ if (method === 'POST' && url.includes('/screenshots')) {
33
+ res.end(JSON.stringify({ id: 1 }));
34
+ return;
35
+ }
36
+
37
+ // POST projects/{id}/diffs → diff id
38
+ if (method === 'POST' && url.includes('/diffs')) {
39
+ res.end(JSON.stringify({ id: 1 }));
40
+ return;
41
+ }
42
+
43
+ // POST projects/{id}/compare → diff id
44
+ if (method === 'POST' && url.includes('/compare')) {
45
+ res.end(JSON.stringify({ id: 1 }));
46
+ return;
47
+ }
48
+
49
+ // GET diffs/{id} → state 2 = completed
50
+ if (method === 'GET' && url.includes('diffs/')) {
51
+ res.end(JSON.stringify({ id: 1, state: 2 }));
52
+ return;
53
+ }
54
+
55
+ res.statusCode = 404;
56
+ res.end(JSON.stringify({ error: 'mock: not found', url }));
57
+ });
58
+ });
59
+
60
+ return new Promise((resolve, reject) => {
61
+ server.listen(PORT, HOST, () => resolve(PORT));
62
+ server.on('error', err => {
63
+ if (err.code === 'EADDRINUSE') {
64
+ // Already running (leftover from previous run) — treat as success.
65
+ server = null;
66
+ resolve(PORT);
67
+ } else {
68
+ reject(err);
69
+ }
70
+ });
71
+ });
72
+ }
73
+
74
+ function stopMockServer() {
75
+ return new Promise(resolve => {
76
+ if (server) {
77
+ server.close(() => { server = null; resolve(); });
78
+ } else {
79
+ resolve();
80
+ }
81
+ });
82
+ }
83
+
84
+ module.exports = { createMockServer, stopMockServer, PORT, HOST };
@@ -0,0 +1,31 @@
1
+ 'use strict';
2
+
3
+ const { BeforeAll, AfterAll } = require('@cucumber/cucumber');
4
+ const fs = require('fs');
5
+ const path = require('path');
6
+ const { createMockServer, stopMockServer } = require('./mock-diffy-api/server');
7
+
8
+ // Minimal valid 1×1 white PNG (width=1 at bytes 16-19 for detectPngWidth)
9
+ const MOCK_PNG = Buffer.from(
10
+ 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk' +
11
+ 'YPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==',
12
+ 'base64'
13
+ );
14
+
15
+ const MOCK_FOLDERS = [
16
+ '/tmp/diffy-test-screenshots/baseline',
17
+ '/tmp/diffy-test-screenshots/feature',
18
+ ];
19
+
20
+ BeforeAll(async function () {
21
+ await createMockServer();
22
+
23
+ for (const folder of MOCK_FOLDERS) {
24
+ fs.mkdirSync(folder, { recursive: true });
25
+ fs.writeFileSync(path.join(folder, 'mock-screenshot.png'), MOCK_PNG);
26
+ }
27
+ });
28
+
29
+ AfterAll(async function () {
30
+ await stopMockServer();
31
+ });