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
@@ -5,6 +5,31 @@ const playwright = require('playwright');
5
5
  const playwrightConfig = require(require('path').join(process.cwd(), 'playwright.config'));
6
6
  const path = require('path');
7
7
 
8
+ // ---------------------------------------------------------------------------
9
+ // Output filter — strip noisy `✔ Before # ...` / `✔ After # ...` hook lines
10
+ // from cucumber-js's failure dump so tester-facing output stays focused on
11
+ // the failing step + hint. Disable with WEBSHIP_FILTER_HOOK_LINES=off.
12
+ // ---------------------------------------------------------------------------
13
+ if (process.env.WEBSHIP_FILTER_HOOK_LINES !== 'off') {
14
+ const HOOK_LINE = /^\s*[✔✖✗⚠?-]\s+(?:Before|After|BeforeStep|AfterStep)\b.*$/;
15
+ const wrap = (stream) => {
16
+ const orig = stream.write.bind(stream);
17
+ stream.write = (chunk, encoding, cb) => {
18
+ if (typeof chunk === 'string' || Buffer.isBuffer(chunk)) {
19
+ const text = typeof chunk === 'string' ? chunk : chunk.toString('utf8');
20
+ const filtered = text
21
+ .split('\n')
22
+ .filter((line) => !HOOK_LINE.test(line.replace(/\x1b\[[0-9;]*m/g, '')))
23
+ .join('\n');
24
+ return orig(filtered, encoding, cb);
25
+ }
26
+ return orig(chunk, encoding, cb);
27
+ };
28
+ };
29
+ wrap(process.stdout);
30
+ wrap(process.stderr);
31
+ }
32
+
8
33
  // ===========================================================================
9
34
  // Internal helpers (BBR smart settle, modal probes, selector + text utilities).
10
35
  // Imported by every *.steps.js file via require('./webship'). Defined here
@@ -166,7 +191,7 @@ async function findVisibleModal(page, world) {
166
191
  if (await all.nth(i).isVisible()) return all.nth(i);
167
192
  }
168
193
  const sel = getModalSelector(world);
169
- throw new Error(
194
+ throw friendly(
170
195
  `No visible modal found.\n` +
171
196
  ` Selector tried: ${sel}\n` +
172
197
  ` Hint: did you "wait for the modal to appear" first?\n` +
@@ -257,7 +282,7 @@ async function gotoUrl(page, url) {
257
282
  if (/NS_ERROR_NET_EMPTY_RESPONSE|net::ERR_EMPTY_RESPONSE/.test(msg)) return;
258
283
  // Connection refused: server probably not running.
259
284
  if (/ECONNREFUSED|net::ERR_CONNECTION_REFUSED/.test(msg)) {
260
- throw new Error(
285
+ throw friendly(
261
286
  `Could not reach "${url}".\n` +
262
287
  ` ${msg.split('\n')[0]}\n` +
263
288
  ` Hint: is your dev server running? Check LAUNCH_URL env var.`
@@ -265,15 +290,14 @@ async function gotoUrl(page, url) {
265
290
  }
266
291
  // DNS failure.
267
292
  if (/ERR_NAME_NOT_RESOLVED|NS_ERROR_UNKNOWN_HOST/.test(msg)) {
268
- throw new Error(
293
+ throw friendly(
269
294
  `Could not resolve host for "${url}".\n` +
270
295
  ` ${msg.split('\n')[0]}\n` +
271
296
  ` Hint: double-check the hostname in LAUNCH_URL or your "Given I am on" path.`
272
297
  );
273
298
  }
274
- // Anything else — preserve original stack but prepend context.
275
- e.message = `Failed to navigate to "${url}":\n ${e.message}`;
276
- throw e;
299
+ // Anything else — strip the stack trace too.
300
+ throw friendly(`Failed to navigate to "${url}":\n ${e.message}`);
277
301
  }
278
302
  }
279
303
 
@@ -303,7 +327,7 @@ async function fillField(page, field, value) {
303
327
  await byName.fill(value);
304
328
  return;
305
329
  }
306
- throw new Error(
330
+ throw friendly(
307
331
  `Could not find a field for "${field}".\n` +
308
332
  ` Tried: getByLabel(exact), getByPlaceholder(exact), [name="${field}"].\n` +
309
333
  ` Hints: check the label/placeholder text matches exactly (case-sensitive),\n` +
@@ -470,6 +494,86 @@ BeforeStep(function (scope) {
470
494
  }
471
495
  });
472
496
 
497
+ /**
498
+ * Translate a raw Playwright / Node / HTTP error message into one short,
499
+ * plain-English sentence aimed at non-coder testers. Falls back to a
500
+ * cleaned-up first line of the original when no pattern matches.
501
+ *
502
+ * @param {Error|string} err
503
+ * @returns {string}
504
+ */
505
+ function humanize(err) {
506
+ const msg = typeof err === 'string' ? err : (err && err.message) || '';
507
+ const first = msg.split('\n')[0].trim();
508
+ // Common Playwright / Node patterns → plain English.
509
+ const map = [
510
+ [/Timeout\s+\d+ms\s+exceeded/i, 'the page took too long to respond'],
511
+ [/locator\.(click|press|fill|hover|dblclick|tap|focus|dispatchEvent|scrollIntoViewIfNeeded)/i,
512
+ 'the element could not be reached'],
513
+ [/strict mode violation/i, 'the locator matched more than one element'],
514
+ [/element is not visible/i, 'the element is hidden or off-screen'],
515
+ [/element is not attached/i, 'the element was removed from the page'],
516
+ [/element is not enabled/i, 'the element is disabled'],
517
+ [/element is outside of the viewport/i, 'the element is outside the visible area'],
518
+ [/intercepts pointer events/i, 'another element is on top of the target'],
519
+ [/ECONNREFUSED|net::ERR_CONNECTION_REFUSED/i, 'the server is not running or refused the connection'],
520
+ [/ERR_NAME_NOT_RESOLVED|NS_ERROR_UNKNOWN_HOST/i, 'the hostname could not be resolved'],
521
+ [/ERR_HTTP_RESPONSE_CODE_FAILURE/i, 'the page returned an HTTP error status'],
522
+ [/ENOENT/i, 'the file could not be found'],
523
+ [/EACCES|EPERM/i, 'the file is not readable or writable'],
524
+ [/Invalid (regular expression|regex)/i, 'the regular expression is invalid'],
525
+ [/Unexpected token|Unexpected end of JSON input/i, 'the JSON could not be parsed'],
526
+ [/Target page, context or browser has been closed/i, 'the browser closed before the step finished'],
527
+ [/page\.goto:/i, 'the page could not be opened'],
528
+ [/frameLocator|content frame/i, 'the iframe content was not ready'],
529
+ [/Cookies? not found|Cookie .* not (set|found)/i, 'the cookie does not exist on this page'],
530
+ [/setViewportSize/i, 'the viewport cannot be resized for this browser context'],
531
+ ];
532
+ for (const [re, plain] of map) {
533
+ if (re.test(msg)) return plain;
534
+ }
535
+ // Strip noisy "Call log:" suffix common in Playwright errors.
536
+ return first.replace(/^\w+\.\w+:\s*/, '').replace(/\s+Call log:.*$/i, '');
537
+ }
538
+
539
+ /**
540
+ * Build a tester-friendly error.
541
+ *
542
+ * Three forms:
543
+ * 1. `friendly(message)` — message becomes the stack.
544
+ * 2. `friendly(message, err)` — appends "Why: <humanized>" + cleaned cause.
545
+ * 3. `friendly({ action, target, hint, cause })` — builds a structured message.
546
+ *
547
+ * The Error's `.stack` is set to the rendered message, so cucumber-js does
548
+ * not print a JS stack trace — only the lines we authored.
549
+ *
550
+ * @param {string|Object} input
551
+ * @param {Error} [cause]
552
+ * @returns {Error}
553
+ */
554
+ function friendly(input, cause) {
555
+ let body;
556
+ if (typeof input === 'string') {
557
+ body = input;
558
+ if (cause) {
559
+ body += `\n Why: ${humanize(cause)}`;
560
+ }
561
+ } else if (input && typeof input === 'object') {
562
+ const lines = [];
563
+ if (input.action && input.target) lines.push(`Could not ${input.action} "${input.target}".`);
564
+ else if (input.action) lines.push(`Could not ${input.action}.`);
565
+ else if (input.message) lines.push(input.message);
566
+ if (input.cause) lines.push(` Why: ${humanize(input.cause)}`);
567
+ if (input.hint) lines.push(` Hint: ${input.hint}`);
568
+ body = lines.join('\n');
569
+ } else {
570
+ body = String(input);
571
+ }
572
+ const e = new Error(body);
573
+ e.stack = body;
574
+ return e;
575
+ }
576
+
473
577
  module.exports = {
474
578
  smartSettle,
475
579
  waitForPageLoad,
@@ -486,6 +590,8 @@ module.exports = {
486
590
  resolveRelativeDate,
487
591
  parseRelativeOffset,
488
592
  formatRelativeDate,
593
+ friendly,
594
+ humanize,
489
595
  };
490
596
 
491
597
  // ---------------------------------------------------------------------------
@@ -510,7 +616,11 @@ if (!global.__WEBSHIP_AUTO_REPORT__) {
510
616
  // ---------------------------------------------------------------------------
511
617
  // World
512
618
  // ---------------------------------------------------------------------------
513
- setDefaultTimeout(30 * 1000);
619
+ // Step timeout must exceed Playwright's 30s default so that locator timeouts
620
+ // (e.g. click() with no match) reach our try/catch wrappers BEFORE cucumber
621
+ // trips its own timeout — otherwise testers see "function timed out" instead
622
+ // of the friendly Why/Hint message.
623
+ setDefaultTimeout(45 * 1000);
514
624
 
515
625
  class PlaywrightWorld extends World {
516
626
  constructor(options) {
@@ -523,10 +633,11 @@ class PlaywrightWorld extends World {
523
633
  this.assetsFolder = path.join(__dirname, '../assets/');
524
634
  }
525
635
 
526
- async openBrowser() {
636
+ async openBrowser(extraContextOptions) {
527
637
  const { browser: browserName, launchOptions, contextOptions } = playwrightConfig;
528
638
  this.playwrightBrowser = await playwright[browserName].launch(launchOptions);
529
- this.context = await this.playwrightBrowser.newContext(contextOptions);
639
+ const merged = Object.assign({}, contextOptions, extraContextOptions || {});
640
+ this.context = await this.playwrightBrowser.newContext(merged);
530
641
  // BBR: install in-flight fetch/XHR counter on every page (init script runs
531
642
  // before any document script). The counter lets smartSettle() detect the
532
643
  // edge of background activity rather than guessing a fixed delay.
@@ -620,18 +731,126 @@ class PlaywrightWorld extends World {
620
731
 
621
732
  setWorldConstructor(PlaywrightWorld);
622
733
 
623
- Before(async function () {
624
- await this.openBrowser();
734
+ // ---------------------------------------------------------------------------
735
+ // Video recording — Playwright records at browser-context creation. The
736
+ // helpers below resolve config + tags into either an empty {} (no
737
+ // recording) or { recordVideo: { dir, size } } that gets merged into the
738
+ // context options.
739
+ // ---------------------------------------------------------------------------
740
+
741
+ const VIDEO_MODES = new Set(['off', 'on', 'on-failure', 'tag']);
742
+
743
+ function videoSettings(world, scope) {
744
+ const cfg = (world.parameters && world.parameters.video) || {};
745
+ let mode = process.env.WEBSHIP_VIDEO || cfg.mode || 'off';
746
+ if (!VIDEO_MODES.has(mode)) mode = 'off';
747
+ return {
748
+ mode,
749
+ dir: process.env.WEBSHIP_VIDEO_DIR || cfg.dir || './videos',
750
+ size: cfg.size || { width: 1280, height: 720 },
751
+ filenamePattern: cfg.filenamePattern || '{datetime}.{feature_file}.{scenario}.{status}.{ext}',
752
+ };
753
+ }
754
+
755
+ function videoHasTag(scope, name) {
756
+ return !!(scope && scope.pickle && Array.isArray(scope.pickle.tags) &&
757
+ scope.pickle.tags.some((t) => t.name === name));
758
+ }
759
+
760
+ function shouldRecordAtStart(s, scope) {
761
+ if (videoHasTag(scope, '@no-video')) return false;
762
+ if (videoHasTag(scope, '@video')) return true;
763
+ return s.mode === 'on' || s.mode === 'on-failure';
764
+ }
765
+
766
+ function sanitisePart(s) {
767
+ return String(s || '').replace(/[^a-zA-Z0-9._-]+/g, '_').slice(0, 80);
768
+ }
769
+
770
+ function buildVideoFilename(template, scope, status) {
771
+ const featurePath = (scope && scope.gherkinDocument && scope.gherkinDocument.uri) || 'unknown';
772
+ const feature = (scope && scope.gherkinDocument && scope.gherkinDocument.feature && scope.gherkinDocument.feature.name) || 'feature';
773
+ const scenario = (scope && scope.pickle && scope.pickle.name) || 'scenario';
774
+ const featureFile = featurePath.split('/').pop().replace(/\.feature$/, '');
775
+ const dt = new Date().toISOString().replace(/[:.]/g, '-');
776
+ return template
777
+ .replace('{datetime}', dt)
778
+ .replace('{feature_file}', sanitisePart(featureFile))
779
+ .replace('{feature}', sanitisePart(feature))
780
+ .replace('{scenario}', sanitisePart(scenario))
781
+ .replace('{status}', sanitisePart(status))
782
+ .replace('{ext}', 'webm');
783
+ }
784
+
785
+ Before({ order: 5 }, async function (scope) {
786
+ this._videoSettings = videoSettings(this, scope);
787
+ this._videoRequested = shouldRecordAtStart(this._videoSettings, scope);
788
+ this._videoForcedByTag = videoHasTag(scope, '@video');
789
+
790
+ const extra = {};
791
+ if (this._videoRequested) {
792
+ require('fs').mkdirSync(this._videoSettings.dir, { recursive: true });
793
+ extra.recordVideo = {
794
+ dir: this._videoSettings.dir,
795
+ size: this._videoSettings.size,
796
+ };
797
+ }
798
+
799
+ await this.openBrowser(extra);
625
800
  if (this.minWaitTime.before_scenario > 0) {
626
801
  await this.page.waitForTimeout(this.minWaitTime.before_scenario);
627
802
  }
628
803
  });
629
804
 
630
- After(async function () {
805
+ After({ order: 5 }, async function (scope) {
631
806
  if (this.minWaitTime.after_scenario > 0) {
632
- await this.page.waitForTimeout(this.minWaitTime.after_scenario);
807
+ try { await this.page.waitForTimeout(this.minWaitTime.after_scenario); } catch { /* page already closed */ }
808
+ }
809
+
810
+ const status = (scope && scope.result && scope.result.status) || 'unknown';
811
+ const videoRef = (this._videoRequested && this.page) ? this.page.video() : null;
812
+ // Capture the raw Playwright path BEFORE closing the context — after
813
+ // close, the remote handle is gone and video.path() throws.
814
+ let rawPath = null;
815
+ if (videoRef) {
816
+ try { rawPath = await videoRef.path(); } catch { /* may throw on remote */ }
817
+ }
818
+
819
+ // Close the *context* (flushes the webm to disk). Browser stays up so
820
+ // saveAs() / delete() can still talk to it.
821
+ if (this.context) {
822
+ try { await this.context.close(); } catch { /* ignore */ }
823
+ }
824
+
825
+ if (videoRef) {
826
+ const settings = this._videoSettings;
827
+ const filename = this._videoSaveAsName || buildVideoFilename(settings.filenamePattern, scope, status);
828
+ const dest = require('path').join(settings.dir, filename);
829
+ try {
830
+ const passed = status === 'PASSED' || status === 'passed';
831
+ if (settings.mode === 'on-failure' && passed && !this._videoForcedByTag) {
832
+ await videoRef.delete().catch(() => {});
833
+ } else {
834
+ await videoRef.saveAs(dest);
835
+ await videoRef.delete().catch(() => {});
836
+ process.stderr.write(`\n[webship-js] video saved → ${dest}\n`);
837
+ }
838
+ } catch (e) {
839
+ process.stderr.write(`\n[webship-js] video save failed: ${e.message}\n`);
840
+ }
841
+ // Fallback: remove the Playwright scratch file via fs if it still exists.
842
+ if (rawPath) {
843
+ try { require('fs').unlinkSync(rawPath); } catch { /* already gone */ }
844
+ }
845
+ }
846
+
847
+ // Finally close the browser.
848
+ if (this.playwrightBrowser) {
849
+ try { await this.playwrightBrowser.close(); } catch { /* ignore */ }
850
+ this.playwrightBrowser = null;
633
851
  }
634
- await this.closeBrowser();
852
+ this.context = null;
853
+ this.page = null;
635
854
  });
636
855
 
637
856
  BeforeStep(async function () {
@@ -1,5 +1,7 @@
1
1
  'use strict';
2
2
 
3
+ const { friendly } = require('./webship');
4
+
3
5
  // Parse and assert against an XML response loaded from a file or doc string.
4
6
 
5
7
  const { Given, Then, When } = require('@cucumber/cucumber');
@@ -15,8 +17,8 @@ catch (e) {
15
17
  }
16
18
 
17
19
  function ensureXml(world) {
18
- if (!DOMParser) throw new Error('XML steps require an XML DOM parser. Install @xmldom/xmldom.');
19
- if (!world._xml) throw new Error('No XML response has been set.');
20
+ if (!DOMParser) throw friendly('XML steps require an XML DOM parser. Install @xmldom/xmldom.');
21
+ if (!world._xml) throw friendly('No XML response has been set.');
20
22
  return world._xml;
21
23
  }
22
24
 
@@ -1,5 +1,7 @@
1
1
  'use strict';
2
2
 
3
+ const { friendly } = require('./webship');
4
+
3
5
  // Parse and assert against YAML response bodies.
4
6
  //
5
7
  // Mirrors xml.steps.js where it makes sense (path-based existence / equality
@@ -23,13 +25,13 @@ try { Ajv = require('ajv'); } catch { /* lazy */ }
23
25
  try { addFormats = require('ajv-formats'); } catch { /* lazy */ }
24
26
 
25
27
  function requireYaml() {
26
- if (!YAML) throw new Error('YAML steps require js-yaml. Install with: npm i js-yaml');
28
+ if (!YAML) throw friendly('YAML steps require js-yaml. Install with: npm i js-yaml');
27
29
  return YAML;
28
30
  }
29
31
 
30
32
  function ensureLoaded(world) {
31
33
  requireYaml();
32
- if (world._yaml === undefined) throw new Error('No YAML response has been set.');
34
+ if (world._yaml === undefined) throw friendly('No YAML response has been set.');
33
35
  return world._yaml;
34
36
  }
35
37
 
@@ -181,10 +183,10 @@ Given('the YAML response content is the following:', async function (docString)
181
183
  *
182
184
  */
183
185
  Given('the active YAML document is {int}', function (n) {
184
- if (!this._yamlDocs) throw new Error('No YAML response has been set.');
186
+ if (!this._yamlDocs) throw friendly('No YAML response has been set.');
185
187
  const idx = n - 1;
186
188
  if (idx < 0 || idx >= this._yamlDocs.length) {
187
- throw new Error(`Document ${n} out of range (have ${this._yamlDocs.length}).`);
189
+ throw friendly(`Document ${n} out of range (have ${this._yamlDocs.length}).`);
188
190
  }
189
191
  this._yamlDocIndex = idx;
190
192
  this._yaml = this._yamlDocs[idx];
@@ -581,10 +583,10 @@ Then('the YAML value at {string} should not be empty', function (p) {
581
583
 
582
584
  function numAt(doc, p) {
583
585
  const nodes = evalPath(doc, p);
584
- if (nodes.length === 0) throw new Error(`YAML element "${p}" not found.`);
586
+ if (nodes.length === 0) throw friendly(`YAML element "${p}" not found.`);
585
587
  const v = nodes[0];
586
588
  const n = typeof v === 'number' ? v : Number(v);
587
- if (!Number.isFinite(n)) throw new Error(`YAML value at "${p}" is not numeric: ${v}`);
589
+ if (!Number.isFinite(n)) throw friendly(`YAML value at "${p}" is not numeric: ${v}`);
588
590
  return n;
589
591
  }
590
592
 
@@ -670,9 +672,9 @@ Then('the YAML value at {string} should be between {float} and {float}', functio
670
672
 
671
673
  function arrayAt(doc, p) {
672
674
  const nodes = evalPath(doc, p);
673
- if (nodes.length === 0) throw new Error(`YAML element "${p}" not found.`);
675
+ if (nodes.length === 0) throw friendly(`YAML element "${p}" not found.`);
674
676
  const v = nodes[0];
675
- if (!Array.isArray(v)) throw new Error(`YAML value at "${p}" is not an array.`);
677
+ if (!Array.isArray(v)) throw friendly(`YAML value at "${p}" is not an array.`);
676
678
  return v;
677
679
  }
678
680
 
@@ -737,10 +739,10 @@ Then('every item in {string} should have key {string}', function (p, key) {
737
739
 
738
740
  function keysAt(doc, p) {
739
741
  const nodes = evalPath(doc, p);
740
- if (nodes.length === 0) throw new Error(`YAML element "${p}" not found.`);
742
+ if (nodes.length === 0) throw friendly(`YAML element "${p}" not found.`);
741
743
  const v = nodes[0];
742
744
  if (typeof v !== 'object' || Array.isArray(v) || v === null) {
743
- throw new Error(`YAML value at "${p}" is not a mapping.`);
745
+ throw friendly(`YAML value at "${p}" is not a mapping.`);
744
746
  }
745
747
  return Object.keys(v);
746
748
  }
@@ -796,7 +798,7 @@ Then('the YAML at {string} should have keys {string}', function (p, csv) {
796
798
  *
797
799
  */
798
800
  Then('the YAML should match JSON Schema {string}', function (schemaFile) {
799
- if (!Ajv) throw new Error('Schema validation requires ajv. Install with: npm i ajv ajv-formats');
801
+ if (!Ajv) throw friendly('Schema validation requires ajv. Install with: npm i ajv ajv-formats');
800
802
  const doc = activeDoc(this); ensureLoaded(this);
801
803
  const p = path.isAbsolute(schemaFile) ? schemaFile : path.join(this.assetsFolder || './tests/assets', schemaFile);
802
804
  const schema = JSON.parse(fs.readFileSync(p, 'utf-8'));
package/tsconfig.json CHANGED
File without changes
@@ -0,0 +1,32 @@
1
+ # videos/
2
+
3
+ Generated by Playwright when video recording is enabled. Default mode is
4
+ **off** — this directory stays empty unless you opt in.
5
+
6
+ ## Enable recording
7
+
8
+ | How | Effect |
9
+ | --- | --- |
10
+ | `WEBSHIP_VIDEO=on npm test` | Record every scenario in this run. |
11
+ | `WEBSHIP_VIDEO=on-failure npm test` | Record every scenario, keep only failures. |
12
+ | Tag scenario `@video` | Force-record this one scenario (mode-independent). |
13
+ | `worldParameters.video.mode = 'on'` in `cucumber.js` | Persist recording for every run. |
14
+
15
+ ## File naming
16
+
17
+ Default template: `{datetime}.{feature_file}.{scenario}.{status}.{ext}` —
18
+ e.g. `2026-05-13T01-47-01-567Z.video.Record_a_tiny_click_flow_with_emojis.PASSED.webm`.
19
+
20
+ Mid-scenario `When I save the current video as "name.webm"` overrides the
21
+ template for that scenario.
22
+
23
+ ## What is gitignored
24
+
25
+ Everything except this README. `.gitignore` keeps `videos/*.webm` out of
26
+ the repo so binary recordings do not bloat history. Share via your CI
27
+ artefact store or attach to a PR description directly.
28
+
29
+ ## Step reference
30
+
31
+ See `docs/04-step-reference.md` → "Video recording" for the full step
32
+ list and mode matrix.
package/.travis-ci.yml DELETED
@@ -1,16 +0,0 @@
1
- language: node_js
2
-
3
- node_js:
4
- - "20"
5
-
6
- before_script:
7
- - npm install
8
- - npx playwright install --with-deps chromium
9
-
10
- script:
11
- - npm start &
12
- - npm test
13
-
14
- cache:
15
- directories:
16
- - node_modules
@@ -1,30 +0,0 @@
1
-
2
- # Then compare diffy "ENV1" with "ENV2"
3
-
4
- ## Description
5
-
6
- This step initiates a Diffy comparison between two project environments. When either environment is specified as "custom", the step uses the `DIFFY_ENV1_URL` and `DIFFY_ENV2_URL` environment variables.
7
-
8
- ## Gherkin Step Pattern
9
-
10
- ```
11
- Then (I |we )*compare diffy "([^"]*)" with "([^"]*)"
12
- ```
13
-
14
- ## Examples
15
-
16
- ```
17
- Then compare diffy "prod" with "stage"
18
- Then compare diffy "production" with "staging"
19
- Then compare diffy "prod" with "dev"
20
- Then compare diffy "stage" with "dev"
21
- Then compare diffy "prod" with "baseline"
22
- Then compare diffy "baseline" with "custom"
23
- Then compare diffy "custom" with "custom"
24
- Then compare diffy "production" with "development"
25
- ```
26
-
27
- ## Parameters
28
-
29
- - **First Environment**: The initial environment name for comparison
30
- - **Second Environment**: The environment to compare against (uses custom URLs when "custom" is specified)
@@ -1,21 +0,0 @@
1
-
2
- # Then create diffy comparison with name "value"
3
-
4
- ## Description
5
- This step definition creates a named Diffy comparison using the last two uploaded snapshots.
6
-
7
- ## Gherkin Pattern
8
- ```
9
- Then (I |we )*create diffy comparison with name "([^"]*)"
10
- ```
11
-
12
- ## Examples
13
- - `Then create diffy comparison with name "release-2.0"`
14
- - `Then create diffy comparison with name "nightly"`
15
- - `Then create diffy comparison with name "smoke-run-42"`
16
- - `Then create diffy comparison with name "webship.co-regression"`
17
- - `Then create diffy comparison with name "before-vs-after"`
18
- - `Then create diffy comparison with name "homepage-baseline-vs-changed"`
19
-
20
- ## Parameters
21
- The step accepts a single parameter: a string value representing the name for the comparison being created.
@@ -1,25 +0,0 @@
1
-
2
- # Then create diffy comparison
3
-
4
- ## Description
5
- This step generates a Diffy comparison (visual diff) by utilizing the two most recently uploaded snapshots.
6
-
7
- ## Gherkin Syntax
8
- ```gherkin
9
- Then (I |we )*create diffy comparison
10
- ```
11
-
12
- ## Usage Examples
13
- The step accepts several grammatical variations:
14
-
15
- ```gherkin
16
- Then create diffy comparison
17
- And create diffy comparison
18
- Then I create diffy comparison
19
- Then we create diffy comparison
20
- And I create diffy comparison
21
- And we create diffy comparison
22
- ```
23
-
24
- ## Purpose
25
- Creates a visual comparison report from the last pair of snapshots that were uploaded to Diffy, allowing teams to identify visual regressions between environments or versions.
@@ -1,35 +0,0 @@
1
-
2
- # Then create diffy screenshot from "environment name" environment
3
-
4
- ## Overview
5
-
6
- This Webship JS step definition instructs Diffy to capture a snapshot remotely from a specified environment within your project. The step accepts both abbreviated and full environment names, including custom environments.
7
-
8
- ## Gherkin Step Pattern
9
-
10
- ```
11
- Then (I |we )*create diffy screenshot from "([^"]*)" environment
12
- ```
13
-
14
- ## Description
15
-
16
- "Ask Diffy to capture a snapshot remotely from a named environment on the project. Accepts short (prod/stage/dev) or long (production/staging/development) forms, plus 'custom'."
17
-
18
- ## Examples
19
-
20
- ```gherkin
21
- Then create diffy screenshot from "production" environment
22
- Then create diffy screenshot from "prod" environment
23
- Then create diffy screenshot from "staging" environment
24
- Then create diffy screenshot from "stage" environment
25
- Then create diffy screenshot from "development" environment
26
- Then create diffy screenshot from "dev" environment
27
- Then create diffy screenshot from "custom" environment
28
- ```
29
-
30
- ## Supported Environment Names
31
-
32
- - **Production**: "production" or "prod"
33
- - **Staging**: "staging" or "stage"
34
- - **Development**: "development" or "dev"
35
- - **Custom**: "custom" (for user-defined environments)
@@ -1,21 +0,0 @@
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`
@@ -1,27 +0,0 @@
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