webship-js 2.0.3 → 2.0.5

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 (213) 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 +53 -17
  9. package/CLAUDE.md +327 -105
  10. package/Jenkinsfile +54 -0
  11. package/azure-pipelines.yml +82 -0
  12. package/bamboo-specs/bamboo.yml +131 -0
  13. package/bin/init-webship.js +0 -13
  14. package/bin/postinstall.js +0 -0
  15. package/buildspec.yml +56 -0
  16. package/cloudbuild.yaml +49 -0
  17. package/codefresh.yml +77 -0
  18. package/cucumber.js +39 -14
  19. package/docs/00-quick-start.md +0 -0
  20. package/docs/01-getting-started.md +0 -0
  21. package/docs/02-bbr-smart-waits.md +0 -0
  22. package/docs/03-selector-registry.md +0 -0
  23. package/docs/04-step-reference.md +74 -3
  24. package/docs/05-web-first-assertions.md +0 -0
  25. package/docs/06-network-and-dialogs.md +0 -0
  26. package/docs/07-auth-state.md +0 -0
  27. package/docs/08-clock-mocking.md +0 -0
  28. package/docs/09-api-testing.md +0 -0
  29. package/docs/10-accessibility.md +0 -0
  30. package/docs/11-debugging.md +0 -0
  31. package/docs/12-ai-agent-guide.md +0 -0
  32. package/docs/13-faq.md +0 -0
  33. package/docs/14-recipes-cookbook.md +0 -0
  34. package/docs/15-tag-conventions.md +0 -0
  35. package/docs/16-ci-cd.md +879 -0
  36. package/docs/README.md +116 -0
  37. package/docs/advanced-screenshots/then-i-save-fullscreen-screenshot.md +0 -0
  38. package/docs/advanced-screenshots/then-i-save-width-x-height-screenshot.md +0 -0
  39. package/docs/advanced-screenshots/when-i-save-screenshot-name-filename.md +0 -0
  40. package/docs/advanced-screenshots.md +0 -0
  41. package/docs/advanced-selectors.md +0 -0
  42. package/docs/api-step-definitions.md +0 -0
  43. package/docs/global-settings.md +45 -22
  44. package/docs/install-webship-js/ddev-webship-js.md +0 -0
  45. package/docs/install-webship-js.md +0 -1
  46. package/docs/overview.md +0 -1
  47. package/docs/step-definitions/given-i-am-anonymous-user.md +0 -0
  48. package/docs/step-definitions/given-i-am-homepage.md +0 -0
  49. package/docs/step-definitions/given-i-am-specific-page.md +0 -0
  50. package/docs/step-definitions/then-i-should-be.md +0 -0
  51. package/docs/step-definitions/then-i-should-see.md +0 -0
  52. package/docs/step-definitions/then-item-checkbox.md +0 -0
  53. package/docs/step-definitions/then-item-link-should-contain-url.md +0 -0
  54. package/docs/step-definitions/then-item-should-contain.md +0 -0
  55. package/docs/step-definitions/then-radio-button-value-should-be-selected.md +0 -0
  56. package/docs/step-definitions/then-response-status-code-should-be-number.md +0 -0
  57. package/docs/step-definitions/then-value-radio-button-selected.md +0 -0
  58. package/docs/step-definitions/when-i-attach-file-file-name-element.md +0 -0
  59. package/docs/step-definitions/when-i-check-checkbox.md +0 -0
  60. package/docs/step-definitions/when-i-click-link.md +0 -0
  61. package/docs/step-definitions/when-i-click-operation-text-row.md +0 -0
  62. package/docs/step-definitions/when-i-fill.md +0 -0
  63. package/docs/step-definitions/when-i-go-homepage.md +0 -0
  64. package/docs/step-definitions/when-i-go-specific-page.md +0 -0
  65. package/docs/step-definitions/when-i-move-backward-one-page.md +0 -0
  66. package/docs/step-definitions/when-i-move-forward-one-page.md +0 -0
  67. package/docs/step-definitions/when-i-press-button.md +0 -0
  68. package/docs/step-definitions/when-i-reload-page.md +0 -0
  69. package/docs/step-definitions/when-i-scroll.md +0 -0
  70. package/docs/step-definitions/when-i-select-option-select-list.md +0 -0
  71. package/docs/step-definitions/when-i-select-radio-button-value.md +0 -0
  72. package/docs/step-definitions/when-i-uncheck-checkbox.md +0 -0
  73. package/docs/step-definitions/when-i-wait-ajax-finish.md +0 -0
  74. package/docs/step-definitions/when-i-wait.md +0 -0
  75. package/docs/step-definitions.md +0 -0
  76. package/examples/a11y.html +0 -0
  77. package/examples/account.html +0 -0
  78. package/examples/ajax-wait-examples.html +0 -0
  79. package/examples/cookies.html +0 -0
  80. package/examples/date.html +0 -0
  81. package/examples/dynamic-examples.html +0 -0
  82. package/examples/element.html +0 -0
  83. package/examples/field.html +0 -0
  84. package/examples/keyboard.html +0 -0
  85. package/examples/links.html +0 -0
  86. package/examples/modal.html +0 -0
  87. package/examples/path.html +0 -0
  88. package/examples/table.html +0 -0
  89. package/examples/test--modal-dialogs.html +0 -0
  90. package/examples/test--when--i-additionally-select.html +0 -0
  91. package/examples/test--when--i-select-radio-button.html +0 -0
  92. package/examples/video-demo.html +43 -0
  93. package/package.json +1 -1
  94. package/playwright.config.ts +0 -0
  95. package/tests/assets/test-document.pdf +0 -0
  96. package/tests/features/a11y.feature +0 -0
  97. package/tests/features/ajax-wait-examples.feature +0 -0
  98. package/tests/features/cookie.feature +0 -0
  99. package/tests/features/date.feature +0 -0
  100. package/tests/features/dynamic-content-examples.feature +0 -0
  101. package/tests/features/element.feature +0 -0
  102. package/tests/features/field.feature +0 -0
  103. package/tests/features/keyboard.feature +0 -0
  104. package/tests/features/link.feature +0 -0
  105. package/tests/features/modal-advanced-example.feature +0 -0
  106. package/tests/features/modal-basic-example.feature +0 -0
  107. package/tests/features/modal-error-handling-example.feature +0 -0
  108. package/tests/features/modal.feature +0 -0
  109. package/tests/features/path.feature +0 -0
  110. package/tests/features/response.feature +0 -0
  111. package/tests/features/responsive.feature +0 -0
  112. package/tests/features/table.feature +0 -0
  113. package/tests/features/test--given--i-am-an-anonymous-user.feature +0 -0
  114. package/tests/features/test--then--i-save-screenshot.feature +0 -0
  115. package/tests/features/test--then--i-see-locator.feature +0 -0
  116. package/tests/features/test--then--i-should-see-n-elements.feature +0 -0
  117. package/tests/features/test--then--print-current-url-and-response.feature +0 -0
  118. package/tests/features/test--when--i-additionally-select.feature +0 -0
  119. package/tests/features/test--when--i-follow.feature +0 -0
  120. package/tests/features/test--when--i-select-radio-button.feature +0 -0
  121. package/tests/features/video.feature +18 -0
  122. package/tests/features/wait.feature +0 -0
  123. package/tests/features/yaml.feature +0 -0
  124. package/tests/reports/README.md +0 -0
  125. package/tests/selectors/_canonical-keys.json +0 -0
  126. package/tests/selectors/back-end-selectors.json +0 -0
  127. package/tests/selectors/cms-contentful-admin.json +0 -0
  128. package/tests/selectors/cms-craft-admin.json +0 -0
  129. package/tests/selectors/cms-drupal-cms-gin.json +0 -0
  130. package/tests/selectors/cms-drupal-core-claro.json +0 -0
  131. package/tests/selectors/cms-generic-admin.json +0 -0
  132. package/tests/selectors/cms-ghost-admin.json +0 -0
  133. package/tests/selectors/cms-joomla-admin.json +0 -0
  134. package/tests/selectors/cms-magento2-admin.json +0 -0
  135. package/tests/selectors/cms-prestashop-admin.json +0 -0
  136. package/tests/selectors/cms-shopify-admin.json +0 -0
  137. package/tests/selectors/cms-strapi-admin.json +0 -0
  138. package/tests/selectors/cms-typo3-admin.json +0 -0
  139. package/tests/selectors/cms-woocommerce-front.json +0 -0
  140. package/tests/selectors/cms-wordpress-admin.json +0 -0
  141. package/tests/selectors/framework-ant-design.json +0 -0
  142. package/tests/selectors/framework-bootstrap.json +0 -0
  143. package/tests/selectors/framework-bulma.json +0 -0
  144. package/tests/selectors/framework-chakra.json +0 -0
  145. package/tests/selectors/framework-foundation.json +0 -0
  146. package/tests/selectors/framework-material-ui.json +0 -0
  147. package/tests/selectors/framework-shadcn.json +0 -0
  148. package/tests/selectors/framework-tailwind.json +0 -0
  149. package/tests/selectors/framework-vuetify.json +0 -0
  150. package/tests/selectors/front-end-selectors.json +0 -0
  151. package/tests/selectors/homepage-selectors.json +0 -0
  152. package/tests/step-definitions/a11y.steps.js +3 -1
  153. package/tests/step-definitions/action.steps.js +2 -2
  154. package/tests/step-definitions/api.steps.js +17 -16
  155. package/tests/step-definitions/assertion.steps.js +2 -2
  156. package/tests/step-definitions/auth.steps.js +3 -1
  157. package/tests/step-definitions/clock.steps.js +38 -38
  158. package/tests/step-definitions/cookie.steps.js +0 -0
  159. package/tests/step-definitions/debug.steps.js +13 -5
  160. package/tests/step-definitions/dialog.steps.js +0 -0
  161. package/tests/step-definitions/element.steps.js +47 -5
  162. package/tests/step-definitions/field.steps.js +0 -0
  163. package/tests/step-definitions/file-download.steps.js +38 -20
  164. package/tests/step-definitions/form.steps.js +6 -6
  165. package/tests/step-definitions/iframe.steps.js +65 -15
  166. package/tests/step-definitions/input.steps.js +47 -8
  167. package/tests/step-definitions/javascript.steps.js +195 -34
  168. package/tests/step-definitions/keyboard.steps.js +38 -4
  169. package/tests/step-definitions/link.steps.js +0 -0
  170. package/tests/step-definitions/metatag.steps.js +0 -0
  171. package/tests/step-definitions/modal.steps.js +39 -14
  172. package/tests/step-definitions/navigation.steps.js +0 -0
  173. package/tests/step-definitions/network.steps.js +61 -19
  174. package/tests/step-definitions/path.steps.js +0 -0
  175. package/tests/step-definitions/response.steps.js +0 -0
  176. package/tests/step-definitions/responsive.steps.js +3 -1
  177. package/tests/step-definitions/rest.steps.js +0 -0
  178. package/tests/step-definitions/screenshot.steps.js +0 -0
  179. package/tests/step-definitions/scroll.steps.js +0 -0
  180. package/tests/step-definitions/selectors.steps.js +19 -17
  181. package/tests/step-definitions/storage.steps.js +0 -0
  182. package/tests/step-definitions/table.steps.js +0 -0
  183. package/tests/step-definitions/video.steps.js +178 -0
  184. package/tests/step-definitions/wait.steps.js +0 -0
  185. package/tests/step-definitions/web-first.steps.js +3 -1
  186. package/tests/step-definitions/webship.js +234 -15
  187. package/tests/step-definitions/xml.steps.js +4 -2
  188. package/tests/step-definitions/yaml.steps.js +13 -11
  189. package/tsconfig.json +0 -0
  190. package/videos/README.md +32 -0
  191. package/.travis-ci.yml +0 -16
  192. package/docs/diffy-step-definitions/then-compare-diffy-env1-env2.md +0 -30
  193. package/docs/diffy-step-definitions/then-create-diffy-comparison-name-value.md +0 -21
  194. package/docs/diffy-step-definitions/then-create-diffy-comparison.md +0 -25
  195. package/docs/diffy-step-definitions/then-create-diffy-screenshot-environment-name.md +0 -35
  196. package/docs/diffy-step-definitions/then-i-take-screenshot.md +0 -21
  197. package/docs/diffy-step-definitions/then-i-take-screenshots-all-breakpoints.md +0 -27
  198. package/docs/diffy-step-definitions/then-send-screenshots-diffy-name-value.md +0 -27
  199. package/docs/diffy-step-definitions/then-upload-folder-url-diffy-snapshotname.md +0 -28
  200. package/docs/diffy-step-definitions/then-wait-diffy-comparison-complete.md +0 -21
  201. package/docs/diffy-step-definitions/when-i-resize-window-number.md +0 -29
  202. package/docs/diffy-step-definitions.md +0 -21
  203. package/docs/index.md +0 -104
  204. package/examples/diffy/baseline.html +0 -54
  205. package/examples/diffy/changed.html +0 -63
  206. package/examples/diffy/index.html +0 -52
  207. package/tests/features/diffy/test--diffy-01-example-demo.feature +0 -22
  208. package/tests/features/diffy/test--diffy-02-all-steps.feature +0 -52
  209. package/tests/features/diffy/test--diffy-03-real-api.feature +0 -21
  210. package/tests/step-definitions-diffy/README.md +0 -329
  211. package/tests/step-definitions-diffy/mock-diffy-api/server.js +0 -84
  212. package/tests/step-definitions-diffy/webship-diffy-mock.js +0 -31
  213. package/tests/step-definitions-diffy/webship-diffy.js +0 -459
@@ -18,6 +18,7 @@ const {
18
18
  findVisibleModal,
19
19
  isAnyModalVisible,
20
20
  waitForModalState,
21
+ friendly,
21
22
  } = require('./webship');
22
23
 
23
24
  // ---------------------------------------------------------------------------
@@ -168,12 +169,20 @@ Then('the modal should not contain {string}', async function (text) {
168
169
  *
169
170
  */
170
171
  When(/^(I |we )*click "([^"]*)?"( button)* in( the)* modal( dialog)*$/, async function (pronounCase, buttonText, buttonCase, theCase, dialogCase) {
171
- await waitForModalState(this.page, 'visible', 10000, this);
172
- const modal = await findVisibleModal(this.page, this);
173
- await modal.locator('button, a, [role="button"], input[type="button"], input[type="submit"], .btn')
174
- .filter({ hasText: buttonText })
175
- .first()
176
- .click();
172
+ try {
173
+ await waitForModalState(this.page, 'visible', 10000, this);
174
+ const modal = await findVisibleModal(this.page, this);
175
+ await modal.locator('button, a, [role="button"], input[type="button"], input[type="submit"], .btn')
176
+ .filter({ hasText: buttonText })
177
+ .first()
178
+ .click();
179
+ } catch (e) {
180
+ throw friendly({
181
+ action: `click "${buttonText}" in the modal`,
182
+ cause: e,
183
+ hint: `make sure the modal is open ("When I wait for the modal to appear") and the button text matches exactly.`,
184
+ });
185
+ }
177
186
  });
178
187
 
179
188
  /**
@@ -193,7 +202,15 @@ When(/^(I |we )*click "([^"]*)?"( button)* in( the)* modal( dialog)*$/, async fu
193
202
  *
194
203
  */
195
204
  When(/^(I |we )*click on "([^"]*)" in the modal$/, async function (pronoun, selector) {
196
- await getModalLocator(this.page, this).locator(selector).first().click();
205
+ try {
206
+ await getModalLocator(this.page, this).locator(selector).first().click();
207
+ } catch (e) {
208
+ throw friendly({
209
+ action: `click on "${selector}" in the modal`,
210
+ cause: e,
211
+ hint: `make sure the modal is open and the selector matches something inside it.`,
212
+ });
213
+ }
197
214
  });
198
215
 
199
216
  /**
@@ -206,13 +223,21 @@ When(/^(I |we )*click on "([^"]*)" in the modal$/, async function (pronoun, sele
206
223
  *
207
224
  */
208
225
  When(/^(I |we )*(close|dismiss)( the)* modal( dialog)*$/, async function (pronounCase, closeOrDismiss, theCase, dialogCase) {
209
- await waitForModalState(this.page, 'visible', 10000, this);
210
- const modal = await findVisibleModal(this.page, this);
211
- const closeBtn = modal.locator('.close, .modal-close, [data-dismiss="modal"], [aria-label="Close"], .btn-close, button[class*="close"]').first();
212
- if (await closeBtn.isVisible()) {
213
- await closeBtn.click();
214
- } else {
215
- await modal.press('Escape');
226
+ try {
227
+ await waitForModalState(this.page, 'visible', 10000, this);
228
+ const modal = await findVisibleModal(this.page, this);
229
+ const closeBtn = modal.locator('.close, .modal-close, [data-dismiss="modal"], [aria-label="Close"], .btn-close, button[class*="close"]').first();
230
+ if (await closeBtn.isVisible()) {
231
+ await closeBtn.click();
232
+ } else {
233
+ await modal.press('Escape');
234
+ }
235
+ } catch (e) {
236
+ throw friendly({
237
+ action: `${closeOrDismiss} the modal`,
238
+ cause: e,
239
+ hint: `the modal had no recognised close button; check it is open or register a custom close-button selector.`,
240
+ });
216
241
  }
217
242
  });
218
243
 
File without changes
@@ -1,5 +1,7 @@
1
1
  'use strict';
2
2
 
3
+ const { friendly } = require('./webship');
4
+
3
5
  // Network interception and mocking via Playwright's `page.route()` API.
4
6
  //
5
7
  // Lets BDD scenarios stub external dependencies, simulate slow / offline
@@ -56,13 +58,21 @@ function ensureRequestLog(world) {
56
58
  *
57
59
  */
58
60
  Given(/^the URL "([^"]*)" returns the JSON:$/, async function (urlPattern, body) {
59
- await this.page.route(urlPattern, async (route) => {
60
- await route.fulfill({
61
- status: 200,
62
- contentType: 'application/json',
63
- body,
61
+ try {
62
+ await this.page.route(urlPattern, async (route) => {
63
+ await route.fulfill({
64
+ status: 200,
65
+ contentType: 'application/json',
66
+ body,
67
+ });
64
68
  });
65
- });
69
+ } catch (e) {
70
+ throw friendly({
71
+ action: `register a JSON stub for "${urlPattern}"`,
72
+ cause: e,
73
+ hint: `URL pattern uses glob syntax — try "**/api/users" or "*.png".`,
74
+ });
75
+ }
66
76
  });
67
77
 
68
78
  /**
@@ -76,9 +86,17 @@ Given(/^the URL "([^"]*)" returns the JSON:$/, async function (urlPattern, body)
76
86
  *
77
87
  */
78
88
  Given(/^the URL "([^"]*)" returns status (\d+)(?: with body "([^"]*)")?$/, async function (urlPattern, status, body) {
79
- await this.page.route(urlPattern, async (route) => {
80
- await route.fulfill({ status: parseInt(status, 10), body: body || '' });
81
- });
89
+ try {
90
+ await this.page.route(urlPattern, async (route) => {
91
+ await route.fulfill({ status: parseInt(status, 10), body: body || '' });
92
+ });
93
+ } catch (e) {
94
+ throw friendly({
95
+ action: `register a status-${status} stub for "${urlPattern}"`,
96
+ cause: e,
97
+ hint: `URL pattern uses glob syntax — try "**/api/users" or "*.png".`,
98
+ });
99
+ }
82
100
  });
83
101
 
84
102
  /**
@@ -92,7 +110,15 @@ Given(/^the URL "([^"]*)" returns status (\d+)(?: with body "([^"]*)")?$/, async
92
110
  *
93
111
  */
94
112
  Given(/^the URL "([^"]*)" is blocked$/, async function (urlPattern) {
95
- await this.page.route(urlPattern, (route) => route.abort());
113
+ try {
114
+ await this.page.route(urlPattern, (route) => route.abort());
115
+ } catch (e) {
116
+ throw friendly({
117
+ action: `block "${urlPattern}"`,
118
+ cause: e,
119
+ hint: `URL pattern uses glob syntax — try "**/analytics.js" or "*.gif".`,
120
+ });
121
+ }
96
122
  });
97
123
 
98
124
  /**
@@ -110,10 +136,18 @@ Given(/^the URL "([^"]*)" is blocked$/, async function (urlPattern) {
110
136
  */
111
137
  Given(/^the URL "([^"]*)" is delayed by (\d+) ?ms$/, async function (urlPattern, delay) {
112
138
  const ms = parseInt(delay, 10);
113
- await this.page.route(urlPattern, async (route) => {
114
- await new Promise((r) => setTimeout(r, ms));
115
- await route.continue();
116
- });
139
+ try {
140
+ await this.page.route(urlPattern, async (route) => {
141
+ await new Promise((r) => setTimeout(r, ms));
142
+ await route.continue();
143
+ });
144
+ } catch (e) {
145
+ throw friendly({
146
+ action: `delay "${urlPattern}" by ${ms} ms`,
147
+ cause: e,
148
+ hint: `URL pattern uses glob syntax — try "**/api/**" or "*.png".`,
149
+ });
150
+ }
117
151
  });
118
152
 
119
153
  /**
@@ -135,7 +169,8 @@ Given(/^the URL "([^"]*)" is delayed by (\d+) ?ms$/, async function (urlPattern,
135
169
  *
136
170
  */
137
171
  Given(/^the network is offline$/, async function () {
138
- await this.context.setOffline(true);
172
+ try { await this.context.setOffline(true); }
173
+ catch (e) { throw friendly({ action: 'switch the network offline', cause: e, hint: 'the browser context may have been closed; try a fresh scenario.' }); }
139
174
  });
140
175
 
141
176
  /**
@@ -157,7 +192,8 @@ Given(/^the network is offline$/, async function () {
157
192
  *
158
193
  */
159
194
  Given(/^the network is online$/, async function () {
160
- await this.context.setOffline(false);
195
+ try { await this.context.setOffline(false); }
196
+ catch (e) { throw friendly({ action: 'switch the network online', cause: e, hint: 'the browser context may have been closed; try a fresh scenario.' }); }
161
197
  });
162
198
 
163
199
  // ---------------------------------------------------------------------------
@@ -198,7 +234,9 @@ Given(/^(I |we )*start recording network requests$/, function () {
198
234
  */
199
235
  Then(/^a request to "([^"]*)" should have been made$/, function (urlPattern) {
200
236
  ensureRequestLog(this);
201
- const re = new RegExp(urlPattern.replace(/\*/g, '.*'));
237
+ let re;
238
+ try { re = new RegExp(urlPattern.replace(/\*/g, '.*')); }
239
+ catch (e) { throw friendly({ action: `match URL pattern "${urlPattern}"`, cause: e, hint: "URL pattern must be a valid regex or glob; check for unmatched brackets." }); }
202
240
  const found = this._requestLog.some((r) => re.test(r.url));
203
241
  assert.ok(found, `Expected at least one request matching "${urlPattern}".`);
204
242
  });
@@ -215,7 +253,9 @@ Then(/^a request to "([^"]*)" should have been made$/, function (urlPattern) {
215
253
  */
216
254
  Then(/^a (GET|POST|PUT|PATCH|DELETE) request to "([^"]*)" should have been made$/, function (method, urlPattern) {
217
255
  ensureRequestLog(this);
218
- const re = new RegExp(urlPattern.replace(/\*/g, '.*'));
256
+ let re;
257
+ try { re = new RegExp(urlPattern.replace(/\*/g, '.*')); }
258
+ catch (e) { throw friendly({ action: `match URL pattern "${urlPattern}"`, cause: e, hint: "URL pattern must be a valid regex or glob; check for unmatched brackets." }); }
219
259
  const found = this._requestLog.some((r) => r.method === method && re.test(r.url));
220
260
  assert.ok(found, `Expected at least one ${method} request matching "${urlPattern}".`);
221
261
  });
@@ -232,7 +272,9 @@ Then(/^a (GET|POST|PUT|PATCH|DELETE) request to "([^"]*)" should have been made$
232
272
  */
233
273
  Then(/^no request to "([^"]*)" should have been made$/, function (urlPattern) {
234
274
  ensureRequestLog(this);
235
- const re = new RegExp(urlPattern.replace(/\*/g, '.*'));
275
+ let re;
276
+ try { re = new RegExp(urlPattern.replace(/\*/g, '.*')); }
277
+ catch (e) { throw friendly({ action: `match URL pattern "${urlPattern}"`, cause: e, hint: "URL pattern must be a valid regex or glob; check for unmatched brackets." }); }
236
278
  const found = this._requestLog.some((r) => re.test(r.url));
237
279
  assert.ok(!found, `Did not expect any request matching "${urlPattern}".`);
238
280
  });
File without changes
File without changes
@@ -1,5 +1,7 @@
1
1
  'use strict';
2
2
 
3
+ const { friendly } = require('./webship');
4
+
3
5
  // Set viewport dimensions and named breakpoints.
4
6
 
5
7
  const { Given, When } = require('@cucumber/cucumber');
@@ -71,7 +73,7 @@ Given('the following responsive breakpoints:', async function (table) {
71
73
  When(/^(I |we )*set the viewport to the "([^"]*)" breakpoint$/, async function (pronoun, name) {
72
74
  const bps = getBreakpoints(this);
73
75
  const bp = bps[name];
74
- if (!bp) throw new Error(`Unknown breakpoint "${name}".`);
76
+ if (!bp) throw friendly(`Unknown breakpoint "${name}".`);
75
77
  await this.page.setViewportSize({ width: bp.width, height: bp.height });
76
78
  });
77
79
 
File without changes
File without changes
File without changes
@@ -1,5 +1,7 @@
1
1
  'use strict';
2
2
 
3
+ const { friendly } = require('./webship');
4
+
3
5
  // ---------------------------------------------------------------------------
4
6
  // Webship-JS — Selectors step definitions
5
7
  //
@@ -62,7 +64,7 @@ const path = require('path');
62
64
  function parseFile(filePath) {
63
65
  const ext = path.extname(filePath).toLowerCase();
64
66
  if (ext !== '.json') {
65
- throw new Error(`Selector files must be JSON (got "${ext}" for "${filePath}").`);
67
+ throw friendly(`Selector files must be JSON (got "${ext}" for "${filePath}").`);
66
68
  }
67
69
  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
68
70
  }
@@ -120,7 +122,7 @@ Before(function () {
120
122
  if (parsed && parsed.css) Object.assign(this.__selectorsCss, parsed.css);
121
123
  if (parsed && parsed.xpath) Object.assign(this.__selectorsXpath, parsed.xpath);
122
124
  } catch (e) {
123
- throw new Error(`Selectors: failed to load selector file "${filePath}": ${e.message}`);
125
+ throw friendly(`Selectors: failed to load selector file "${filePath}": ${e.message}`);
124
126
  }
125
127
  }
126
128
  });
@@ -173,7 +175,7 @@ function resolveSelector(world, name) {
173
175
  ? `\n Registered names: ${known.slice(0, 8).join(', ')}${known.length > 8 ? ', ...' : ''}`
174
176
  : '\n No selectors registered yet.';
175
177
 
176
- throw new Error(
178
+ throw friendly(
177
179
  `Unknown selector "${trimmed}".${suggestion}${examples}\n` +
178
180
  ` Register one with:\n` +
179
181
  ` Given I define css selectors:\n` +
@@ -219,9 +221,9 @@ async function getGeometry(page, selector) {
219
221
 
220
222
  async function assertPosition(page, position, c1Name, c1Sel, c2Name, c2Sel) {
221
223
  const g1 = await getGeometry(page, c1Sel);
222
- if (!g1) throw new Error(`Cannot get bounding box for "${c1Name}" (${c1Sel}) — element not visible`);
224
+ if (!g1) throw friendly(`Cannot get bounding box for "${c1Name}" (${c1Sel}) — element not visible`);
223
225
  const g2 = await getGeometry(page, c2Sel);
224
- if (!g2) throw new Error(`Cannot get bounding box for "${c2Name}" (${c2Sel}) — element not visible`);
226
+ if (!g2) throw friendly(`Cannot get bounding box for "${c2Name}" (${c2Sel}) — element not visible`);
225
227
 
226
228
  let pass = false;
227
229
  switch (position) {
@@ -262,7 +264,7 @@ async function dispatcher(world, position, subjectText, othersText, negate = fal
262
264
  } catch (e) { errors.push(e.message); }
263
265
  }
264
266
  }
265
- if (errors.length > 0) throw new Error(errors.join('\n'));
267
+ if (errors.length > 0) throw friendly(errors.join('\n'));
266
268
  }
267
269
 
268
270
  // ===========================================================================
@@ -296,7 +298,7 @@ async function dispatcher(world, position, subjectText, othersText, negate = fal
296
298
  * And I add "cta link" selector for "//a[contains(@class,'cta')]" xpath selector
297
299
  */
298
300
  When(/^(I |we )*add "([^"]*)" selector for "([^"]*)" css selector$/, function (pronounCase, selectorName, cssSelector) {
299
- if (!selectorName || !cssSelector) throw new Error('Selectors: selector name and CSS selector must not be empty.');
301
+ if (!selectorName || !cssSelector) throw friendly('Selectors: selector name and CSS selector must not be empty.');
300
302
  this.__selectorsCss[selectorName.trim()] = cssSelector.trim();
301
303
  });
302
304
 
@@ -323,7 +325,7 @@ When(/^(I |we )*add "([^"]*)" selector for "([^"]*)" css selector$/, function (p
323
325
  * When I add "last nav item" selector for "//nav[@role='navigation']//a[last()]" xpath selector
324
326
  */
325
327
  When(/^(I |we )*add "([^"]*)" selector for "([^"]*)" xpath selector$/, function (pronounCase, selectorName, xpathSelector) {
326
- if (!selectorName || !xpathSelector) throw new Error('Selectors: selector name and XPath selector must not be empty.');
328
+ if (!selectorName || !xpathSelector) throw friendly('Selectors: selector name and XPath selector must not be empty.');
327
329
  this.__selectorsXpath[selectorName.trim()] = xpathSelector.trim();
328
330
  });
329
331
 
@@ -357,12 +359,12 @@ When(/^(I |we )*add "([^"]*)" selector for "([^"]*)" xpath selector$/, function
357
359
  */
358
360
  When(/^(I |we )*add selectors from "([^"]*)" file$/, function (pronounCase, fileName) {
359
361
  const cfg = this.__selectorsConfig;
360
- if (!fileName) throw new Error('Selectors: file name must not be empty.');
361
- if (!cfg.filesPath) throw new Error('Selectors: worldParameters.selectors.filesPath must be set to load selector files.');
362
+ if (!fileName) throw friendly('Selectors: file name must not be empty.');
363
+ if (!cfg.filesPath) throw friendly('Selectors: worldParameters.selectors.filesPath must be set to load selector files.');
362
364
  const filePath = path.join(cfg.filesPath, fileName);
363
365
  let parsed;
364
366
  try { parsed = parseFile(filePath); } catch (e) {
365
- throw new Error(`Selectors: failed to load selector file "${filePath}": ${e.message}`);
367
+ throw friendly(`Selectors: failed to load selector file "${filePath}": ${e.message}`);
366
368
  }
367
369
  if (parsed && parsed.css) Object.assign(this.__selectorsCss, parsed.css);
368
370
  if (parsed && parsed.xpath) Object.assign(this.__selectorsXpath, parsed.xpath);
@@ -569,7 +571,7 @@ Given(/^(I |we )*define xpath selectors:$/, function (pronounCase, dataTable) {
569
571
  Given(/^(I am |we are )?viewing the site on a (?:"([^"]+)"|([a-zA-Z0-9 _,]+)) (?:screen|device)$/, async function (pronounCase, quoted, bare) {
570
572
  const name = (quoted || bare || '').trim();
571
573
  const cfg = this.__selectorsConfig;
572
- if (!cfg.breakpoints[name]) throw new Error(`Selectors: breakpoint "${name}" not defined in worldParameters.selectors.breakpoints.`);
574
+ if (!cfg.breakpoints[name]) throw friendly(`Selectors: breakpoint "${name}" not defined in worldParameters.selectors.breakpoints.`);
573
575
  const { width, height } = cfg.breakpoints[name];
574
576
  await this.page.setViewportSize({ width, height });
575
577
  });
@@ -772,7 +774,7 @@ Then(/^(I |we )*see visible ([a-zA-Z0-9 ,\-]+)$/, async function (pronounCase, s
772
774
  try { await this.page.locator(sel).first().waitFor({ state: 'visible', timeout: 5000 }); }
773
775
  catch { errors.push(`"${name}" (${sel}) is not visible`); }
774
776
  }
775
- if (errors.length > 0) throw new Error(errors.join('\n'));
777
+ if (errors.length > 0) throw friendly(errors.join('\n'));
776
778
  });
777
779
 
778
780
  /**
@@ -798,7 +800,7 @@ Then(/^(I |we )*(don't|do not) see ([a-zA-Z0-9 ,\-]+)$/, async function (pronoun
798
800
  try { await this.page.locator(sel).first().waitFor({ state: 'hidden', timeout: 5000 }); }
799
801
  catch { errors.push(`"${name}" (${sel}) is visible (expected hidden)`); }
800
802
  }
801
- if (errors.length > 0) throw new Error(errors.join('\n'));
803
+ if (errors.length > 0) throw friendly(errors.join('\n'));
802
804
  });
803
805
 
804
806
  /**
@@ -825,7 +827,7 @@ Then(/^(I |we )*see ([a-zA-Z0-9 ,\-]+) has focus$/, async function (pronounCase,
825
827
  const handle = await loc.elementHandle();
826
828
  await this.page.waitForFunction((el) => el === document.activeElement, handle, { timeout: 5000 });
827
829
  } catch {
828
- throw new Error(`"${name}" (${sel}) does not have focus`);
830
+ throw friendly(`"${name}" (${sel}) does not have focus`);
829
831
  }
830
832
  });
831
833
 
@@ -944,7 +946,7 @@ When(/^(I |we )*select "([^"]*)" text in "([^"]*)" field$/, async function (pron
944
946
 
945
947
  const value = await loc.inputValue();
946
948
  const start = value.indexOf(selectedText);
947
- if (start === -1) throw new Error(`Text "${selectedText}" not found in field "${fieldLabel}"`);
949
+ if (start === -1) throw friendly(`Text "${selectedText}" not found in field "${fieldLabel}"`);
948
950
  const end = start + selectedText.length;
949
951
 
950
952
  await loc.focus();
@@ -992,5 +994,5 @@ When(/^(I |we )*click (?:on |a )?([a-zA-Z0-9 ,\-]+)$/, async function (pronounCa
992
994
  try { await this.page.locator(sel).first().click(); }
993
995
  catch (e) { errors.push(`Cannot click "${name}" (${sel}): ${e.message}`); }
994
996
  }
995
- if (errors.length > 0) throw new Error(errors.join('\n'));
997
+ if (errors.length > 0) throw friendly(errors.join('\n'));
996
998
  });
File without changes
File without changes
@@ -0,0 +1,178 @@
1
+ 'use strict';
2
+
3
+ const { friendly } = require('./webship');
4
+
5
+ // Video recording steps — start / stop / save mid-scenario.
6
+ //
7
+ // Playwright records video only at browser-context creation. Mid-scenario
8
+ // `start` / `stop` therefore work by tearing down the current page +
9
+ // context and reopening with the new recording flag. Page state is lost
10
+ // across the boundary — call `start` BEFORE any navigation and `stop` only
11
+ // when you no longer need the current page state.
12
+ //
13
+ // Default mode is 'off' (no recording). See cucumber.js → worldParameters.video.
14
+
15
+ const { When, Then } = require('@cucumber/cucumber');
16
+ const fs = require('fs');
17
+ const path = require('path');
18
+
19
+ function settings(world) {
20
+ const cfg = (world.parameters && world.parameters.video) || {};
21
+ return {
22
+ dir: process.env.WEBSHIP_VIDEO_DIR || cfg.dir || './videos',
23
+ size: cfg.size || { width: 1280, height: 720 },
24
+ };
25
+ }
26
+
27
+ async function rebuildContext(world, recordVideo) {
28
+ await world.closeBrowser();
29
+ if (recordVideo) {
30
+ const s = settings(world);
31
+ fs.mkdirSync(s.dir, { recursive: true });
32
+ world._videoRequested = true;
33
+ await world.openBrowser({ recordVideo: { dir: s.dir, size: s.size } });
34
+ } else {
35
+ world._videoRequested = false;
36
+ await world.openBrowser();
37
+ }
38
+ }
39
+
40
+ /**
41
+ * Start recording the browser as a webm video. Closes the current page +
42
+ * context and reopens with `recordVideo` enabled. Place BEFORE any
43
+ * navigation in the scenario.
44
+ *
45
+ * Example #1: When I start video recording
46
+ * Example #2: And I start video recording
47
+ * Example #3: Given I start video recording
48
+ * Example #4: But I start video recording
49
+ * Example #5: Then I start video recording
50
+ *
51
+ */
52
+ When(/^(I |we )*start video recording$/, async function (pronoun) {
53
+ try {
54
+ await rebuildContext(this, true);
55
+ } catch (e) {
56
+ throw friendly({
57
+ action: 'start video recording',
58
+ cause: e,
59
+ hint: `the videos directory (${(this.parameters && this.parameters.video && this.parameters.video.dir) || './videos'}) must be writable.`,
60
+ });
61
+ }
62
+ });
63
+
64
+ /**
65
+ * Stop recording. Closes the current page + context (which flushes the
66
+ * webm to disk) and reopens a fresh, non-recording browser so the rest
67
+ * of the scenario can continue.
68
+ *
69
+ * Example #1: When I stop video recording
70
+ * Example #2: And I stop video recording
71
+ * Example #3: But I stop video recording
72
+ * Example #4: Then I stop video recording
73
+ * Example #5: Then I stop video recording
74
+ *
75
+ */
76
+ When(/^(I |we )*stop video recording$/, async function (pronoun) {
77
+ try {
78
+ if (!this.page || !this._videoRequested) return;
79
+ const video = this.page.video();
80
+ // Close context first — flushes the webm — then saveAs while the
81
+ // browser is still alive, finally close the browser and reopen fresh.
82
+ try { await this.context.close(); } catch { /* ignore */ }
83
+ if (video) {
84
+ try {
85
+ const s = settings(this);
86
+ const name = this._videoSaveAsName || `manual.${Date.now()}.webm`;
87
+ const dest = path.join(s.dir, name);
88
+ await video.saveAs(dest);
89
+ await video.delete().catch(() => {});
90
+ process.stderr.write(`\n[webship-js] video saved → ${dest}\n`);
91
+ // Reset so the After hook does not try to re-save.
92
+ this._videoSaveAsName = null;
93
+ } catch (e) {
94
+ process.stderr.write(`\n[webship-js] video save failed: ${e.message}\n`);
95
+ }
96
+ }
97
+ if (this.playwrightBrowser) {
98
+ try { await this.playwrightBrowser.close(); } catch { /* ignore */ }
99
+ this.playwrightBrowser = null;
100
+ }
101
+ this.context = null;
102
+ this.page = null;
103
+ this._videoRequested = false;
104
+ await this.openBrowser();
105
+ } catch (e) {
106
+ throw friendly({
107
+ action: 'stop video recording',
108
+ cause: e,
109
+ hint: 'the scenario will continue with a fresh, non-recording browser.',
110
+ });
111
+ }
112
+ });
113
+
114
+ /**
115
+ * Reserve a custom filename for the current scenario's video. The actual
116
+ * save happens at scenario end (Playwright's `video.saveAs()` blocks
117
+ * until recording finishes, so we cannot copy bytes mid-flight). If the
118
+ * scenario calls `stop video recording` before scenario end, the manual
119
+ * webm uses this name instead of the automatic timestamped one.
120
+ *
121
+ * Example #1: When I save the current video as "checkout-flow.webm"
122
+ * Example #2: When I save the current video as "regression-21.webm"
123
+ * Example #3: And I save the current video as "smoke.webm"
124
+ * Example #4: Then I save the current video as "demo.webm"
125
+ * Example #5: But I save the current video as "rerun.webm"
126
+ *
127
+ */
128
+ When(/^(I |we )*save the current video as "([^"]*)"$/, function (pronoun, name) {
129
+ try {
130
+ if (!this._videoRequested) {
131
+ throw new Error('recording is not active');
132
+ }
133
+ if (!name || !name.trim()) {
134
+ throw new Error('filename is empty');
135
+ }
136
+ this._videoSaveAsName = name;
137
+ } catch (e) {
138
+ throw friendly({
139
+ action: `save the current video as "${name}"`,
140
+ cause: e,
141
+ hint: 'call "When I start video recording" first, or set worldParameters.video.mode to "on".',
142
+ });
143
+ }
144
+ });
145
+
146
+ /**
147
+ * Print the path that the current video will be written to. Diagnostic
148
+ * only — never asserts, never fails.
149
+ *
150
+ * Example #1: Then print video path
151
+ * Example #2: And print video path
152
+ * Example #3: But print video path
153
+ * Example #4: Then print video path
154
+ * Example #5: Then print video path
155
+ *
156
+ */
157
+ Then(/^print video path$/, async function () {
158
+ // Diagnostic only — swallow every error and report inline.
159
+ try {
160
+ if (!this.page || !this._videoRequested) {
161
+ console.log('\n--- Video path: recording is OFF ---');
162
+ return;
163
+ }
164
+ const video = this.page.video();
165
+ if (!video) {
166
+ console.log('\n--- Video path: no video object on this page ---');
167
+ return;
168
+ }
169
+ try {
170
+ const p = await video.path();
171
+ console.log(`\n--- Video path: ${p} ---`);
172
+ } catch (e) {
173
+ console.log(`\n--- Video path unavailable: ${e.message} ---`);
174
+ }
175
+ } catch (e) {
176
+ console.log(`\n--- Video path error: ${e.message} ---`);
177
+ }
178
+ });
File without changes
@@ -1,5 +1,7 @@
1
1
  'use strict';
2
2
 
3
+ const { friendly } = require('./webship');
4
+
3
5
  // Web-first assertion steps — each matcher polls the live page until the
4
6
  // condition holds or the per-step timeout elapses. The assertion IS the
5
7
  // wait, so no `wait for AJAX` is required between an action and its check.
@@ -29,7 +31,7 @@ async function poll(fn, predicate, timeout, message) {
29
31
  }
30
32
  await new Promise((r) => setTimeout(r, 100));
31
33
  }
32
- throw new Error(`${message} (last seen: ${typeof last === 'object' ? JSON.stringify(last) : String(last)})`);
34
+ throw friendly(`${message} (last seen: ${typeof last === 'object' ? JSON.stringify(last) : String(last)})`);
33
35
  }
34
36
 
35
37
  async function checkState(locator, state) {