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
@@ -2,70 +2,231 @@
2
2
 
3
3
  // Auto-detect JavaScript errors during test execution.
4
4
  //
5
- // Errors collected from page.on('pageerror') and page.on('console') (level=error).
6
- // Always tracked once a page is opened. Final assertion runs only when:
7
- // - the scenario is tagged @javascript (asserts no errors at scenario end), OR
8
- // - the test explicitly calls "Then there should be no JavaScript errors".
9
- // Use the @js-errors tag to suppress the @javascript assertion when errors
10
- // are intentionally expected.
5
+ // Listeners are attached on Before (order 200) once a page is open:
6
+ // page.on('pageerror') → uncaught errors
7
+ // page.on('console', level) → console messages (filtered by config)
8
+ //
9
+ // After every scenario the collector reports per the active "mode":
10
+ // - 'warn' (default) → log a yellow warning, scenario still passes
11
+ // - 'fail' → assert.fail with the error list
12
+ // - 'off' → silent
13
+ //
14
+ // Mode resolution priority (first match wins):
15
+ // 1. scenario tag @js-fail / @js-warn / @js-off / @javascript / @js-errors
16
+ // 2. env var WEBSHIP_JS_ERROR_MODE = warn | fail | off
17
+ // 3. worldParameters parameters.javascript.mode
18
+ // 4. default 'warn'
19
+ //
20
+ // Back-compat: @javascript → fail (legacy "always fail" tag). @js-errors → off.
11
21
 
12
22
  const { Before, After, Then } = require('@cucumber/cucumber');
13
23
  const assert = require('assert');
14
24
 
15
- function hasTag(scenario, name) {
16
- if (!scenario || !Array.isArray(scenario.pickle && scenario.pickle.tags)) return false;
17
- return scenario.pickle.tags.some((t) => t.name === name);
25
+ const VALID_MODES = new Set(['warn', 'fail', 'off']);
26
+ const DEFAULT_CONSOLE_LEVELS = ['error'];
27
+
28
+ /**
29
+ * Resolve effective settings for the current scenario.
30
+ *
31
+ * @returns {{ mode: 'warn'|'fail'|'off', levels: string[], ignore: RegExp|null,
32
+ * beforeScenario: boolean, afterScenario: boolean }}
33
+ */
34
+ function resolveSettings(world, scope) {
35
+ const cfg = (world.parameters && world.parameters.javascript) || {};
36
+ const tag = (name) => hasTag(scope, name);
37
+
38
+ let mode;
39
+ if (tag('@js-fail') || tag('@javascript')) mode = 'fail';
40
+ else if (tag('@js-warn')) mode = 'warn';
41
+ else if (tag('@js-off') || tag('@js-errors')) mode = 'off';
42
+ else if (process.env.WEBSHIP_JS_ERROR_MODE) mode = process.env.WEBSHIP_JS_ERROR_MODE;
43
+ else if (cfg.mode) mode = cfg.mode;
44
+ else mode = 'warn';
45
+ if (!VALID_MODES.has(mode)) mode = 'warn';
46
+
47
+ const levelsRaw =
48
+ process.env.WEBSHIP_JS_ERROR_LEVELS ||
49
+ (Array.isArray(cfg.levels) ? cfg.levels.join(',') : cfg.levels) ||
50
+ DEFAULT_CONSOLE_LEVELS.join(',');
51
+ const levels = String(levelsRaw).split(',').map((s) => s.trim()).filter(Boolean);
52
+
53
+ const ignoreSrc = process.env.WEBSHIP_JS_ERROR_IGNORE || cfg.ignore || null;
54
+ let ignore = null;
55
+ if (ignoreSrc) {
56
+ try { ignore = new RegExp(ignoreSrc); }
57
+ catch { ignore = null; }
58
+ }
59
+
60
+ const beforeScenario =
61
+ process.env.WEBSHIP_JS_ERROR_BEFORE === '1'
62
+ ? true
63
+ : cfg.beforeScenario === true;
64
+ const afterScenario =
65
+ process.env.WEBSHIP_JS_ERROR_AFTER === '0'
66
+ ? false
67
+ : cfg.afterScenario !== false; // default true
68
+
69
+ return { mode, levels, ignore, beforeScenario, afterScenario };
70
+ }
71
+
72
+ function hasTag(scope, name) {
73
+ if (!scope || !Array.isArray(scope.pickle && scope.pickle.tags)) return false;
74
+ return scope.pickle.tags.some((t) => t.name === name);
75
+ }
76
+
77
+ function formatErrors(errs) {
78
+ return errs.map((e, i) => ` ${i + 1}. [${e.type}] ${e.message}`).join('\n');
79
+ }
80
+
81
+ function filterErrors(errs, ignore) {
82
+ if (!ignore) return errs;
83
+ return errs.filter((e) => !ignore.test(e.message));
84
+ }
85
+
86
+ function reportWarning(scope, errs) {
87
+ const name = (scope && scope.pickle && scope.pickle.name) || 'scenario';
88
+ // Yellow ANSI when FORCE_COLOR is on, plain otherwise — let the runtime
89
+ // decide. cucumber-js sets FORCE_COLOR=1 by default in interactive shells.
90
+ const head = `[webship-js] JavaScript errors during "${name}" (mode=warn):`;
91
+ process.stderr.write(`\n\x1b[33m${head}\n${formatErrors(errs)}\x1b[0m\n`);
18
92
  }
19
93
 
94
+ // ---------------------------------------------------------------------------
95
+ // Before — attach listeners + (optional) pre-snapshot.
96
+ // ---------------------------------------------------------------------------
97
+
20
98
  Before({ order: 200 }, function (scope) {
21
99
  this._jsErrors = [];
22
100
  this._jsErrorsAsserted = false;
23
- this._jsErrorsAutoAssert = hasTag(scope, '@javascript');
101
+ this._jsSettings = resolveSettings(this, scope);
102
+ if (this._jsSettings.mode === 'off') return;
24
103
  if (!this.page) return;
104
+
105
+ const levels = new Set(this._jsSettings.levels);
25
106
  this.page.on('pageerror', (err) => {
26
107
  this._jsErrors.push({ type: 'pageerror', message: String(err && err.message || err) });
27
108
  });
28
109
  this.page.on('console', (msg) => {
29
- if (msg.type() === 'error') {
30
- this._jsErrors.push({ type: 'console.error', message: msg.text() });
110
+ if (levels.has(msg.type())) {
111
+ this._jsErrors.push({ type: `console.${msg.type()}`, message: msg.text() });
31
112
  }
32
113
  });
114
+
115
+ if (this._jsSettings.beforeScenario) {
116
+ // Pre-scenario snapshot — typically empty unless the same page is reused.
117
+ const errs = filterErrors(this._jsErrors, this._jsSettings.ignore);
118
+ if (errs.length > 0) {
119
+ process.stderr.write(
120
+ `\n\x1b[33m[webship-js] Pre-scenario JavaScript errors:\n${formatErrors(errs)}\x1b[0m\n`
121
+ );
122
+ }
123
+ }
33
124
  });
34
125
 
126
+ // ---------------------------------------------------------------------------
127
+ // Steps
128
+ // ---------------------------------------------------------------------------
129
+
35
130
  /**
36
131
  * Assert that no JavaScript errors have been collected so far.
37
132
  *
38
- * Errors are tracked from page open (page errors + console.error). Calling
39
- * this step asserts the error log is empty and prevents the auto-assert at
40
- * scenario end (so it does not double-fire).
133
+ * Always fails on error (ignoring the active mode) — this is the explicit
134
+ * "hard check" step. Calling it also prevents the auto-report at scenario
135
+ * end so a single error is not reported twice.
41
136
  *
42
137
  * Example #1: Then there should be no JavaScript errors
43
- * Example #2: Given I am on the homepage
44
- * Then there should be no JavaScript errors
45
- * Example #3: When I follow "Pricing"
46
- * And I wait until the network is idle
47
- * Then there should be no JavaScript errors
48
- * Example #4: When I press "Add to cart"
49
- * Then there should be no JavaScript errors
50
- * Example #5: Given I am on "/dashboard"
51
- * And I scroll to the bottom
52
- * Then there should be no JavaScript errors
138
+ * Example #2: And there should be no JavaScript errors
139
+ * Example #3: But there should be no JavaScript errors
140
+ * Example #4: Then there should be no JavaScript errors
141
+ * Example #5: Then there should be no JavaScript errors
53
142
  *
54
143
  */
55
144
  Then(/^there should be no JavaScript errors$/, function () {
56
145
  this._jsErrorsAsserted = true;
57
- const errs = this._jsErrors || [];
146
+ const errs = filterErrors(this._jsErrors || [], this._jsSettings && this._jsSettings.ignore);
58
147
  if (errs.length === 0) return;
59
- const summary = errs.map((e, i) => ` ${i + 1}. [${e.type}] ${e.message}`).join('\n');
60
- assert.fail(`JavaScript errors detected:\n${summary}`);
148
+ assert.fail(`JavaScript errors detected:\n${formatErrors(errs)}`);
61
149
  });
62
150
 
63
- After({ order: 200 }, function (scope) {
64
- if (!this._jsErrorsAutoAssert) return;
65
- if (hasTag(scope, '@js-errors')) return;
66
- if (this._jsErrorsAsserted) return;
151
+ /**
152
+ * Assert that no JavaScript console warnings were collected. Requires
153
+ * 'warning' to be in the captured console levels (see worldParameters or
154
+ * WEBSHIP_JS_ERROR_LEVELS).
155
+ *
156
+ * Example #1: Then there should be no JavaScript warnings
157
+ * Example #2: And there should be no JavaScript warnings
158
+ * Example #3: But there should be no JavaScript warnings
159
+ * Example #4: Then there should be no JavaScript warnings
160
+ * Example #5: Then there should be no JavaScript warnings
161
+ *
162
+ */
163
+ Then(/^there should be no JavaScript warnings$/, function () {
164
+ this._jsErrorsAsserted = true;
165
+ const errs = (this._jsErrors || []).filter((e) => e.type === 'console.warning');
166
+ if (errs.length === 0) return;
167
+ assert.fail(`JavaScript warnings detected:\n${formatErrors(errs)}`);
168
+ });
169
+
170
+ /**
171
+ * Assert that no collected JavaScript error message matches a regular
172
+ * expression. Useful when some noise is unavoidable but a specific bug
173
+ * pattern must never appear.
174
+ *
175
+ * Example #1: Then JavaScript errors should not match "TypeError"
176
+ * Example #2: Then JavaScript errors should not match "is not a function"
177
+ * Example #3: And JavaScript errors should not match "Cannot read property"
178
+ * Example #4: Then JavaScript errors should not match "ReferenceError: .* is not defined"
179
+ * Example #5: Then JavaScript errors should not match "Uncaught"
180
+ *
181
+ */
182
+ Then(/^JavaScript errors should not match "([^"]*)"$/, function (pattern) {
183
+ let re;
184
+ try { re = new RegExp(pattern); }
185
+ catch (e) {
186
+ assert.fail(`Invalid regular expression: "${pattern}" — ${e.message}`);
187
+ }
188
+ const errs = (this._jsErrors || []).filter((e) => re.test(e.message));
189
+ if (errs.length === 0) return;
190
+ assert.fail(`JavaScript errors matched /${pattern}/:\n${formatErrors(errs)}`);
191
+ });
192
+
193
+ /**
194
+ * Print the JavaScript errors collected so far. Diagnostic only — never
195
+ * asserts, never fails. Useful inside a scenario being debugged.
196
+ *
197
+ * Example #1: Then print JavaScript errors
198
+ * Example #2: And print JavaScript errors
199
+ * Example #3: But print JavaScript errors
200
+ * Example #4: Then print JavaScript errors
201
+ * Example #5: Then print JavaScript errors
202
+ *
203
+ */
204
+ Then(/^print JavaScript errors$/, function () {
67
205
  const errs = this._jsErrors || [];
206
+ if (errs.length === 0) {
207
+ console.log('\n--- JavaScript errors: none ---');
208
+ return;
209
+ }
210
+ console.log('\n--- JavaScript errors ---');
211
+ console.log(formatErrors(errs));
212
+ });
213
+
214
+ // ---------------------------------------------------------------------------
215
+ // After — report per mode.
216
+ // ---------------------------------------------------------------------------
217
+
218
+ After({ order: 200 }, function (scope) {
219
+ const s = this._jsSettings || resolveSettings(this, scope);
220
+ if (s.mode === 'off') return;
221
+ if (!s.afterScenario) return;
222
+ if (this._jsErrorsAsserted) return; // already handled by explicit step
223
+
224
+ const errs = filterErrors(this._jsErrors || [], s.ignore);
68
225
  if (errs.length === 0) return;
69
- const summary = errs.map((e, i) => ` ${i + 1}. [${e.type}] ${e.message}`).join('\n');
70
- assert.fail(`JavaScript errors detected during scenario:\n${summary}`);
226
+
227
+ if (s.mode === 'fail') {
228
+ assert.fail(`JavaScript errors detected during scenario:\n${formatErrors(errs)}`);
229
+ } else {
230
+ reportWarning(scope, errs);
231
+ }
71
232
  });
@@ -1,5 +1,7 @@
1
1
  'use strict';
2
2
 
3
+ const { friendly } = require('./webship');
4
+
3
5
  // Simulate keyboard interactions on the page or on a specific element.
4
6
 
5
7
  const { When } = require('@cucumber/cucumber');
@@ -31,7 +33,15 @@ function normalizeKey(key) {
31
33
  *
32
34
  */
33
35
  When(/^(I |we )*press the key "([^"]*)"$/, async function (pronoun, key) {
34
- await this.page.keyboard.press(normalizeKey(key));
36
+ try {
37
+ await this.page.keyboard.press(normalizeKey(key));
38
+ } catch (e) {
39
+ throw friendly({
40
+ action: `press the key "${key}"`,
41
+ cause: e,
42
+ hint: `use a real key name like Enter, Escape, Tab, ArrowDown, or a short alias (enter, esc, tab, up, down, left, right, space).`,
43
+ });
44
+ }
35
45
  });
36
46
 
37
47
  /**
@@ -45,7 +55,15 @@ When(/^(I |we )*press the key "([^"]*)"$/, async function (pronoun, key) {
45
55
  *
46
56
  */
47
57
  When(/^(I |we )*press the key "([^"]*)" on the element "([^"]*)"$/, async function (pronoun, key, sel) {
48
- await this.page.locator(sel).first().press(normalizeKey(key));
58
+ try {
59
+ await this.page.locator(sel).first().press(normalizeKey(key));
60
+ } catch (e) {
61
+ throw friendly({
62
+ action: `press the key "${key}" on "${sel}"`,
63
+ cause: e,
64
+ hint: `check that "${sel}" matches an element on the page that can be focused (input, button, link).`,
65
+ });
66
+ }
49
67
  });
50
68
 
51
69
  /**
@@ -60,7 +78,15 @@ When(/^(I |we )*press the key "([^"]*)" on the element "([^"]*)"$/, async functi
60
78
  *
61
79
  */
62
80
  When(/^(I |we )*press the keys "([^"]*)"$/, async function (pronoun, keys) {
63
- await this.page.keyboard.press(keys);
81
+ try {
82
+ await this.page.keyboard.press(keys);
83
+ } catch (e) {
84
+ throw friendly({
85
+ action: `press the keys "${keys}"`,
86
+ cause: e,
87
+ hint: `use a "+" between modifier and key, e.g. "Control+a", "Meta+s", or "Shift+Tab".`,
88
+ });
89
+ }
64
90
  });
65
91
 
66
92
  /**
@@ -74,5 +100,13 @@ When(/^(I |we )*press the keys "([^"]*)"$/, async function (pronoun, keys) {
74
100
  *
75
101
  */
76
102
  When(/^(I |we )*press the keys "([^"]*)" on the element "([^"]*)"$/, async function (pronoun, keys, sel) {
77
- await this.page.locator(sel).first().press(keys);
103
+ try {
104
+ await this.page.locator(sel).first().press(keys);
105
+ } catch (e) {
106
+ throw friendly({
107
+ action: `press "${keys}" on "${sel}"`,
108
+ cause: e,
109
+ hint: `check the element exists and use "+" between modifier and key, e.g. "Control+s".`,
110
+ });
111
+ }
78
112
  });
@@ -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
 
@@ -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
  });
@@ -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