webship-js 2.0.10 → 2.0.11

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 (110) hide show
  1. package/.github/ISSUE_TEMPLATE/issue.md +37 -0
  2. package/.github/PULL_REQUEST_TEMPLATE.md +24 -0
  3. package/.github/workflows/github-actions.yml +56 -4
  4. package/CLAUDE.md +5 -2
  5. package/README.md +13 -1
  6. package/bin/generate-reports.js +51 -7
  7. package/bin/init-webship.js +85 -17
  8. package/cucumber.js +29 -1
  9. package/docs/00-quick-start.md +30 -7
  10. package/docs/02-bbr-smart-waits.md +6 -0
  11. package/docs/04-step-reference.md +2 -2
  12. package/docs/11-debugging.md +21 -0
  13. package/docs/12-ai-agent-guide.md +3 -1
  14. package/docs/13-faq.md +3 -0
  15. package/docs/15-tag-conventions.md +4 -1
  16. package/docs/16-ci-cd.md +29 -13
  17. package/docs/global-settings.md +2 -2
  18. package/docs/install-webship-js/ddev-webship-js.md +3 -0
  19. package/docs/install-webship-js.md +14 -2
  20. package/examples/a11y-legacy-widget.html +34 -0
  21. package/examples/auth-state.html +42 -0
  22. package/examples/clock.html +33 -0
  23. package/examples/downloads/webship-archive.zip +0 -0
  24. package/examples/downloads/webship-notes.txt +4 -0
  25. package/examples/downloads/webship-report.csv +4 -0
  26. package/examples/downloads.html +16 -0
  27. package/examples/element-viewport.html +42 -0
  28. package/examples/field-types.html +98 -0
  29. package/examples/iframe-newsletter.html +29 -0
  30. package/examples/iframe-order.html +26 -0
  31. package/examples/iframe.html +21 -0
  32. package/examples/javascript-errors.html +35 -0
  33. package/examples/links.html +1 -0
  34. package/examples/metatags.html +18 -0
  35. package/examples/mouse-and-pointer.html +83 -0
  36. package/examples/native-dialogs.html +8 -0
  37. package/examples/network.html +83 -0
  38. package/examples/scroll-horizontal.html +50 -0
  39. package/examples/selectors-position.html +29 -0
  40. package/examples/storage.html +57 -0
  41. package/examples/viewport-size.html +24 -0
  42. package/examples/wait-conditions.html +69 -0
  43. package/examples/web-first.html +99 -0
  44. package/package.json +9 -2
  45. package/tests/assets/catalog.xml +19 -0
  46. package/tests/assets/feed-namespaced.xml +13 -0
  47. package/tests/assets/sitemap.xml +14 -0
  48. package/tests/assets/webship-site-expected.yaml +21 -0
  49. package/tests/assets/webship-site.schema.json +46 -0
  50. package/tests/assets/webship-site.yaml +21 -0
  51. package/tests/check-examples.js +235 -0
  52. package/tests/check-must-fail.js +84 -0
  53. package/tests/check-paths.js +82 -0
  54. package/tests/check-report.js +119 -0
  55. package/tests/check-scaffold.js +211 -0
  56. package/tests/features/a11y.feature +18 -0
  57. package/tests/features/auth-state.feature +32 -0
  58. package/tests/features/clock.feature +27 -0
  59. package/tests/features/cookie.feature +9 -0
  60. package/tests/features/dialog.feature +27 -0
  61. package/tests/features/element.feature +47 -0
  62. package/tests/features/field.feature +104 -0
  63. package/tests/features/file-download.feature +64 -0
  64. package/tests/features/iframe.feature +83 -0
  65. package/tests/features/javascript.feature +47 -0
  66. package/tests/features/link.feature +11 -0
  67. package/tests/features/metatag.feature +38 -0
  68. package/tests/features/mouse-and-pointer.feature +86 -0
  69. package/tests/features/network-mocking.feature +80 -0
  70. package/tests/features/responsive.feature +27 -0
  71. package/tests/features/scroll-horizontal.feature +55 -0
  72. package/tests/features/selectors-position.feature +41 -0
  73. package/tests/features/storage.feature +98 -0
  74. package/tests/features/test--then--i-see-locator.feature +13 -0
  75. package/tests/features/test--then--i-should--see-text-in-element.feature +9 -1
  76. package/tests/features/test--then--the-field-should-contain-value.feature +8 -0
  77. package/tests/features/video.feature +1 -0
  78. package/tests/features/wait.feature +89 -0
  79. package/tests/features/web-first.feature +100 -0
  80. package/tests/features/xml.feature +96 -0
  81. package/tests/features/yaml.feature +75 -0
  82. package/tests/must-fail/assertions.feature +96 -0
  83. package/tests/must-fail/waits.feature +51 -0
  84. package/tests/reports/README.md +2 -2
  85. package/tests/step-definitions/a11y.steps.js +12 -8
  86. package/tests/step-definitions/assertion.steps.js +235 -61
  87. package/tests/step-definitions/dialog.steps.js +2 -2
  88. package/tests/step-definitions/element.steps.js +3 -1
  89. package/tests/step-definitions/field.steps.js +152 -22
  90. package/tests/step-definitions/file-download.steps.js +74 -10
  91. package/tests/step-definitions/screenshot.steps.js +1 -1
  92. package/tests/step-definitions/selectors.steps.js +9 -3
  93. package/tests/step-definitions/storage.steps.js +3 -3
  94. package/tests/step-definitions/wait.steps.js +129 -39
  95. package/tests/step-definitions/webship.js +144 -3
  96. package/tests/step-definitions/xml.steps.js +76 -14
  97. package/tests/step-definitions/yaml.steps.js +46 -27
  98. package/.scratch/commit.txt +0 -14
  99. package/.scratch/docs.py +0 -42
  100. package/.scratch/echo-server.js +0 -8
  101. package/.scratch/echo.js +0 -35
  102. package/.scratch/echo.pid +0 -1
  103. package/.scratch/features/cookies.feature +0 -22
  104. package/.scratch/http.pid +0 -1
  105. package/.scratch/https.pid +0 -1
  106. package/.scratch/issue.md +0 -49
  107. package/.scratch/one.js +0 -2
  108. package/.scratch/one.json +0 -280
  109. package/.scratch/patch.py +0 -163
  110. package/.scratch/pr.md +0 -30
@@ -9,8 +9,7 @@
9
9
  // Modal assertions live in modal.steps.js.
10
10
 
11
11
  const { Then } = require('@cucumber/cucumber');
12
- const assert = require('assert');
13
- const { buildSelector, getLocatorText, friendly } = require('./webship');
12
+ const { buildSelector, getLocatorText, locateByLabelOrSelector, failure, excerpt, isTimeout } = require('./webship');
14
13
  const { getLastResponse } = require('./response.steps');
15
14
 
16
15
  // ---------------------------------------------------------------------------
@@ -29,9 +28,20 @@ const { getLastResponse } = require('./response.steps');
29
28
  Then(/^(I |we )*should( not)* see "([^"]*)?"$/, async function (pronounCase, notCase, expectedText) {
30
29
  if (notCase) {
31
30
  const text = await this.page.locator('body').textContent() || '';
32
- assert.ok(!text.includes(expectedText), `Page should NOT contain "${expectedText}" but it does.`);
31
+ if (text.includes(expectedText)) {
32
+ throw failure(this.page, `The text "${expectedText}" is on the page, but it should not be.`, {
33
+ hint: 'this step reads all the text of the page, the text that is hidden included.',
34
+ });
35
+ }
33
36
  } else {
34
- await this.page.locator('body').filter({ hasText: expectedText }).waitFor({ timeout: 5000 });
37
+ try {
38
+ await this.page.locator('body').filter({ hasText: expectedText }).waitFor({ timeout: 5000 });
39
+ } catch (e) {
40
+ if (!isTimeout(e)) throw e;
41
+ throw failure(this.page, `The text "${expectedText}" was not found on the page after 5 seconds.`, {
42
+ hint: `check the spelling and the letter case. The value of a field, an image and the content of an iframe are not page text. For text that arrives late, use: I wait for the text "${expectedText}" to appear`,
43
+ });
44
+ }
35
45
  }
36
46
  });
37
47
 
@@ -45,11 +55,25 @@ Then(/^(I |we )*should( not)* see "([^"]*)?"$/, async function (pronounCase, not
45
55
  */
46
56
  Then(/^(I |we )*should( not)* see text matching "([^"]*)?"$/, async function (pronounCase, notCase, textPattern) {
47
57
  const bodyText = await this.page.evaluate(() => document.body.innerText || '');
48
- const regex = new RegExp(textPattern);
49
- if (notCase) {
50
- assert.ok(!regex.test(bodyText), `Page text should NOT match "${textPattern}" but it does.`);
51
- } else {
52
- assert.ok(regex.test(bodyText), `Page text should match "${textPattern}" but it does not.`);
58
+ let regex;
59
+ try {
60
+ regex = new RegExp(textPattern);
61
+ } catch (e) {
62
+ throw failure(this.page, `"${textPattern}" is not a valid regular expression: ${e.message}`, {
63
+ hint: 'escape the characters that have a meaning in a regular expression, such as ( ) [ ] ? + * and .',
64
+ });
65
+ }
66
+ const match = regex.exec(bodyText);
67
+ if (notCase && match) {
68
+ throw failure(this.page, `The text of the page matches "${textPattern}", but it should not.`, {
69
+ found: `"${excerpt(match[0])}"`,
70
+ hint: 'the pattern is a regular expression tried against the visible text of the whole page.',
71
+ });
72
+ }
73
+ if (!notCase && !match) {
74
+ throw failure(this.page, `No text of the page matches "${textPattern}".`, {
75
+ hint: 'the pattern is a regular expression tried against the visible text of the whole page; ^ and $ stand for the start and the end of that whole text.',
76
+ });
53
77
  }
54
78
  });
55
79
 
@@ -74,10 +98,19 @@ Then(/^(I |we )*should( not)* see "([^"]*)?" in( the)* "([^"]*)?" row$/, async f
74
98
  const rows = Array.from(document.querySelectorAll('tr'));
75
99
  return rows.filter(r => r.textContent.includes(id)).some(r => r.textContent.includes(text));
76
100
  }, { id: rowIdentifier, text: expectedText });
77
- if (notCase) {
78
- assert.ok(!found, `Found "${expectedText}" in the "${rowIdentifier}" row, but it should not be there.`);
79
- } else {
80
- assert.ok(found, `Could not find "${expectedText}" in the "${rowIdentifier}" row.`);
101
+ if (notCase && found) {
102
+ throw failure(this.page, `The "${rowIdentifier}" row contains "${expectedText}", but it should not.`, {
103
+ hint: `the row is every table row whose text contains "${rowIdentifier}".`,
104
+ });
105
+ }
106
+ if (!notCase && !found) {
107
+ const rows = await this.page.locator('tr').filter({ hasText: rowIdentifier }).count();
108
+ throw failure(this.page, rows
109
+ ? `The "${rowIdentifier}" row does not contain "${expectedText}".`
110
+ : `No table row contains "${rowIdentifier}", so "${expectedText}" could not be looked for in it.`, {
111
+ found: rows ? `"${excerpt(await this.page.locator('tr').filter({ hasText: rowIdentifier }).first().textContent())}"` : undefined,
112
+ hint: 'check the spelling and the letter case of both texts; the step reads the table rows that are on the page now.',
113
+ });
81
114
  }
82
115
  });
83
116
 
@@ -110,15 +143,33 @@ Then(/^(I |we )*should( not)* see (a|an) "([^"]*)?" element$/, async function (p
110
143
  const target = forIds[i]
111
144
  ? this.page.locator(`[id="${forIds[i].replace(/["\\]/g, '\\$&')}"]`).first()
112
145
  : named.nth(i);
113
- assert.ok(!(await target.isVisible()), `Element "${element}" should NOT be visible but it is.`);
146
+ if (await target.isVisible()) {
147
+ throw failure(this.page, `The element "${element}" is visible, but it should not be.`, {
148
+ hint: 'this step finds an element by its exact visible text or by its label.',
149
+ });
150
+ }
114
151
  }
115
152
  } else {
153
+ const hint = `this step finds an element by its exact visible text or by its label. To find it by its id, class, name or another attribute, use: I should see a "${element}" element by attr`;
116
154
  const loc = this.page.getByText(element, { exact: true }).first();
155
+ try {
156
+ await loc.waitFor({ state: 'attached', timeout: 3000 });
157
+ } catch (e) {
158
+ if (!isTimeout(e)) throw e;
159
+ throw failure(this.page, `No element with the text or the label "${element}" was found after 3 seconds.`, { hint });
160
+ }
117
161
  const forAttr = await loc.getAttribute('for').catch(() => null);
118
- if (forAttr) {
119
- await this.page.locator('#' + forAttr).waitFor({ state: 'visible', timeout: 3000 });
120
- } else {
121
- await loc.waitFor({ state: 'visible', timeout: 3000 });
162
+ try {
163
+ if (forAttr) {
164
+ await this.page.locator('#' + forAttr).waitFor({ state: 'visible', timeout: 3000 });
165
+ } else {
166
+ await loc.waitFor({ state: 'visible', timeout: 3000 });
167
+ }
168
+ } catch (e) {
169
+ if (!isTimeout(e)) throw e;
170
+ throw failure(this.page, forAttr
171
+ ? `The field of the label "${element}" (#${forAttr}) is not visible after 3 seconds.`
172
+ : `The element "${element}" is on the page but not visible after 3 seconds.`, { hint });
122
173
  }
123
174
  }
124
175
  });
@@ -133,31 +184,64 @@ Then(/^(I |we )*should( not)* see (a|an) "([^"]*)?" element$/, async function (p
133
184
  *
134
185
  */
135
186
  Then(/^(I |we )*should( not)* see (a|an) "([^"]*)?" element by( its)*(?: "([^"]*)?")* (attribute|attr)$/, async function (pronounCase, notCase, aAnCase, attrValue, itsCase, attr, attrWord) {
136
- const loc = this.page.locator(buildSelector(attrValue, attr));
187
+ const selector = buildSelector(attrValue, attr);
188
+ const loc = this.page.locator(selector);
137
189
  if (notCase) {
138
- assert.strictEqual(await loc.count(), 0, `Element should NOT be present but it is.`);
190
+ const count = await loc.count();
191
+ if (count > 0) {
192
+ throw failure(this.page, `An element with "${attrValue}" is on the page, but it should not be.`, {
193
+ found: `${count} element(s)`,
194
+ hint: attr
195
+ ? `the step looked for an element whose "${attr}" attribute is "${attrValue}"; a hidden element counts too.`
196
+ : `without a named attribute the step tries "${attrValue}" as an id, a class, a name, a test id, an aria-label, a value, a placeholder and a title; a hidden element counts too.`,
197
+ });
198
+ }
139
199
  } else {
140
- await loc.first().waitFor({ state: 'visible', timeout: 3000 });
200
+ try {
201
+ await loc.first().waitFor({ state: 'visible', timeout: 3000 });
202
+ } catch (e) {
203
+ if (!isTimeout(e)) throw e;
204
+ const count = await loc.count().catch(() => 0);
205
+ throw failure(this.page, count
206
+ ? `The element with "${attrValue}" is on the page but not visible after 3 seconds.`
207
+ : `No element with "${attrValue}" was found after 3 seconds.`, {
208
+ hint: attr
209
+ ? `the step looked for an element whose "${attr}" attribute is "${attrValue}".`
210
+ : `without a named attribute the step tries "${attrValue}" as an id, a class, a name, a test id, an aria-label, a value, a placeholder and a title.`,
211
+ });
212
+ }
141
213
  }
142
214
  });
143
215
 
144
216
  /**
145
- * Assert that an element (found by its label) contains or does not contain text.
217
+ * Assert that an element contains or does not contain text. The element is
218
+ * named by the exact text of its label, or by a CSS selector.
146
219
  *
147
220
  * Example #1: Then I should see "John Smith" in the "Username" element
148
221
  * Example #2: Then I should not see "Joe Smith" in the "Username" element
149
222
  * Example #3: And we should see "1234" in the "Password" element
223
+ * Example #4: Then I should see "About Us" in the "h1" element
224
+ * Example #5: Then we should not see "Error" in the "#status" element
150
225
  *
151
226
  */
152
227
  Then(/^(I |we )*should( not)* see "([^"]*)?" in( the)* "([^"]*)?" element$/, async function (pronounCase, notCase, expectedText, theCase, element) {
153
- const forAttr = await this.page.getByText(element, { exact: true }).getAttribute('for').catch(() => null);
154
- const loc = this.page.locator(forAttr ? '#' + forAttr : element).first();
155
- await loc.waitFor({ timeout: 5000 });
228
+ const loc = await locateByLabelOrSelector(this.page, element, 5000);
229
+ if (!loc) {
230
+ throw failure(this.page, `The element "${element}" was not found on the page after 5 seconds.`, {
231
+ hint: `"${element}" is read as the exact text of a label, else as a CSS selector. To find an element by its id, class, name or another attribute, add "by attr" to the step.`,
232
+ });
233
+ }
156
234
  const content = await getLocatorText(loc);
157
- if (notCase) {
158
- assert.ok(!content.includes(expectedText), `Element should NOT contain "${expectedText}" but it does.`);
159
- } else {
160
- assert.ok(content.includes(expectedText), `Element should contain "${expectedText}" but it does not.`);
235
+ if (notCase && content.includes(expectedText)) {
236
+ throw failure(this.page, `The element "${element}" contains "${expectedText}", but it should not.`, {
237
+ found: `"${excerpt(content)}"`,
238
+ });
239
+ }
240
+ if (!notCase && !content.includes(expectedText)) {
241
+ throw failure(this.page, `The element "${element}" does not contain "${expectedText}".`, {
242
+ found: `"${excerpt(content)}"`,
243
+ hint: 'check the spelling and the letter case; for a field the step reads its value.',
244
+ });
161
245
  }
162
246
  });
163
247
 
@@ -172,12 +256,27 @@ Then(/^(I |we )*should( not)* see "([^"]*)?" in( the)* "([^"]*)?" element$/, asy
172
256
  */
173
257
  Then(/^(I |we )*should( not)* see "([^"]*)?" in( the)* "([^"]*)?" element by( its)*(?: "([^"]*)?")* (attribute|attr)$/, async function (pronounCase, notCase, expectedText, theCase, attrValue, itsCase, attr, attrWord) {
174
258
  const loc = this.page.locator(buildSelector(attrValue, attr)).first();
175
- await loc.waitFor({ timeout: 10000 });
259
+ try {
260
+ await loc.waitFor({ timeout: 10000 });
261
+ } catch (e) {
262
+ if (!isTimeout(e)) throw e;
263
+ throw failure(this.page, `No visible element with "${attrValue}" was found after 10 seconds, so "${expectedText}" could not be looked for in it.`, {
264
+ hint: attr
265
+ ? `the step looked for an element whose "${attr}" attribute is "${attrValue}".`
266
+ : `without a named attribute the step tries "${attrValue}" as an id, a class, a name, a test id, an aria-label, a value, a placeholder and a title.`,
267
+ });
268
+ }
176
269
  const content = await getLocatorText(loc);
177
- if (notCase) {
178
- assert.ok(!content.includes(expectedText), `Element should NOT contain "${expectedText}" but it does.`);
179
- } else {
180
- assert.ok(content.includes(expectedText), `Element should contain "${expectedText}" but it does not.`);
270
+ if (notCase && content.includes(expectedText)) {
271
+ throw failure(this.page, `The element with "${attrValue}" contains "${expectedText}", but it should not.`, {
272
+ found: `"${excerpt(content)}"`,
273
+ });
274
+ }
275
+ if (!notCase && !content.includes(expectedText)) {
276
+ throw failure(this.page, `The element with "${attrValue}" does not contain "${expectedText}".`, {
277
+ found: `"${excerpt(content)}"`,
278
+ hint: 'check the spelling and the letter case; for a field the step reads its value.',
279
+ });
181
280
  }
182
281
  });
183
282
 
@@ -192,14 +291,34 @@ Then(/^(I |we )*should( not)* see "([^"]*)?" in( the)* "([^"]*)?" element by( it
192
291
  *
193
292
  */
194
293
  Then(/^(I |we )*should( not)* see text matching "([^"]*)?" in( the)* "([^"]*)?" element$/, async function (pronounCase, notCase, textPattern, theCase, element) {
294
+ let regex;
295
+ try {
296
+ regex = new RegExp(textPattern);
297
+ } catch (e) {
298
+ throw failure(this.page, `"${textPattern}" is not a valid regular expression: ${e.message}`, {
299
+ hint: 'escape the characters that have a meaning in a regular expression, such as ( ) [ ] ? + * and .',
300
+ });
301
+ }
195
302
  const loc = this.page.locator(element).first();
196
- await loc.waitFor({ timeout: 5000 });
303
+ try {
304
+ await loc.waitFor({ timeout: 5000 });
305
+ } catch (e) {
306
+ if (!isTimeout(e)) throw e;
307
+ throw failure(this.page, `No visible element matches "${element}" after 5 seconds, so its text could not be read.`, {
308
+ hint: `"${element}" is a CSS selector here.`,
309
+ });
310
+ }
197
311
  const text = await getLocatorText(loc);
198
- const regex = new RegExp(textPattern);
199
- if (notCase) {
200
- assert.ok(!regex.test(text), `Element "${element}" text should NOT match "${textPattern}" but it does.`);
201
- } else {
202
- assert.ok(regex.test(text), `Element "${element}" text should match "${textPattern}" but it does not.`);
312
+ if (notCase && regex.test(text)) {
313
+ throw failure(this.page, `The text of the element "${element}" matches "${textPattern}", but it should not.`, {
314
+ found: `"${excerpt(text)}"`,
315
+ });
316
+ }
317
+ if (!notCase && !regex.test(text)) {
318
+ throw failure(this.page, `The text of the element "${element}" does not match "${textPattern}".`, {
319
+ found: `"${excerpt(text)}"`,
320
+ hint: 'the pattern is a regular expression; for a field the step reads its value.',
321
+ });
203
322
  }
204
323
  });
205
324
 
@@ -219,8 +338,15 @@ Then(/^(the )*"([^"]*)?" element should( not)* contain "([^"]*)?"$/, async funct
219
338
  const expectedValue = cssClean.substring(colonIdx + 1).trim();
220
339
 
221
340
  const loc = this.page.locator(buildSelector(selectorRaw)).first();
222
- await loc.waitFor({ timeout: 10000 });
223
- const matches = await loc.evaluate((el, { prop, expectedVal }) => {
341
+ try {
342
+ await loc.waitFor({ timeout: 10000 });
343
+ } catch (e) {
344
+ if (!isTimeout(e)) throw e;
345
+ throw failure(this.page, `No visible element with "${selectorRaw}" was found after 10 seconds, so its CSS could not be read.`, {
346
+ hint: `the step tries "${selectorRaw}" as an id, a class, a name, a test id, an aria-label, a value, a placeholder and a title.`,
347
+ });
348
+ }
349
+ const { matches, computed } = await loc.evaluate((el, { prop, expectedVal }) => {
224
350
  function colorToRgb(color) {
225
351
  const canvas = document.createElement('canvas');
226
352
  canvas.width = canvas.height = 1;
@@ -243,14 +369,23 @@ Then(/^(the )*"([^"]*)?" element should( not)* contain "([^"]*)?"$/, async funct
243
369
  return tokens;
244
370
  }
245
371
  const computed = window.getComputedStyle(el).getPropertyValue(prop).trim();
246
- return tokenize(normalizeColorTokens(expectedVal.toLowerCase()))
247
- .every(token => normalizeColorTokens(computed.toLowerCase()).includes(token));
372
+ return {
373
+ computed,
374
+ matches: tokenize(normalizeColorTokens(expectedVal.toLowerCase()))
375
+ .every(token => normalizeColorTokens(computed.toLowerCase()).includes(token)),
376
+ };
248
377
  }, { prop: cssProperty, expectedVal: expectedValue });
249
378
 
250
- if (notCase) {
251
- assert.ok(!matches, `Element should NOT have CSS "${cssProperty}: ${expectedValue}" but it does.`);
252
- } else {
253
- assert.ok(matches, `Element should have CSS "${cssProperty}: ${expectedValue}".`);
379
+ if (notCase && matches) {
380
+ throw failure(this.page, `The element "${selectorRaw}" has the CSS "${cssProperty}: ${expectedValue}", but it should not.`, {
381
+ found: `${cssProperty}: ${computed}`,
382
+ });
383
+ }
384
+ if (!notCase && !matches) {
385
+ throw failure(this.page, `The element "${selectorRaw}" does not have the CSS "${cssProperty}: ${expectedValue}".`, {
386
+ found: `${cssProperty}: ${computed || '(no value)'}`,
387
+ hint: 'the step compares with the computed style, where a colour is written as rgb(…) and a length in pixels.',
388
+ });
254
389
  }
255
390
  });
256
391
 
@@ -272,7 +407,9 @@ Then(/^(I |we )*should see (\d+) "([^"]*)" elements?$/, async function (pronounC
272
407
  const expected = parseInt(num, 10);
273
408
  const actual = await this.page.locator(selector).count();
274
409
  if (actual !== expected) {
275
- throw friendly(`Expected ${expected} "${selector}" element(s), got ${actual}.`);
410
+ throw failure(this.page, `Expected ${expected} "${selector}" element(s), got ${actual}.`, {
411
+ hint: `"${selector}" is a CSS selector; hidden elements count too.`,
412
+ });
276
413
  }
277
414
  });
278
415
 
@@ -290,9 +427,21 @@ Then(/^(I |we )*should see (\d+) "([^"]*)" elements?$/, async function (pronounC
290
427
  */
291
428
  Then(/^(the )*"([^"]*)?" link should contain "([^"]*)?"$/, async function (theCase, element, url) {
292
429
  const loc = this.page.getByText(element, { exact: true }).first();
293
- await loc.waitFor({ timeout: 5000 });
430
+ try {
431
+ await loc.waitFor({ timeout: 5000 });
432
+ } catch (e) {
433
+ if (!isTimeout(e)) throw e;
434
+ throw failure(this.page, `No visible link with the text "${element}" was found after 5 seconds.`, {
435
+ hint: `the step finds the link by its exact text. To find it by its id, class, title or another attribute, add "by attr" to the step.`,
436
+ });
437
+ }
294
438
  const href = await loc.evaluate(el => el.href || el.getAttribute('href') || '');
295
- assert.ok(href.includes(url), `Expected link "${element}" href to contain "${url}" but got "${href}"`);
439
+ if (!href.includes(url)) {
440
+ throw failure(this.page, `The address of the link "${element}" does not contain "${url}".`, {
441
+ found: href ? `"${href}"` : 'the element has no address (no href)',
442
+ hint: 'the step reads the full address the link leads to, with the domain.',
443
+ });
444
+ }
296
445
  });
297
446
 
298
447
  /**
@@ -305,9 +454,23 @@ Then(/^(the )*"([^"]*)?" link should contain "([^"]*)?"$/, async function (theCa
305
454
  */
306
455
  Then(/^(the )*"([^"]*)?" link should contain "([^"]*)?" by( its)*(?: "([^"]*)?")* (attribute|attr)$/, async function (theCase, attrValue, url, itsCase, attr, attrWord) {
307
456
  const loc = this.page.locator(buildSelector(attrValue, attr)).first();
308
- await loc.waitFor({ timeout: 5000 });
457
+ try {
458
+ await loc.waitFor({ timeout: 5000 });
459
+ } catch (e) {
460
+ if (!isTimeout(e)) throw e;
461
+ throw failure(this.page, `No visible link with "${attrValue}" was found after 5 seconds.`, {
462
+ hint: attr
463
+ ? `the step looked for an element whose "${attr}" attribute is "${attrValue}".`
464
+ : `without a named attribute the step tries "${attrValue}" as an id, a class, a name, a test id, an aria-label, a value, a placeholder and a title.`,
465
+ });
466
+ }
309
467
  const href = await loc.evaluate(el => el.href || el.getAttribute('href') || '');
310
- assert.ok(href.includes(url), `Expected element href to contain "${url}" but got "${href}"`);
468
+ if (!href.includes(url)) {
469
+ throw failure(this.page, `The address of the link with "${attrValue}" does not contain "${url}".`, {
470
+ found: href ? `"${href}"` : 'the element has no address (no href)',
471
+ hint: 'the step reads the full address the link leads to, with the domain.',
472
+ });
473
+ }
311
474
  });
312
475
 
313
476
  // ---------------------------------------------------------------------------
@@ -331,10 +494,16 @@ Then(/^(the )*"([^"]*)?" link should contain "([^"]*)?" by( its)*(?: "([^"]*)?")
331
494
  */
332
495
  Then(/^(the )*response should( not)* contain "([^"]*)?"$/, async function (theCase, notCase, expectedText) {
333
496
  const text = await this.page.locator('html').textContent() || '';
334
- if (notCase) {
335
- assert.ok(!text.includes(expectedText), `Response should NOT contain "${expectedText}" but it does.`);
336
- } else {
337
- assert.ok(text.includes(expectedText), `Response should contain "${expectedText}" but it does not.`);
497
+ if (notCase && text.includes(expectedText)) {
498
+ throw failure(this.page, `The response contains "${expectedText}", but it should not.`, {
499
+ hint: 'this step reads all the text of the document, the text that is hidden included.',
500
+ });
501
+ }
502
+ if (!notCase && !text.includes(expectedText)) {
503
+ throw failure(this.page, `The response does not contain "${expectedText}".`, {
504
+ found: `"${excerpt(text)}"`,
505
+ hint: 'this step reads the text of the document the browser shows, not its HTML source.',
506
+ });
338
507
  }
339
508
  });
340
509
 
@@ -355,9 +524,14 @@ Then(/^(the )*response should( not)* contain "([^"]*)?"$/, async function (theCa
355
524
  Then(/^(the )*response status code should( not)* be (\d+)$/, async function (theCase, notCase, expectedStatusCode) {
356
525
  const expected = parseInt(expectedStatusCode, 10);
357
526
  const { status } = await getLastResponse(this);
358
- if (notCase) {
359
- assert.notStrictEqual(status, expected, `Status code should NOT be ${expected}`);
360
- } else {
361
- assert.strictEqual(status, expected, `Expected status ${expected} but got ${status}`);
527
+ if (notCase && status === expected) {
528
+ throw failure(this.page, `The response status code is ${expected}, but it should not be.`, {
529
+ hint: 'the step reads the status of the document the browser shows now.',
530
+ });
531
+ }
532
+ if (!notCase && status !== expected) {
533
+ throw failure(this.page, `Expected the response status code ${expected}, got ${status}.`, {
534
+ hint: 'the step reads the status of the document the browser shows now.',
535
+ });
362
536
  }
363
537
  });
@@ -75,9 +75,9 @@ Given(/^(I |we )*will accept the next dialog$/, function (pronoun) {
75
75
  * Then I should be on the homepage
76
76
  * Example #4: Given I will dismiss the next dialog
77
77
  * When I press "Delete"
78
- * Then "<.row>" should still be visible
78
+ * Then ".row" should be visible
79
79
  * Example #5: Given I will dismiss the next dialog
80
- * When I close the tab
80
+ * When I reload the page
81
81
  *
82
82
  */
83
83
  Given(/^(I |we )*will dismiss the next dialog$/, function (pronoun) {
@@ -135,7 +135,9 @@ Then('the element {string} should be at the top of the viewport', async function
135
135
  Then('the element {string} should be centered in the viewport', async function (sel) {
136
136
  const box = await this.page.locator(sel).first().boundingBox();
137
137
  assert.ok(box, `Element "${sel}" not found.`);
138
- const vw = this.page.viewportSize().width;
138
+ // Read the width from the page: page.viewportSize() is null when the
139
+ // browser context is opened with a fluid viewport (`viewport: null`).
140
+ const vw = await this.page.evaluate(() => document.documentElement.clientWidth);
139
141
  const center = box.x + box.width / 2;
140
142
  const tolerance = vw * 0.1;
141
143
  assert.ok(Math.abs(center - vw / 2) <= tolerance, `Element "${sel}" not centered (center=${center}, vw=${vw}).`);