webship-js 2.0.3 → 2.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) 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 +2 -2
  9. package/CLAUDE.md +2 -2
  10. package/Jenkinsfile +54 -0
  11. package/azure-pipelines.yml +82 -0
  12. package/bamboo-specs/bamboo.yml +131 -0
  13. package/buildspec.yml +56 -0
  14. package/cloudbuild.yaml +49 -0
  15. package/codefresh.yml +77 -0
  16. package/cucumber.js +40 -3
  17. package/docs/04-step-reference.md +74 -3
  18. package/docs/16-ci-cd.md +879 -0
  19. package/docs/README.md +113 -0
  20. package/docs/global-settings.md +51 -0
  21. package/examples/video-demo.html +43 -0
  22. package/package.json +1 -1
  23. package/tests/features/video.feature +18 -0
  24. package/tests/step-definitions/a11y.steps.js +3 -1
  25. package/tests/step-definitions/action.steps.js +2 -2
  26. package/tests/step-definitions/api.steps.js +17 -16
  27. package/tests/step-definitions/assertion.steps.js +2 -2
  28. package/tests/step-definitions/auth.steps.js +3 -1
  29. package/tests/step-definitions/clock.steps.js +38 -38
  30. package/tests/step-definitions/debug.steps.js +13 -5
  31. package/tests/step-definitions/element.steps.js +47 -5
  32. package/tests/step-definitions/file-download.steps.js +38 -20
  33. package/tests/step-definitions/form.steps.js +6 -6
  34. package/tests/step-definitions/iframe.steps.js +65 -15
  35. package/tests/step-definitions/input.steps.js +47 -8
  36. package/tests/step-definitions/javascript.steps.js +195 -34
  37. package/tests/step-definitions/keyboard.steps.js +38 -4
  38. package/tests/step-definitions/modal.steps.js +39 -14
  39. package/tests/step-definitions/network.steps.js +61 -19
  40. package/tests/step-definitions/responsive.steps.js +3 -1
  41. package/tests/step-definitions/selectors.steps.js +19 -17
  42. package/tests/step-definitions/video.steps.js +178 -0
  43. package/tests/step-definitions/web-first.steps.js +3 -1
  44. package/tests/step-definitions/webship.js +234 -15
  45. package/tests/step-definitions/xml.steps.js +4 -2
  46. package/tests/step-definitions/yaml.steps.js +13 -11
  47. package/videos/README.md +32 -0
  48. package/.travis-ci.yml +0 -16
  49. package/docs/index.md +0 -104
package/docs/README.md ADDED
@@ -0,0 +1,113 @@
1
+ # Webship-js Documentation
2
+
3
+ Webship-js is a BDD-first browser-automation harness built on Playwright + Cucumber-js. Feature files in plain Gherkin; selectors that survive redesigns; smart waits that never sleep.
4
+
5
+ **411 built-in steps** across **36 step files**. **288 example scenarios / 1,406 step executions** in the bundled suite, all green on chromium, firefox, and webkit.
6
+
7
+ ## Reading order
8
+
9
+ ### Webship-js essentials (custom)
10
+
11
+ | Doc | Topic |
12
+ | --- | --- |
13
+ | [00 Quick start](00-quick-start.md) | 5-minute path for newcomers |
14
+ | [01 Getting started](01-getting-started.md) | Install, project layout, run modes |
15
+ | [02 BBR smart waits](02-bbr-smart-waits.md) | Why we never `sleep N seconds` |
16
+ | [03 Selector registry](03-selector-registry.md) | Named selectors + CMS / framework presets |
17
+ | [04 Step reference](04-step-reference.md) | Every built-in step, by topic |
18
+ | [05 Web-first assertions](05-web-first-assertions.md) | Auto-retrying matchers |
19
+ | [06 Networking & dialogs](06-network-and-dialogs.md) | Request mocking, alerts, prompts |
20
+ | [07 Auth state](07-auth-state.md) | Save / restore login |
21
+ | [08 Clock mocking](08-clock-mocking.md) | Control time |
22
+ | [09 API testing](09-api-testing.md) | Direct HTTP from BDD |
23
+ | [10 Accessibility](10-accessibility.md) | POUR smoke checks |
24
+ | [11 Debugging](11-debugging.md) | Screenshots, headed, traces, reports |
25
+ | [12 AI agent guide](12-ai-agent-guide.md) | Wisdom + recipes from the Recipes book v1.0.30 (TDD AI / SPDD / Three Amigos / golden rules) |
26
+ | [13 FAQ](13-faq.md) | Common questions for newcomers |
27
+ | [14 Recipes cookbook](14-recipes-cookbook.md) | 20 paste-and-go scenarios |
28
+ | [15 Tag conventions](15-tag-conventions.md) | Standard tags + CI lane patterns |
29
+ | [16 CI / CD setup](16-ci-cd.md) | Per-provider setup steps and config notes |
30
+
31
+ ### Reference (mirrored from webship.co/docs/webship-js/2.0.x)
32
+
33
+ | Doc | Topic |
34
+ | --- | --- |
35
+ | [Overview](overview.md) | Webship-js v2.0.x at a glance |
36
+ | [Install](install-webship-js.md) | Install Webship-js |
37
+ | [Install — DDEV](install-webship-js/ddev-webship-js.md) | DDEV-Webship-js variant |
38
+ | [Global settings](global-settings.md) | `cucumber.js` `worldParameters` reference |
39
+ | [Commands](commands.md) | CLI commands |
40
+ | [Assertions](assertions.md) | Built-in assertions |
41
+ | [Step definitions](step-definitions.md) | Step-definition catalogue (28 sub-pages under `step-definitions/`) |
42
+ | [API step definitions](api-step-definitions.md) | REST step definitions |
43
+ | [Advanced screenshots](advanced-screenshots.md) | Per-size, full-page, named (3 sub-pages under `advanced-screenshots/`) |
44
+ | [Advanced selectors](advanced-selectors.md) | Named selector registry, position assertions |
45
+ | [Diffy step definitions](diffy-step-definitions.md) | Visual-diff workflow (10 sub-pages under `diffy-step-definitions/`) |
46
+
47
+ ## At a glance
48
+
49
+ ```gherkin
50
+ Feature: Smoke
51
+
52
+ Background:
53
+ Given I restore the auth state from "tests/auth/admin.json"
54
+
55
+ @javascript
56
+ Scenario: Dashboard renders without JS errors
57
+ Given I am on "/dashboard"
58
+ And I wait until the network is idle
59
+ Then the page should have a main landmark
60
+ And "<#user-list>" should have a count of 5 within 5 seconds
61
+ And "<.notification>" should not be visible
62
+ ```
63
+
64
+ ## Source layout
65
+
66
+ ```
67
+ webship-js/
68
+ ├── docs/ <— You are here
69
+ ├── tests/
70
+ │ ├── features/ <— Your *.feature files
71
+ │ ├── selectors/ <— CMS / framework JSON presets
72
+ │ └── step-definitions/ <— Built-in steps (auto-loaded)
73
+ │ ├── webship.js # World setup, hooks, shared helpers (smartSettle, modal, selectors, date tokens)
74
+ │ ├── a11y.steps.js (26) # axe-core audits + WCAG hygiene probes
75
+ │ ├── action.steps.js (7) # press / click / follow / attach
76
+ │ ├── api.steps.js (22) # REST long form (base URL, headers, query, body, JSON Pointer)
77
+ │ ├── assertion.steps.js (14) # see / not see, in row, in element, response, count
78
+ │ ├── auth.steps.js (3) # save / restore / clear storageState
79
+ │ ├── clock.steps.js (7) # install / advance / pause / set system time
80
+ │ ├── cookie.steps.js (12) # cookie exists / equals / contains
81
+ │ ├── debug.steps.js (2) # print URL / last response (diagnostic)
82
+ │ ├── dialog.steps.js (8) # native alert / confirm / prompt
83
+ │ ├── element.steps.js (19) # focus / scroll-to / dispatch / count / position
84
+ │ ├── field.steps.js (27) # field state, checkbox, radio, select-list
85
+ │ ├── file-download.steps.js (8) # capture + assert filename / mime / path
86
+ │ ├── form.steps.js (13) # fill / select / check / uncheck / radio
87
+ │ ├── iframe.steps.js (10) # frameLocator switch + scoped click / fill / assert
88
+ │ ├── input.steps.js (9) # hover / drag / dbl / right-click / tap / viewport
89
+ │ ├── javascript.steps.js (4) # JS error tracker + assertion (warn / fail / off)
90
+ │ ├── keyboard.steps.js (4) # single key + combos with alias normalisation
91
+ │ ├── link.steps.js (9) # href / title / target / rel
92
+ │ ├── metatag.steps.js (3) # description / keywords / OG / Twitter
93
+ │ ├── modal.steps.js (9) # HTML modal visibility / content / interactions
94
+ │ ├── navigation.steps.js (11) # homepage / paths / history / URL assertions
95
+ │ ├── network.steps.js (10) # route stubs / mocks / delays / offline
96
+ │ ├── path.steps.js (8) # URL path / query / fragment
97
+ │ ├── response.steps.js (4) # response header inspection
98
+ │ ├── responsive.steps.js (5) # named breakpoints + explicit viewport
99
+ │ ├── rest.steps.js (5) # REST short form
100
+ │ ├── screenshot.steps.js (6) # manual + auto-on-failure + per-step capture
101
+ │ ├── scroll.steps.js (12) # page + scoped element scroll
102
+ │ ├── selectors.steps.js (22) # named CSS / XPath registry + 22 CMS / framework presets
103
+ │ ├── storage.steps.js (9) # local / session storage
104
+ │ ├── table.steps.js (8) # data-table row / column assertions
105
+ │ ├── video.steps.js (4) # start / stop / save webm recording
106
+ │ ├── wait.steps.js (21) # every wait phrasing — all BBR-backed
107
+ │ ├── web-first.steps.js (12) # auto-retrying matchers (`within N seconds`)
108
+ │ ├── xml.steps.js (20) # XPath equals / contains / count / attr
109
+ │ └── yaml.steps.js (38) # multi-doc + types + numerics + JSON Schema + diff
110
+ ├── examples/ <— Static HTML fixtures
111
+ ├── cucumber.js <— Profiles + worldParameters
112
+ └── playwright.config.ts <— Browser launch + context options
113
+ ```
@@ -136,6 +136,57 @@ Filename pattern tokens: `{datetime}`, `{date}`, `{time}`, `{feature_file}`,
136
136
  `{feature}`, `{scenario}`, `{step_line}`, `{ext}`, `{failed_prefix}`,
137
137
  `{url}`, `{host}`, `{path}`.
138
138
 
139
+ ### `video` — Playwright video recording
140
+
141
+ ```js
142
+ video: {
143
+ mode: 'off', // WEBSHIP_VIDEO — 'off' | 'on' | 'on-failure' | 'tag'
144
+ dir: './videos', // WEBSHIP_VIDEO_DIR
145
+ size: { width: 1280, height: 720 }, // recording viewport
146
+ filenamePattern: '{datetime}.{feature_file}.{scenario}.{status}.{ext}',
147
+ }
148
+ ```
149
+
150
+ Tag overrides per scenario:
151
+
152
+ | Tag | Effect |
153
+ | --- | --- |
154
+ | `@video` | Force recording on. |
155
+ | `@no-video` | Suppress recording. |
156
+
157
+ Modes:
158
+
159
+ | Mode | Behaviour |
160
+ | --- | --- |
161
+ | `off` (default) | No recording. |
162
+ | `on` | Record every scenario. |
163
+ | `on-failure` | Record every scenario, keep only failures. |
164
+ | `tag` | Record only scenarios tagged `@video`. |
165
+
166
+ Mid-scenario start / stop steps live in `video.steps.js`. Recording starts at context creation only — `When I start video recording` closes + reopens the context, losing page state. Call before any navigation.
167
+
168
+ ### `javascript` — page-error / console capture
169
+
170
+ ```js
171
+ javascript: {
172
+ mode: 'warn', // WEBSHIP_JS_ERROR_MODE — 'warn' | 'fail' | 'off'
173
+ levels: ['error'], // WEBSHIP_JS_ERROR_LEVELS (csv) — console levels to capture
174
+ ignore: '', // WEBSHIP_JS_ERROR_IGNORE — regex of messages to drop
175
+ beforeScenario: false, // WEBSHIP_JS_ERROR_BEFORE — snapshot pre-existing errors
176
+ afterScenario: true, // WEBSHIP_JS_ERROR_AFTER — report at scenario end
177
+ }
178
+ ```
179
+
180
+ Tags override `mode` per scenario:
181
+
182
+ | Tag | Effect |
183
+ | --- | --- |
184
+ | `@js-fail` / `@javascript` (legacy) | force `fail` |
185
+ | `@js-warn` | force `warn` |
186
+ | `@js-off` / `@js-errors` (legacy) | force `off` |
187
+
188
+ The explicit step `Then there should be no JavaScript errors` always asserts (independent of mode).
189
+
139
190
  ### `diffy` — visual-diff integration (optional)
140
191
 
141
192
  ```js
@@ -0,0 +1,43 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="UTF-8">
5
+ <title>🎬 Video Demo</title>
6
+ <style>
7
+ body { font-family: system-ui, sans-serif; max-width: 720px; margin: 2rem auto; padding: 1rem; background: linear-gradient(180deg, #fdf6e3 0%, #eee8d5 100%); color: #073642; }
8
+ h1 { font-size: 2rem; }
9
+ main { background: #fff; border-radius: 12px; padding: 2rem; box-shadow: 0 4px 20px rgba(0,0,0,0.08); }
10
+ button { font-size: 1.1rem; padding: 0.6rem 1.2rem; background: #268bd2; color: #fff; border: 0; border-radius: 8px; cursor: pointer; margin-right: 0.5rem; }
11
+ button:hover { background: #2aa198; }
12
+ .status { font-size: 1.4rem; padding: 1rem; margin-top: 1rem; border-radius: 8px; background: #fdf6e3; min-height: 2rem; }
13
+ .smile { font-size: 3rem; }
14
+ </style>
15
+ </head>
16
+ <body>
17
+ <h1>🎬 Webship-js Video Demo</h1>
18
+ <main role="main">
19
+ <p>Click a button below — the recording captures the page state change.</p>
20
+ <button id="wave">👋 Wave</button>
21
+ <button id="rocket">🚀 Launch</button>
22
+ <button id="party">🎉 Celebrate</button>
23
+ <div class="status" id="status">Ready to record ⏺️</div>
24
+ <div class="smile" id="smile"></div>
25
+ </main>
26
+ <script>
27
+ const status = document.getElementById('status');
28
+ const smile = document.getElementById('smile');
29
+ document.getElementById('wave').addEventListener('click', () => {
30
+ status.textContent = 'Hello, world 👋';
31
+ smile.textContent = '😀';
32
+ });
33
+ document.getElementById('rocket').addEventListener('click', () => {
34
+ status.textContent = 'Liftoff! 🚀';
35
+ smile.textContent = '🌕';
36
+ });
37
+ document.getElementById('party').addEventListener('click', () => {
38
+ status.textContent = 'Party time 🎉';
39
+ smile.textContent = '🥳';
40
+ });
41
+ </script>
42
+ </body>
43
+ </html>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "webship-js",
3
- "version": "2.0.3",
3
+ "version": "2.0.4",
4
4
  "description": "Webship JS automated functional testing.",
5
5
  "main": "index.js",
6
6
  "bin": {
@@ -0,0 +1,18 @@
1
+ @video
2
+ Feature: 🎬 Video recording
3
+
4
+ As a tester, I want to record a short browser video so that I can attach it
5
+ to a bug report and let reviewers replay what happened.
6
+
7
+ Scenario: 🎥 Record a tiny click flow with emojis
8
+ When I start video recording
9
+ Given I am on "/video-demo.html"
10
+ Then I should see "Webship-js Video Demo"
11
+ When I press "👋 Wave"
12
+ Then I should see "Hello, world"
13
+ When I press "🚀 Launch"
14
+ Then I should see "Liftoff!"
15
+ When I press "🎉 Celebrate"
16
+ Then I should see "Party time"
17
+ When I save the current video as "demo.webm"
18
+ When I stop video recording
@@ -1,5 +1,7 @@
1
1
  'use strict';
2
2
 
3
+ const { friendly } = require('./webship');
4
+
3
5
  // Accessibility (a11y) step definitions.
4
6
  //
5
7
  // Two layers:
@@ -51,7 +53,7 @@ function summariseViolations(violations) {
51
53
 
52
54
  async function runAxe(world, opts = {}) {
53
55
  if (!AxeBuilder) {
54
- throw new Error('axe-core a11y steps require @axe-core/playwright. Install: npm i @axe-core/playwright axe-core');
56
+ throw friendly('axe-core a11y steps require @axe-core/playwright. Install: npm i @axe-core/playwright axe-core');
55
57
  }
56
58
  let builder = new AxeBuilder({ page: world.page });
57
59
  if (opts.tags) builder = builder.withTags(opts.tags);
@@ -5,7 +5,7 @@
5
5
 
6
6
  const { When } = require('@cucumber/cucumber');
7
7
  const path = require('path');
8
- const { buildSelector } = require('./webship');
8
+ const { buildSelector, friendly } = require('./webship');
9
9
 
10
10
  // Wrap a Playwright action with a friendlier error pointing at the
11
11
  // failing locator + Gherkin step. Pass `label` describing the step
@@ -15,7 +15,7 @@ async function actOrExplain(label, target, fn) {
15
15
  await fn();
16
16
  } catch (e) {
17
17
  const msg = (e.message || '').split('\n')[0];
18
- throw new Error(
18
+ throw friendly(
19
19
  `Failed to ${label} "${target}".\n` +
20
20
  ` ${msg}\n` +
21
21
  ` Hints:\n` +
@@ -1,6 +1,7 @@
1
1
  const { Given, When, Then, Before } = require('@cucumber/cucumber');
2
2
  const axios = require('axios');
3
3
  const assert = require('assert');
4
+ const { friendly } = require('./webship');
4
5
 
5
6
  // Global variables to store API response and request data
6
7
  let apiResponse = null;
@@ -163,7 +164,7 @@ Given(/^(?:I set the request body to|we set the request body to|the request body
163
164
  const processedData = replacePlaceHolder(jsonData);
164
165
  apiRequestData = JSON.parse(processedData);
165
166
  } catch (error) {
166
- throw new Error(`Invalid JSON in request body: ${error.message}`);
167
+ throw friendly(`Invalid JSON in request body: ${error.message}`);
167
168
  }
168
169
  });
169
170
 
@@ -232,7 +233,7 @@ When(/^(?:I |we )?send a ([A-Z]+) request to "([^"]+)"$/, async function (method
232
233
  }
233
234
  });
234
235
  } catch (error) {
235
- throw new Error(`${method} request failed: ${error.message}`);
236
+ throw friendly(`${method} request failed: ${error.message}`);
236
237
  }
237
238
  });
238
239
 
@@ -278,7 +279,7 @@ When(/^(?:I |we )?send a ([A-Z]+) request to "([^"]+)" with values:$/, async fun
278
279
  }
279
280
  });
280
281
  } catch (error) {
281
- throw new Error(`${method} request with values failed: ${error.message}`);
282
+ throw friendly(`${method} request with values failed: ${error.message}`);
282
283
  }
283
284
  });
284
285
 
@@ -351,7 +352,7 @@ When(/^(?:I |we )?send a ([A-Z]+) request to "([^"]+)" with body:$/, async funct
351
352
  }
352
353
  });
353
354
  } catch (error) {
354
- throw new Error(`${method} request with body failed: ${error.message}`);
355
+ throw friendly(`${method} request with body failed: ${error.message}`);
355
356
  }
356
357
  });
357
358
 
@@ -416,7 +417,7 @@ When(/^(?:I |we )?send a ([A-Z]+) request to "([^"]+)" with form data:$/, async
416
417
  }
417
418
  });
418
419
  } catch (error) {
419
- throw new Error(`${method} request with form data failed: ${error.message}`);
420
+ throw friendly(`${method} request with form data failed: ${error.message}`);
420
421
  }
421
422
  });
422
423
 
@@ -436,7 +437,7 @@ When(/^(?:I |we )?send a ([A-Z]+) request to "([^"]+)" with form data:$/, async
436
437
  */
437
438
  Then(/^(?:the )?API response code should be (\d+)$/, function (expectedCode) {
438
439
  if (!apiResponse) {
439
- throw new Error('No API response available. Make sure to send a request first.');
440
+ throw friendly('No API response available. Make sure to send a request first.');
440
441
  }
441
442
 
442
443
  const expected = parseInt(expectedCode);
@@ -459,7 +460,7 @@ Then(/^(?:the )?API response code should be (\d+)$/, function (expectedCode) {
459
460
  */
460
461
  Then(/^(?:the )?API response should contain "([^"]*)"$/, function (expectedText) {
461
462
  if (!apiResponse) {
462
- throw new Error('No API response available. Make sure to send a request first.');
463
+ throw friendly('No API response available. Make sure to send a request first.');
463
464
  }
464
465
 
465
466
  const responseBody = typeof apiResponse.data === 'string' ?
@@ -484,7 +485,7 @@ Then(/^(?:the )?API response should contain "([^"]*)"$/, function (expectedText)
484
485
  */
485
486
  Then(/^(?:the )?API response should not contain "([^"]*)"$/, function (unexpectedText) {
486
487
  if (!apiResponse) {
487
- throw new Error('No API response available. Make sure to send a request first.');
488
+ throw friendly('No API response available. Make sure to send a request first.');
488
489
  }
489
490
 
490
491
  const responseBody = typeof apiResponse.data === 'string' ?
@@ -531,7 +532,7 @@ Then(/^(?:the )?API response should not contain "([^"]*)"$/, function (unexpecte
531
532
  */
532
533
  Then(/^(?:the )?API response should contain json:$/, function (docString) {
533
534
  if (!apiResponse) {
534
- throw new Error('No API response available. Make sure to send a request first.');
535
+ throw friendly('No API response available. Make sure to send a request first.');
535
536
  }
536
537
 
537
538
  let expectedJson;
@@ -540,14 +541,14 @@ Then(/^(?:the )?API response should contain json:$/, function (docString) {
540
541
  try {
541
542
  expectedJson = JSON.parse(replacePlaceHolder(docString.trim()));
542
543
  } catch (error) {
543
- throw new Error(`Cannot convert expected JSON: ${docString}`);
544
+ throw friendly(`Cannot convert expected JSON: ${docString}`);
544
545
  }
545
546
 
546
547
  try {
547
548
  actualJson = typeof apiResponse.data === 'string' ?
548
549
  JSON.parse(apiResponse.data) : apiResponse.data;
549
550
  } catch (error) {
550
- throw new Error(`Cannot convert actual response to JSON: ${apiResponse.data}`);
551
+ throw friendly(`Cannot convert actual response to JSON: ${apiResponse.data}`);
551
552
  }
552
553
 
553
554
  // Check that expected properties exist in actual response and match values
@@ -573,7 +574,7 @@ Then(/^(?:the )?API response should contain json:$/, function (docString) {
573
574
  */
574
575
  Then(/^(?:the JSON response should have|the API response should have|the JSON property) "([^"]*)" (?:equal to|should be) (.+)$/, function (propertyPath, expectedValue) {
575
576
  if (!apiResponse) {
576
- throw new Error('No API response available. Make sure to send a request first.');
577
+ throw friendly('No API response available. Make sure to send a request first.');
577
578
  }
578
579
 
579
580
  // Replace placeholders in expected value first
@@ -612,7 +613,7 @@ Then(/^(?:the JSON response should have|the API response should have|the JSON pr
612
613
  */
613
614
  Then(/^(?:the JSON response should have property|the API response should contain property) "([^"]*)"$/, function (propertyPath) {
614
615
  if (!apiResponse) {
615
- throw new Error('No API response available. Make sure to send a request first.');
616
+ throw friendly('No API response available. Make sure to send a request first.');
616
617
  }
617
618
 
618
619
  const actualValue = getNestedProperty(apiResponse.data, propertyPath);
@@ -635,7 +636,7 @@ Then(/^(?:the JSON response should have property|the API response should contain
635
636
  */
636
637
  Then(/^(?:the JSON response should not have property|the API response should not contain property) "([^"]*)"$/, function (propertyPath) {
637
638
  if (!apiResponse) {
638
- throw new Error('No API response available. Make sure to send a request first.');
639
+ throw friendly('No API response available. Make sure to send a request first.');
639
640
  }
640
641
 
641
642
  const actualValue = getNestedProperty(apiResponse.data, propertyPath);
@@ -659,7 +660,7 @@ Then(/^(?:the JSON response should not have property|the API response should not
659
660
  */
660
661
  Then(/^(?:the response should be valid JSON|the API response should be valid JSON)$/, function () {
661
662
  if (!apiResponse) {
662
- throw new Error('No API response available. Make sure to send a request first.');
663
+ throw friendly('No API response available. Make sure to send a request first.');
663
664
  }
664
665
 
665
666
  assert(typeof apiResponse.data === 'object' && apiResponse.data !== null,
@@ -680,7 +681,7 @@ Then(/^(?:the response should be valid JSON|the API response should be valid JSO
680
681
  */
681
682
  Then(/^(?:the response header|the header) "([^"]*)" should (?:be|contain) "([^"]*)"$/, function (headerName, expectedValue) {
682
683
  if (!apiResponse) {
683
- throw new Error('No API response available. Make sure to send a request first.');
684
+ throw friendly('No API response available. Make sure to send a request first.');
684
685
  }
685
686
 
686
687
  const actualValue = apiResponse.headers[headerName.toLowerCase()];
@@ -11,7 +11,7 @@
11
11
  const { Then } = require('@cucumber/cucumber');
12
12
  const assert = require('assert');
13
13
  const axios = require('axios');
14
- const { buildSelector, getLocatorText } = require('./webship');
14
+ const { buildSelector, getLocatorText, friendly } = require('./webship');
15
15
 
16
16
  // ---------------------------------------------------------------------------
17
17
  // Plain page-text
@@ -257,7 +257,7 @@ Then(/^(I |we )*should see (\d+) "([^"]*)" elements?$/, async function (pronounC
257
257
  const expected = parseInt(num, 10);
258
258
  const actual = await this.page.locator(selector).count();
259
259
  if (actual !== expected) {
260
- throw new Error(`Expected ${expected} "${selector}" element(s), got ${actual}.`);
260
+ throw friendly(`Expected ${expected} "${selector}" element(s), got ${actual}.`);
261
261
  }
262
262
  });
263
263
 
@@ -1,5 +1,7 @@
1
1
  'use strict';
2
2
 
3
+ const { friendly } = require('./webship');
4
+
3
5
  // Authentication-state helpers built on Playwright's `storageState` API.
4
6
  //
5
7
  // Save the cookies + localStorage of an authenticated context to a JSON file
@@ -73,7 +75,7 @@ When(/^(I |we )*save the auth state to "([^"]*)"$/, async function (pronoun, tar
73
75
  Given(/^(I |we )*restore the auth state from "([^"]*)"$/, async function (pronoun, source) {
74
76
  const file = resolveStoragePath(source);
75
77
  if (!fs.existsSync(file)) {
76
- throw new Error(`Auth state file not found: ${file}`);
78
+ throw friendly(`Auth state file not found: ${file}`);
77
79
  }
78
80
  const playwrightConfig = require(path.join(process.cwd(), 'playwright.config'));
79
81
  const newContext = await this.playwrightBrowser.newContext({
@@ -1,43 +1,37 @@
1
1
  'use strict';
2
2
 
3
+ const { friendly } = require('./webship');
4
+
3
5
  // Clock / time-mocking steps backed by Playwright's `page.clock` API.
4
- //
5
- // Useful for testing relative-time UIs ("5 minutes ago"), debounced inputs,
6
- // throttled re-renders, scheduled UI changes (toast auto-dismiss, session
7
- // timeout), and any flow gated on `Date.now()` or `setTimeout`.
8
- //
9
- // Once the fake clock is installed, page-level `Date.now()` and `new Date()`
10
- // return the fake time, and pending timers stay paused until explicitly
11
- // advanced.
12
6
 
13
7
  const { Given, When } = require('@cucumber/cucumber');
14
8
 
9
+ const ISO_HINT = 'install the fake clock first via "Given the system time is \\"YYYY-MM-DDTHH:MM:SSZ\\"".';
10
+
15
11
  /**
16
12
  * Install a fake clock anchored at an ISO 8601 instant.
17
13
  *
18
- * After this step, `Date.now()` inside the page returns the fake time and
19
- * `setTimeout` / `setInterval` callbacks queue but do not fire until you
20
- * advance the clock.
21
- *
22
14
  * Example #1: Given the system time is "2026-05-08T10:00:00Z"
23
15
  * Example #2: Given the system time is "2026-01-01T00:00:00Z"
24
- * And I am on "/feed"
25
16
  * Example #3: Given the system time is "2026-12-31T23:59:55Z"
26
- * And I am on "/countdown"
27
17
  * Example #4: Given the system time is "2026-05-08T10:00:00Z"
28
- * And I am on "/feed"
29
- * And "<.timestamp>" should have text "just now"
30
18
  * Example #5: Given the system time is "2026-07-04T12:00:00-04:00"
31
- * And I am on "/holiday-banner"
32
19
  *
33
20
  */
34
21
  Given(/^the system time is "([^"]*)"$/, async function (iso) {
35
- await this.page.clock.install({ time: new Date(iso) });
22
+ const d = new Date(iso);
23
+ if (isNaN(d.getTime())) {
24
+ throw friendly({
25
+ action: `set the system time to "${iso}"`,
26
+ hint: 'use an ISO 8601 date like "2026-05-08T10:00:00Z".',
27
+ });
28
+ }
29
+ try { await this.page.clock.install({ time: d }); }
30
+ catch (e) { throw friendly({ action: `install a fake clock at "${iso}"`, cause: e, hint: 'open a page first via "Given I am on \\"/path\\"".' }); }
36
31
  });
37
32
 
38
33
  /**
39
- * Advance the fake clock forward by N milliseconds, firing every queued
40
- * `setTimeout` / `setInterval` callback scheduled within that interval.
34
+ * Advance the fake clock forward by N milliseconds.
41
35
  *
42
36
  * Example #1: When I advance the clock by 500 ms
43
37
  * Example #2: When I advance the clock by 1500 ms
@@ -47,7 +41,8 @@ Given(/^the system time is "([^"]*)"$/, async function (iso) {
47
41
  *
48
42
  */
49
43
  When(/^(I |we )*advance the clock by (\d+) ?ms$/, async function (pronoun, ms) {
50
- await this.page.clock.runFor(parseInt(ms, 10));
44
+ try { await this.page.clock.runFor(parseInt(ms, 10)); }
45
+ catch (e) { throw friendly({ action: `advance the clock by ${ms} ms`, cause: e, hint: ISO_HINT }); }
51
46
  });
52
47
 
53
48
  /**
@@ -61,7 +56,8 @@ When(/^(I |we )*advance the clock by (\d+) ?ms$/, async function (pronoun, ms) {
61
56
  *
62
57
  */
63
58
  When(/^(I |we )*advance the clock by (\d+) seconds?$/, async function (pronoun, seconds) {
64
- await this.page.clock.runFor(parseInt(seconds, 10) * 1000);
59
+ try { await this.page.clock.runFor(parseInt(seconds, 10) * 1000); }
60
+ catch (e) { throw friendly({ action: `advance the clock by ${seconds} second(s)`, cause: e, hint: ISO_HINT }); }
65
61
  });
66
62
 
67
63
  /**
@@ -75,46 +71,42 @@ When(/^(I |we )*advance the clock by (\d+) seconds?$/, async function (pronoun,
75
71
  *
76
72
  */
77
73
  When(/^(I |we )*advance the clock by (\d+) minutes?$/, async function (pronoun, minutes) {
78
- await this.page.clock.runFor(parseInt(minutes, 10) * 60 * 1000);
74
+ try { await this.page.clock.runFor(parseInt(minutes, 10) * 60 * 1000); }
75
+ catch (e) { throw friendly({ action: `advance the clock by ${minutes} minute(s)`, cause: e, hint: ISO_HINT }); }
79
76
  });
80
77
 
81
78
  /**
82
- * Pause the fake clock — no further timer callbacks fire until resumed or
83
- * explicitly advanced. Useful between actions when you do not want a long
84
- * tick to fire mid-step.
79
+ * Pause the fake clock.
85
80
  *
86
81
  * Example #1: When I pause the clock
87
- * Example #2: Given the system time is "2026-05-08T10:00:00Z"
88
- * When I pause the clock
82
+ * Example #2: When I pause the clock
89
83
  * Example #3: When we pause the clock
90
84
  * Example #4: And I pause the clock
91
85
  * Example #5: When I pause the clock
92
- * Then "<.timer>" should have text "00:00"
93
86
  *
94
87
  */
95
88
  When(/^(I |we )*pause the clock$/, async function () {
96
- await this.page.clock.pauseAt(await this.page.evaluate(() => Date.now()));
89
+ try { await this.page.clock.pauseAt(await this.page.evaluate(() => Date.now())); }
90
+ catch (e) { throw friendly({ action: 'pause the clock', cause: e, hint: ISO_HINT }); }
97
91
  });
98
92
 
99
93
  /**
100
- * Resume the fake clock from the current paused time.
94
+ * Resume the fake clock.
101
95
  *
102
96
  * Example #1: When I resume the clock
103
- * Example #2: When I pause the clock
104
- * And I resume the clock
97
+ * Example #2: When I resume the clock
105
98
  * Example #3: When we resume the clock
106
99
  * Example #4: And I resume the clock
107
100
  * Example #5: When I resume the clock
108
- * And I advance the clock by 5 seconds
109
101
  *
110
102
  */
111
103
  When(/^(I |we )*resume the clock$/, async function () {
112
- await this.page.clock.resume();
104
+ try { await this.page.clock.resume(); }
105
+ catch (e) { throw friendly({ action: 'resume the clock', cause: e, hint: 'pause the clock first via "When I pause the clock".' }); }
113
106
  });
114
107
 
115
108
  /**
116
- * Set the fake clock to a specific time WITHOUT advancing through it. Use
117
- * `advance` if you want pending timers in the gap to fire.
109
+ * Set the fake clock to a specific time.
118
110
  *
119
111
  * Example #1: When I set the system time to "2026-05-08T12:30:00Z"
120
112
  * Example #2: When I set the system time to "2026-12-31T23:59:55Z"
@@ -124,5 +116,13 @@ When(/^(I |we )*resume the clock$/, async function () {
124
116
  *
125
117
  */
126
118
  When(/^(I |we )*set the system time to "([^"]*)"$/, async function (pronoun, iso) {
127
- await this.page.clock.setSystemTime(new Date(iso));
119
+ const d = new Date(iso);
120
+ if (isNaN(d.getTime())) {
121
+ throw friendly({
122
+ action: `set the system time to "${iso}"`,
123
+ hint: 'use an ISO 8601 date like "2026-05-08T12:30:00Z".',
124
+ });
125
+ }
126
+ try { await this.page.clock.setSystemTime(d); }
127
+ catch (e) { throw friendly({ action: `set the system time to "${iso}"`, cause: e, hint: ISO_HINT }); }
128
128
  });
@@ -13,8 +13,12 @@ const { Then } = require('@cucumber/cucumber');
13
13
  * Example #3: And print current URL
14
14
  */
15
15
  Then(/^print current URL$/, function () {
16
- console.log('\n--- Current URL ---');
17
- console.log(` ${this.page.url()}`);
16
+ try {
17
+ console.log('\n--- Current URL ---');
18
+ console.log(` ${this.page.url()}`);
19
+ } catch (e) {
20
+ console.log(`\n--- Current URL unavailable: ${e.message} ---`);
21
+ }
18
22
  });
19
23
 
20
24
  /**
@@ -25,7 +29,11 @@ Then(/^print current URL$/, function () {
25
29
  * Example #3: And print last response
26
30
  */
27
31
  Then(/^print last response$/, async function () {
28
- const html = await this.page.content();
29
- console.log('\n--- Last Response (HTML) ---');
30
- console.log(html);
32
+ try {
33
+ const html = await this.page.content();
34
+ console.log('\n--- Last Response (HTML) ---');
35
+ console.log(html);
36
+ } catch (e) {
37
+ console.log(`\n--- Last response unavailable: ${e.message} ---`);
38
+ }
31
39
  });