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
@@ -4,6 +4,7 @@
4
4
 
5
5
  const { Given, When, Then } = require('@cucumber/cucumber');
6
6
  const assert = require('assert');
7
+ const { friendly } = require('./webship');
7
8
 
8
9
  // Resolve a field by label, name, id, or selector.
9
10
  function fieldLocator(page, field) {
@@ -27,6 +28,44 @@ async function getField(page, field) {
27
28
  return loc;
28
29
  }
29
30
 
31
+ // Escape a label for use inside a quoted CSS / Playwright selector string.
32
+ function quoted(text) {
33
+ return String(text).replace(/\\/g, '\\\\').replace(/"/g, '\\"');
34
+ }
35
+
36
+ // Resolve the date or the time input of a datetime field named by its label.
37
+ // The pair is written in many ways, so every usual one is looked at, and the
38
+ // first input in the page that fits is taken:
39
+ // - inputs in an element that follows the label, or right after the label;
40
+ // - inputs inside the label;
41
+ // - inputs of a fieldset whose legend carries the label;
42
+ // - inputs whose name or accessible name contains the label, whatever the case.
43
+ // `half` narrows a date range to its "start" or its "end" input.
44
+ async function datetimePart(page, label, type, half) {
45
+ const l = quoted(label);
46
+ const input = `input[type="${type}"]${half ? `[name*="${half}" i]` : ''}`;
47
+ const named = `input[type="${type}"][name*="${l}" i]${half ? `[name*="${half}" i]` : ''}`;
48
+ const loc = page.locator([
49
+ `label:has-text("${l}") ~ * ${input}`,
50
+ `label:has-text("${l}") ~ ${input}`,
51
+ `label:has-text("${l}") ${input}`,
52
+ `fieldset:has(legend:has-text("${l}")) ${input}`,
53
+ named,
54
+ `${input}[aria-label*="${l}" i]`,
55
+ ].join(', ')).first();
56
+ try {
57
+ await loc.waitFor({ state: 'attached', timeout: 5000 });
58
+ } catch (e) {
59
+ throw friendly({
60
+ action: `find the ${half ? half + ' ' : ''}${type} input of the datetime field`,
61
+ target: label,
62
+ cause: `no <input type="${type}"> was found after a label, inside a label or a fieldset, or by a name that contains "${label}"`,
63
+ hint: 'use the visible label of the field, the legend of its fieldset, or a part of the name of its inputs.',
64
+ });
65
+ }
66
+ return loc;
67
+ }
68
+
30
69
  /**
31
70
  * Assert a field's current value is the empty string.
32
71
  *
@@ -207,6 +246,12 @@ Then('the color field {string} should have the value {string}', async function (
207
246
  /**
208
247
  * Fill a CKEditor / contenteditable rich-text field with HTML.
209
248
  *
249
+ * The field is found by the name or the id of its form control, by the text
250
+ * of its label, or by the accessible name of its editable area
251
+ * (`aria-label` / `aria-labelledby`). The editable area that is filled is the
252
+ * one that belongs to that field, so a page with several editors is filled in
253
+ * the right place. A page with a single editor is filled whatever the name.
254
+ *
210
255
  * Example #1: When I fill in the WYSIWYG field "body" with the "Hello world"
211
256
  * Example #2: When I fill in the WYSIWYG field "Description" with the "<strong>Bold</strong>"
212
257
  * Example #3: And we fill in the WYSIWYG field "content" with the "Plain paragraph"
@@ -215,13 +260,77 @@ Then('the color field {string} should have the value {string}', async function (
215
260
  *
216
261
  */
217
262
  When(/^(I |we )*fill in the WYSIWYG field "([^"]*)" with the "([^"]*)"$/, async function (pronoun, field, value) {
218
- // CKEditor5/4 fallback: try contenteditable.
219
- await this.page.evaluate(({ field, value }) => {
220
- const editor = document.querySelector(`[name="${field}"], #${field}`);
221
- if (editor && 'value' in editor) editor.value = value;
222
- const ce = document.querySelector('.ck-editor__editable, [contenteditable="true"]');
223
- if (ce) ce.innerHTML = `<p>${value}</p>`;
263
+ const filled = await this.page.evaluate(({ field, value }) => {
264
+ const EDITABLE = '.ck-editor__editable, [contenteditable="true"], [contenteditable=""]';
265
+ const html = `<p>${value}</p>`;
266
+ const byId = (id) => (id ? document.getElementById(id) : null);
267
+ const sameText = (el) => (el.textContent || '').replace(/\s+/g, ' ').trim() === field;
268
+
269
+ // 1. What the name points at: a form control by its name or id, a label
270
+ // by its text, or an editable area by its accessible name.
271
+ let source = Array.from(document.getElementsByName(field))[0] || byId(field);
272
+ if (!source) {
273
+ const label = Array.from(document.querySelectorAll('label')).find(sameText);
274
+ if (label) source = label.control || byId(label.getAttribute('for'));
275
+ }
276
+ if (!source) {
277
+ source = Array.from(document.querySelectorAll(EDITABLE)).find((el) => {
278
+ if (el.getAttribute('aria-label') === field) return true;
279
+ const ids = (el.getAttribute('aria-labelledby') || '').split(/\s+/).filter(Boolean);
280
+ return ids.some((id) => { const named = byId(id); return named && sameText(named); });
281
+ }) || null;
282
+ }
283
+
284
+ // 2. The editable area that belongs to it. An editor renders right after
285
+ // the form control it replaces; failing that, it is the only editable
286
+ // area of the closest wrapper around the control.
287
+ let editable = null;
288
+ if (source && source.matches(EDITABLE)) {
289
+ editable = source;
290
+ } else if (source) {
291
+ for (let el = source.nextElementSibling; el && !editable; el = el.nextElementSibling) {
292
+ if (el.matches('label, input, textarea, select')) break;
293
+ editable = el.matches(EDITABLE) ? el : el.querySelector(EDITABLE);
294
+ }
295
+ for (let box = source.parentElement; box && box !== document.body && !editable; box = box.parentElement) {
296
+ const inside = box.querySelectorAll(EDITABLE);
297
+ if (inside.length === 1) editable = inside[0];
298
+ if (inside.length > 1) break;
299
+ }
300
+ } else {
301
+ const all = document.querySelectorAll(EDITABLE);
302
+ if (all.length === 1) editable = all[0];
303
+ }
304
+
305
+ const control = source && source !== editable && 'value' in source ? source : null;
306
+ if (control) {
307
+ control.value = value;
308
+ control.dispatchEvent(new Event('input', { bubbles: true }));
309
+ control.dispatchEvent(new Event('change', { bubbles: true }));
310
+ }
311
+ if (editable) {
312
+ const ck5 = editable.ckeditorInstance;
313
+ if (ck5 && typeof ck5.setData === 'function') ck5.setData(html);
314
+ else {
315
+ editable.innerHTML = html;
316
+ editable.dispatchEvent(new Event('input', { bubbles: true }));
317
+ }
318
+ }
319
+ // CKEditor 4 edits inside an iframe and keeps its instances by control id or name.
320
+ const registry = window.CKEDITOR && window.CKEDITOR.instances;
321
+ const ck4 = registry && control ? (registry[control.id] || registry[control.name]) : null;
322
+ if (ck4 && typeof ck4.setData === 'function') ck4.setData(html);
323
+
324
+ return Boolean(control || editable || ck4);
224
325
  }, { field, value });
326
+ if (!filled) {
327
+ throw friendly({
328
+ action: 'fill in the WYSIWYG field',
329
+ target: field,
330
+ cause: 'no form control with that name or id, no label with that text and no editable area with that accessible name was found',
331
+ hint: 'use the name or the id of the textarea behind the editor, the text of its label, or the aria-label of the editable area.',
332
+ });
333
+ }
225
334
  });
226
335
 
227
336
  /**
@@ -401,6 +510,11 @@ Given('browser validation for the form {string} is disabled', async function (se
401
510
  /**
402
511
  * Fill paired `<input type=date>` + `<input type=time>` controls for a label.
403
512
  *
513
+ * The field is named by its visible label or the legend of its fieldset; an
514
+ * input whose name or aria-label contains that text is found too, whatever
515
+ * the letter case. When an input is not found within 5 seconds the step
516
+ * fails and fills nothing.
517
+ *
404
518
  * Example #1: When I fill in the datetime field "Start" with date "2026-05-08" and time "10:00"
405
519
  * Example #2: When I fill in the datetime field "Departure" with date "2026-12-31" and time "23:59"
406
520
  * Example #3: And we fill in the datetime field "Pickup" with date "2026-07-04" and time "08:30"
@@ -409,9 +523,11 @@ Given('browser validation for the form {string} is disabled', async function (se
409
523
  *
410
524
  */
411
525
  When(/^(I |we )*fill in the datetime field "([^"]*)" with date "([^"]*)" and time "([^"]*)"$/, async function (pronoun, label, date, time) {
412
- const root = this.page.locator(`label:has-text("${label}")`).first();
413
- await this.page.locator(`input[type="date"][name*="${label}"], label:has-text("${label}") ~ * input[type="date"]`).first().fill(date).catch(() => {});
414
- await this.page.locator(`input[type="time"][name*="${label}"], label:has-text("${label}") ~ * input[type="time"]`).first().fill(time).catch(() => {});
526
+ // Both inputs are found before either is filled: a failure leaves the form as it was.
527
+ const dateInput = await datetimePart(this.page, label, 'date');
528
+ const timeInput = await datetimePart(this.page, label, 'time');
529
+ await dateInput.fill(date);
530
+ await timeInput.fill(time);
415
531
  });
416
532
 
417
533
  /**
@@ -425,7 +541,7 @@ When(/^(I |we )*fill in the datetime field "([^"]*)" with date "([^"]*)" and tim
425
541
  *
426
542
  */
427
543
  When(/^(I |we )*fill in the date part of the datetime field "([^"]*)" with "([^"]*)"$/, async function (pronoun, label, date) {
428
- await this.page.locator(`label:has-text("${label}") ~ * input[type="date"], input[type="date"][name*="${label}"]`).first().fill(date);
544
+ await (await datetimePart(this.page, label, 'date')).fill(date);
429
545
  });
430
546
 
431
547
  /**
@@ -439,12 +555,15 @@ When(/^(I |we )*fill in the date part of the datetime field "([^"]*)" with "([^"
439
555
  *
440
556
  */
441
557
  When(/^(I |we )*fill in the time part of the datetime field "([^"]*)" with "([^"]*)"$/, async function (pronoun, label, time) {
442
- await this.page.locator(`label:has-text("${label}") ~ * input[type="time"], input[type="time"][name*="${label}"]`).first().fill(time);
558
+ await (await datetimePart(this.page, label, 'time')).fill(time);
443
559
  });
444
560
 
445
561
  /**
446
562
  * Fill the `start` half of a date-range pair.
447
563
  *
564
+ * The range is named by its label or the legend of its fieldset; of its
565
+ * inputs, the ones whose name contains "start" are filled.
566
+ *
448
567
  * Example #1: When I fill in the start datetime field "Event" with date "2026-05-08" and time "10:00"
449
568
  * Example #2: When I fill in the start datetime field "Trip" with date "2026-12-31" and time "08:00"
450
569
  * Example #3: And we fill in the start datetime field "Window" with date "2026-07-04" and time "12:00"
@@ -453,13 +572,18 @@ When(/^(I |we )*fill in the time part of the datetime field "([^"]*)" with "([^"
453
572
  *
454
573
  */
455
574
  When(/^(I |we )*fill in the start datetime field "([^"]*)" with date "([^"]*)" and time "([^"]*)"$/, async function (pronoun, label, date, time) {
456
- await this.page.locator(`input[name*="${label}"][name*="start"][type="date"]`).first().fill(date).catch(() => {});
457
- await this.page.locator(`input[name*="${label}"][name*="start"][type="time"]`).first().fill(time).catch(() => {});
575
+ const dateInput = await datetimePart(this.page, label, 'date', 'start');
576
+ const timeInput = await datetimePart(this.page, label, 'time', 'start');
577
+ await dateInput.fill(date);
578
+ await timeInput.fill(time);
458
579
  });
459
580
 
460
581
  /**
461
582
  * Fill the `end` half of a date-range pair.
462
583
  *
584
+ * The range is named by its label or the legend of its fieldset; of its
585
+ * inputs, the ones whose name contains "end" are filled.
586
+ *
463
587
  * Example #1: When I fill in the end datetime field "Event" with date "2026-05-09" and time "18:00"
464
588
  * Example #2: When I fill in the end datetime field "Trip" with date "2027-01-07" and time "20:00"
465
589
  * Example #3: And we fill in the end datetime field "Window" with date "2026-07-04" and time "18:00"
@@ -468,8 +592,10 @@ When(/^(I |we )*fill in the start datetime field "([^"]*)" with date "([^"]*)" a
468
592
  *
469
593
  */
470
594
  When(/^(I |we )*fill in the end datetime field "([^"]*)" with date "([^"]*)" and time "([^"]*)"$/, async function (pronoun, label, date, time) {
471
- await this.page.locator(`input[name*="${label}"][name*="end"][type="date"]`).first().fill(date).catch(() => {});
472
- await this.page.locator(`input[name*="${label}"][name*="end"][type="time"]`).first().fill(time).catch(() => {});
595
+ const dateInput = await datetimePart(this.page, label, 'date', 'end');
596
+ const timeInput = await datetimePart(this.page, label, 'time', 'end');
597
+ await dateInput.fill(date);
598
+ await timeInput.fill(time);
473
599
  });
474
600
 
475
601
  // ---------------------------------------------------------------------------
@@ -479,24 +605,28 @@ When(/^(I |we )*fill in the end datetime field "([^"]*)" with date "([^"]*)" and
479
605
 
480
606
  const { Then: ThenF } = require('@cucumber/cucumber');
481
607
  const assertF = require('assert');
482
- const { getLocatorText: getLocatorTextF } = require('./webship');
608
+ const { getLocatorText: getLocatorTextF, locateByLabelOrSelector: locateByLabelOrSelectorF, friendly: friendlyF } = require('./webship');
483
609
 
484
610
  /**
485
611
  * Assert that a form field contains or does not contain specific text.
486
612
  *
613
+ * The field is named by the exact text of its label, or by a CSS selector.
614
+ *
487
615
  * Example #1: Then the "Username" field should contain "John Smith"
488
616
  * Example #2: Then the "#username" field should not contain "John Smith"
489
617
  * Example #3: And the "Email" field should contain "jon@example.com"
618
+ * Example #4: Then the "[name=username]" field should contain "John Smith"
619
+ * Example #5: And the "input.email" field should not contain "example.org"
490
620
  *
491
621
  */
492
622
  ThenF(/^(the )*"([^"]*)?" field should( not)* contain "([^"]*)?"$/, async function (theCase, field, notCase, expectedText) {
493
- let selector = field;
494
- if (!field.startsWith('#') && !field.startsWith('.')) {
495
- const forAttr = await this.page.getByText(field, { exact: true }).getAttribute('for').catch(() => null);
496
- if (forAttr) selector = '#' + forAttr;
623
+ const loc = await locateByLabelOrSelectorF(this.page, field, 5000);
624
+ if (!loc) {
625
+ throw friendlyF({
626
+ message: `The field "${field}" was not found on the page after 5 seconds.`,
627
+ hint: `"${field}" is read as the exact text of a label, else as a CSS selector such as "#username" or "[name=username]".`,
628
+ });
497
629
  }
498
- const loc = this.page.locator(selector).first();
499
- await loc.waitFor({ timeout: 5000 });
500
630
  const content = await getLocatorTextF(loc);
501
631
  if (notCase) {
502
632
  assertF.ok(!content.includes(expectedText), `Field should NOT contain "${expectedText}" but it does.`);
@@ -148,10 +148,63 @@ Then('the downloaded file name should contain {string}', async function (part) {
148
148
  assert.ok(this._lastDownload.filename.indexOf(part) !== -1, `Filename "${this._lastDownload.filename}" does not contain "${part}".`);
149
149
  });
150
150
 
151
- // ZIP archive assertions: pending. Install `yauzl` or `adm-zip` to enable.
151
+ // ---------------------------------------------------------------------------
152
+ // ZIP archive assertions
153
+ // ---------------------------------------------------------------------------
154
+ //
155
+ // The names are read from the central directory of the archive, with no
156
+ // dependency: nothing is unpacked. Folder entries are left out, and a file in
157
+ // a folder is known by its path in the archive ("reports/summary.csv").
158
+
159
+ const ZIP_END_OF_CENTRAL_DIRECTORY = 0x06054b50;
160
+ const ZIP_CENTRAL_DIRECTORY_ENTRY = 0x02014b50;
161
+
162
+ function zipFileNames(buffer) {
163
+ const notZip = () => friendly('The downloaded file is not a zip archive.');
164
+ if (!buffer || buffer.length < 22) throw notZip();
165
+ // The end record sits at the end of the file, before an optional comment.
166
+ let end = -1;
167
+ const lowest = Math.max(0, buffer.length - 22 - 0xffff);
168
+ for (let i = buffer.length - 22; i >= lowest; i--) {
169
+ if (buffer.readUInt32LE(i) === ZIP_END_OF_CENTRAL_DIRECTORY) { end = i; break; }
170
+ }
171
+ if (end === -1) throw notZip();
172
+ const total = buffer.readUInt16LE(end + 10);
173
+ let offset = buffer.readUInt32LE(end + 16);
174
+ if (total === 0xffff || offset === 0xffffffff) {
175
+ throw friendly('The downloaded file is a Zip64 archive, which the zip archive steps do not read.');
176
+ }
177
+ const names = [];
178
+ for (let n = 0; n < total; n++) {
179
+ if (offset + 46 > buffer.length || buffer.readUInt32LE(offset) !== ZIP_CENTRAL_DIRECTORY_ENTRY) throw notZip();
180
+ const nameLength = buffer.readUInt16LE(offset + 28);
181
+ const extraLength = buffer.readUInt16LE(offset + 30);
182
+ const commentLength = buffer.readUInt16LE(offset + 32);
183
+ const name = buffer.slice(offset + 46, offset + 46 + nameLength).toString('utf-8');
184
+ if (!name.endsWith('/')) names.push(name);
185
+ offset += 46 + nameLength + extraLength + commentLength;
186
+ }
187
+ return names;
188
+ }
189
+
190
+ function downloadedZipFileNames(world) {
191
+ assert.ok(world._lastDownload, 'No download has been performed.');
192
+ return zipFileNames(world._lastDownload.content);
193
+ }
194
+
195
+ // One name per row, several names in a row, or both.
196
+ function listedNames(table) {
197
+ return table.raw().flat().map((v) => v.trim()).filter(Boolean);
198
+ }
199
+
200
+ function baseName(entry) {
201
+ return entry.slice(entry.lastIndexOf('/') + 1);
202
+ }
152
203
 
153
204
  /**
154
- * (Pending) Assert the downloaded ZIP archive contains the listed filenames exactly.
205
+ * Assert the downloaded ZIP archive contains every listed file. A name
206
+ * matches a file by its full path in the archive ("reports/summary.csv")
207
+ * or by its file name alone ("summary.csv"). Other files may be present.
155
208
  *
156
209
  * Example #1: Then the downloaded file should be a zip archive containing the following files named:
157
210
  * | report.pdf |
@@ -166,12 +219,16 @@ Then('the downloaded file name should contain {string}', async function (part) {
166
219
  * | manifest.json |
167
220
  *
168
221
  */
169
- Then('the downloaded file should be a zip archive containing the following files named:', async function () {
170
- return 'pending';
222
+ Then('the downloaded file should be a zip archive containing the following files named:', async function (table) {
223
+ const names = downloadedZipFileNames(this);
224
+ const missing = listedNames(table).filter((want) => !names.some((n) => n === want || baseName(n) === want));
225
+ assert.strictEqual(missing.length, 0,
226
+ `The zip archive has no file named: ${missing.join(', ')}. It contains: ${names.join(', ') || '(no files)'}.`);
171
227
  });
172
228
 
173
229
  /**
174
- * (Pending) Assert the downloaded ZIP contains files whose names contain the listed substrings.
230
+ * Assert the downloaded ZIP contains, for every listed text, a file whose
231
+ * path in the archive contains it.
175
232
  *
176
233
  * Example #1: Then the downloaded file should be a zip archive containing the following files partially named:
177
234
  * | report |
@@ -186,12 +243,16 @@ Then('the downloaded file should be a zip archive containing the following files
186
243
  * | manifest |
187
244
  *
188
245
  */
189
- Then('the downloaded file should be a zip archive containing the following files partially named:', async function () {
190
- return 'pending';
246
+ Then('the downloaded file should be a zip archive containing the following files partially named:', async function (table) {
247
+ const names = downloadedZipFileNames(this);
248
+ const missing = listedNames(table).filter((part) => !names.some((n) => n.indexOf(part) !== -1));
249
+ assert.strictEqual(missing.length, 0,
250
+ `The zip archive has no file with a name containing: ${missing.join(', ')}. It contains: ${names.join(', ') || '(no files)'}.`);
191
251
  });
192
252
 
193
253
  /**
194
- * (Pending) Assert the downloaded ZIP does NOT contain files whose names contain the listed substrings.
254
+ * Assert the downloaded ZIP has no file whose path in the archive contains
255
+ * one of the listed texts.
195
256
  *
196
257
  * Example #1: Then the downloaded file should be a zip archive not containing the following files partially named:
197
258
  * | secret |
@@ -206,6 +267,9 @@ Then('the downloaded file should be a zip archive containing the following files
206
267
  * | __MACOSX |
207
268
  *
208
269
  */
209
- Then('the downloaded file should be a zip archive not containing the following files partially named:', async function () {
210
- return 'pending';
270
+ Then('the downloaded file should be a zip archive not containing the following files partially named:', async function (table) {
271
+ const names = downloadedZipFileNames(this);
272
+ const found = names.filter((n) => listedNames(table).some((part) => n.indexOf(part) !== -1));
273
+ assert.strictEqual(found.length, 0,
274
+ `The zip archive should not contain: ${found.join(', ')}.`);
211
275
  });
@@ -288,7 +288,7 @@ AfterStep(async function (step) {
288
288
  * Example #5: When I go to homepage
289
289
  * Then I save screenshot
290
290
  * Example #6: Given I am on "/news"
291
- * When I scroll to "#latest"
291
+ * When I scroll to the element "#latest"
292
292
  * Then I save screenshot
293
293
  * Example #7: Given I am on "/contact"
294
294
  * When I fill in "email" with "info@webship.co"
@@ -185,8 +185,10 @@ function resolveSelector(world, name) {
185
185
  );
186
186
  }
187
187
 
188
+ // Names are separated by a comma or by the whole word "and" ("a, b and c",
189
+ // "a, b, and c"), never by the letters "and" inside a name ("brand logo").
188
190
  function parseNames(text) {
189
- return text.split(/\s*(?:,|and)\s*/).map(s => s.trim()).filter(Boolean);
191
+ return text.split(/\s*,\s*(?:and\s+)?|\s+and\s+/).map(s => s.trim()).filter(Boolean);
190
192
  }
191
193
 
192
194
  // ---------------------------------------------------------------------------
@@ -242,7 +244,9 @@ async function assertPosition(page, position, c1Name, c1Sel, c2Name, c2Sel) {
242
244
  case 'over': {
243
245
  const intersects = !(g1.left >= g2.left + g2.width || g1.left + g1.width <= g2.left ||
244
246
  g1.top >= g2.top + g2.height || g1.top + g1.height <= g2.top);
245
- pass = intersects && g1.zIndex <= g2.zIndex;
247
+ // The subject (g1) is over the other component when they overlap and
248
+ // the subject is not stacked under it.
249
+ pass = intersects && g1.zIndex >= g2.zIndex;
246
250
  break;
247
251
  }
248
252
  }
@@ -700,7 +704,9 @@ Then(/^(I |we )*see ([a-zA-Z0-9 ,\-]+) outside of ([a-zA-Z0-9 ,\-]+)$/, async fu
700
704
  });
701
705
 
702
706
  /**
703
- * Assert a subject locator overlaps another via intersection and z-index.
707
+ * Assert a subject locator overlaps another via intersection and z-index:
708
+ * the two bounding boxes intersect and the z-index of the subject is not
709
+ * lower than the z-index of the other.
704
710
  *
705
711
  * Example #1: Then I see modal over content
706
712
  * Example #2: Then I see dropdown over nav
@@ -70,8 +70,8 @@ Given(/^the cookie "([^"]*)" is removed$/, async function (name) {
70
70
  * Example #3: Given all cookies are cleared
71
71
  * And I am an anonymous user
72
72
  * Example #4: Given all cookies are cleared
73
- * And localStorage is cleared
74
- * And sessionStorage is cleared
73
+ * And local storage is cleared
74
+ * And session storage is cleared
75
75
  * Example #5: Given all cookies are cleared
76
76
  * When I follow "Login"
77
77
  *
@@ -112,7 +112,7 @@ Given(/^(?:the )?local storage "([^"]*)" is set to "([^"]*)"$/, async function (
112
112
  * Example #1: Given the local storage "user" is removed
113
113
  * Example #2: Given local storage "theme" is removed
114
114
  * When I reload the page
115
- * Then "<body>" should not have class "theme-dark"
115
+ * Then the element "body" with the attribute "class" and the value containing "theme-dark" should not exist
116
116
  * Example #3: Given the local storage "onboarding_complete" is removed
117
117
  * Example #4: Given the local storage "cart" is removed
118
118
  * And I am on "/cart"