webship-js 2.0.11 → 2.0.13

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 (175) hide show
  1. package/.circleci/config.yml +10 -1
  2. package/.drone.yml +7 -7
  3. package/.github/workflows/github-actions.yml +48 -0
  4. package/.gitlab-ci.yml +9 -4
  5. package/.harness/webship-js-pipeline.yml +5 -6
  6. package/.semaphore/semaphore.yml +6 -9
  7. package/.teamcity/settings.kts +7 -6
  8. package/.travis.yml +6 -1
  9. package/AGENTS.md +1 -1
  10. package/CLAUDE.md +65 -23
  11. package/Jenkinsfile +5 -3
  12. package/azure-pipelines.yml +17 -8
  13. package/bamboo-specs/bamboo.yml +9 -15
  14. package/bin/init-webship.js +53 -10
  15. package/bitbucket-pipelines.yml +5 -1
  16. package/buildspec.yml +6 -7
  17. package/cloudbuild.yaml +28 -12
  18. package/codefresh.yml +6 -6
  19. package/cucumber.js +17 -10
  20. package/docs/00-quick-start.md +8 -0
  21. package/docs/02-bbr-smart-waits.md +15 -10
  22. package/docs/03-selector-registry.md +24 -0
  23. package/docs/04-step-reference.md +51 -25
  24. package/docs/05-web-first-assertions.md +6 -0
  25. package/docs/07-auth-state.md +1 -1
  26. package/docs/08-clock-mocking.md +21 -2
  27. package/docs/09-api-testing.md +40 -2
  28. package/docs/10-accessibility.md +2 -0
  29. package/docs/11-debugging.md +3 -1
  30. package/docs/12-ai-agent-guide.md +5 -0
  31. package/docs/13-faq.md +72 -1
  32. package/docs/14-recipes-cookbook.md +2 -0
  33. package/docs/15-tag-conventions.md +2 -1
  34. package/docs/16-ci-cd.md +140 -119
  35. package/docs/README.md +5 -5
  36. package/docs/advanced-screenshots.md +3 -1
  37. package/docs/api-step-definitions.md +16 -2
  38. package/docs/global-settings.md +69 -17
  39. package/docs/install-webship-js.md +2 -0
  40. package/docs/step-definitions/then-i-should-see.md +14 -1
  41. package/docs/step-definitions/then-item-checkbox.md +2 -0
  42. package/docs/step-definitions/when-i-fill.md +4 -0
  43. package/docs/step-definitions/when-i-select-option-select-list.md +2 -0
  44. package/examples/check-switch.html +37 -0
  45. package/examples/choice-controls.html +29 -0
  46. package/examples/click-whitespace.html +37 -0
  47. package/examples/datetime-fields.html +52 -0
  48. package/examples/element-selector-hint.html +16 -0
  49. package/examples/field-states.html +27 -0
  50. package/examples/fill-in-empty.html +26 -0
  51. package/examples/fill-unreachable.html +27 -0
  52. package/examples/follow-hidden-first.html +29 -0
  53. package/examples/iframe-inner.html +20 -0
  54. package/examples/iframe-nested.html +16 -0
  55. package/examples/iframe-outer.html +15 -0
  56. package/examples/multi-value-fields.html +54 -0
  57. package/examples/registered-names.html +15 -0
  58. package/examples/select-by-label.html +33 -0
  59. package/examples/settle-budget.html +21 -0
  60. package/examples/sorted-tables.html +38 -0
  61. package/examples/text-matching.html +48 -0
  62. package/examples/text-order.html +25 -0
  63. package/examples/touch.html +22 -0
  64. package/examples/viewport-top.html +36 -0
  65. package/package.json +17 -1
  66. package/playwright.config.ts +3 -1
  67. package/tests/check-api-launch-url.js +106 -0
  68. package/tests/check-assets.js +103 -0
  69. package/tests/check-attachments.js +105 -0
  70. package/tests/check-breakpoints.js +117 -0
  71. package/tests/check-clock.js +143 -0
  72. package/tests/check-config.js +90 -0
  73. package/tests/check-context.js +215 -0
  74. package/tests/check-dry-run.js +104 -0
  75. package/tests/check-examples.js +10 -4
  76. package/tests/check-exit-report.js +141 -0
  77. package/tests/check-javascript-errors.js +105 -0
  78. package/tests/check-must-fail.js +5 -4
  79. package/tests/check-network-changed.js +137 -0
  80. package/tests/check-scaffold.js +54 -2
  81. package/tests/check-screenshots.js +117 -0
  82. package/tests/check-settle-verbs.js +137 -0
  83. package/tests/check-time-limit.js +104 -0
  84. package/tests/check-video.js +156 -0
  85. package/tests/check-world.js +167 -0
  86. package/tests/features/api-base-url.feature +25 -0
  87. package/tests/features/api-form-data.feature +18 -0
  88. package/tests/features/api-json-paths.feature +24 -0
  89. package/tests/features/api-response-contains.feature +21 -0
  90. package/tests/features/api-response-header-presence.feature +17 -0
  91. package/tests/features/api-response-header.feature +17 -0
  92. package/tests/features/api-saved-placeholders.feature +37 -0
  93. package/tests/features/api-step-definitions-individual.feature +1 -1
  94. package/tests/features/api-tables.feature +40 -0
  95. package/tests/features/breakpoints.feature +25 -0
  96. package/tests/features/check-switch.feature +28 -0
  97. package/tests/features/choice-controls.feature +35 -0
  98. package/tests/features/click-whitespace.feature +29 -0
  99. package/tests/features/complete-api-testing-examples.feature +1 -1
  100. package/tests/features/datetime-field-lookup.feature +29 -0
  101. package/tests/features/element-selector-hint.feature +14 -0
  102. package/tests/features/field-state.feature +21 -0
  103. package/tests/features/fill-in-empty-value.feature +41 -0
  104. package/tests/features/fill-reachable.feature +13 -0
  105. package/tests/features/follow-hidden-first.feature +9 -0
  106. package/tests/features/iframe-nested.feature +43 -0
  107. package/tests/features/javascript-tolerated-errors.feature +20 -0
  108. package/tests/features/modal-open.feature +13 -0
  109. package/tests/features/multi-value-field-lookup.feature +30 -0
  110. package/tests/features/registered-names.feature +14 -0
  111. package/tests/features/select-by-label.feature +31 -0
  112. package/tests/features/selector-files.feature +14 -0
  113. package/tests/features/selectors-table-header.feature +35 -0
  114. package/tests/features/settle-budget.feature +11 -0
  115. package/tests/features/sorted-tables.feature +19 -0
  116. package/tests/features/storage-quoted-values.feature +26 -0
  117. package/tests/features/text-matching.feature +38 -0
  118. package/tests/features/text-order.feature +14 -0
  119. package/tests/features/touch.feature +21 -0
  120. package/tests/features/viewport-top.feature +13 -0
  121. package/tests/features/xml-namespaces.feature +34 -0
  122. package/tests/must-fail/api-json-paths.feature +21 -0
  123. package/tests/must-fail/api-response-contains.feature +23 -0
  124. package/tests/must-fail/api-response-header-presence.feature +17 -0
  125. package/tests/must-fail/api-response-header.feature +21 -0
  126. package/tests/must-fail/api-without-base-url.feature +11 -0
  127. package/tests/must-fail/breakpoints.feature +15 -0
  128. package/tests/must-fail/choice-controls.feature +25 -0
  129. package/tests/must-fail/clock.feature +11 -0
  130. package/tests/must-fail/datetime-field.feature +10 -0
  131. package/tests/must-fail/element-selector-hint.feature +17 -0
  132. package/tests/must-fail/field-state.feature +20 -0
  133. package/tests/must-fail/fill-field.feature +30 -0
  134. package/tests/must-fail/iframe-text.feature +17 -0
  135. package/tests/must-fail/modal-open.feature +26 -0
  136. package/tests/must-fail/multi-value-field.feature +18 -0
  137. package/tests/must-fail/registered-names.feature +25 -0
  138. package/tests/must-fail/select-list.feature +15 -0
  139. package/tests/must-fail/selector-files.feature +10 -0
  140. package/tests/must-fail/sorted-tables.feature +20 -0
  141. package/tests/must-fail/storage-before-a-page.feature +13 -0
  142. package/tests/must-fail/text-matching.feature +16 -0
  143. package/tests/must-fail/text-order.feature +15 -0
  144. package/tests/must-fail/viewport-top.feature +20 -0
  145. package/tests/must-fail/yaml-numbers.feature +48 -0
  146. package/tests/step-definitions/a11y.steps.js +24 -15
  147. package/tests/step-definitions/action.steps.js +53 -20
  148. package/tests/step-definitions/api.steps.js +349 -67
  149. package/tests/step-definitions/assertion.steps.js +100 -10
  150. package/tests/step-definitions/auth.steps.js +15 -18
  151. package/tests/step-definitions/clock.steps.js +22 -0
  152. package/tests/step-definitions/debug.steps.js +8 -0
  153. package/tests/step-definitions/dialog.steps.js +7 -0
  154. package/tests/step-definitions/element.steps.js +132 -17
  155. package/tests/step-definitions/field.steps.js +412 -96
  156. package/tests/step-definitions/form.steps.js +88 -37
  157. package/tests/step-definitions/iframe.steps.js +89 -29
  158. package/tests/step-definitions/input.steps.js +26 -7
  159. package/tests/step-definitions/javascript.steps.js +64 -22
  160. package/tests/step-definitions/modal.steps.js +79 -13
  161. package/tests/step-definitions/navigation.steps.js +14 -0
  162. package/tests/step-definitions/network.steps.js +15 -5
  163. package/tests/step-definitions/response.steps.js +6 -4
  164. package/tests/step-definitions/responsive.steps.js +26 -33
  165. package/tests/step-definitions/screenshot.steps.js +25 -8
  166. package/tests/step-definitions/scroll.steps.js +20 -0
  167. package/tests/step-definitions/selectors.steps.js +95 -48
  168. package/tests/step-definitions/storage.steps.js +38 -13
  169. package/tests/step-definitions/table.steps.js +81 -6
  170. package/tests/step-definitions/video.steps.js +52 -55
  171. package/tests/step-definitions/wait.steps.js +88 -23
  172. package/tests/step-definitions/web-first.steps.js +69 -35
  173. package/tests/step-definitions/webship.js +741 -145
  174. package/tests/step-definitions/xml.steps.js +49 -15
  175. package/tests/step-definitions/yaml.steps.js +45 -20
@@ -1,6 +1,6 @@
1
1
  'use strict';
2
2
 
3
- const { friendly } = require('./webship');
3
+ const { friendly, resolveAssetFile } = require('./webship');
4
4
 
5
5
  // Parse and assert against an XML response loaded from a file or doc string.
6
6
  //
@@ -12,7 +12,6 @@ const { friendly } = require('./webship');
12
12
  const { Given, Then, When } = require('@cucumber/cucumber');
13
13
  const assert = require('assert');
14
14
  const fs = require('fs');
15
- const path = require('path');
16
15
 
17
16
  let DOMParser;
18
17
  try { ({ DOMParser } = require('@xmldom/xmldom')); }
@@ -110,7 +109,8 @@ function evalXPath(doc, xpath) {
110
109
  }
111
110
 
112
111
  /**
113
- * Load XML response content from a file under `tests/assets/`.
112
+ * Load XML response content from a file under `tests/assets/` of the project,
113
+ * or from a path from the project root.
114
114
  *
115
115
  * Example #1: Given the response content from the file "feed.xml"
116
116
  * Example #2: Given the response content from the file "rss.xml"
@@ -120,8 +120,7 @@ function evalXPath(doc, xpath) {
120
120
  *
121
121
  */
122
122
  Given('the response content from the file {string}', async function (filename) {
123
- const p = path.isAbsolute(filename) ? filename : path.join(this.assetsFolder || './tests/assets', filename);
124
- setXmlResponse(this, fs.readFileSync(p, 'utf-8'));
123
+ setXmlResponse(this, fs.readFileSync(resolveAssetFile(this, filename), 'utf-8'));
125
124
  });
126
125
 
127
126
  /**
@@ -419,8 +418,34 @@ Then('the XML element {string} should have {int} element(s)', async function (xp
419
418
  assert.strictEqual((nodes || []).length, count);
420
419
  });
421
420
 
421
+ // Every namespace an XML document uses: each one an element declares
422
+ // (xmlns="..." or xmlns:p="..."), wherever it is declared, and the namespace
423
+ // of every element and attribute. Other attributes are values, not namespaces.
424
+ function usedNamespaces(doc) {
425
+ const found = new Set();
426
+ const walk = (el) => {
427
+ if (el.namespaceURI) found.add(el.namespaceURI);
428
+ for (const a of Array.from(el.attributes || [])) {
429
+ if (a.name === 'xmlns' || a.name.indexOf('xmlns:') === 0) {
430
+ if (a.value) found.add(a.value);
431
+ } else if (a.namespaceURI) {
432
+ found.add(a.namespaceURI);
433
+ }
434
+ }
435
+ for (const c of Array.from(el.childNodes || [])) if (c.nodeType === 1) walk(c);
436
+ };
437
+ if (doc && doc.documentElement) walk(doc.documentElement);
438
+ return found;
439
+ }
440
+
441
+ function listNamespaces(found) {
442
+ return found.size ? Array.from(found).map((ns) => `"${ns}"`).join(', ') : 'no namespace';
443
+ }
444
+
422
445
  /**
423
- * Assert the XML root declares an `xmlns:*` namespace URI.
446
+ * Assert the XML document uses a namespace: an element declares it
447
+ * (`xmlns="..."` or `xmlns:p="..."`) anywhere in the document, or an element
448
+ * or an attribute is in it.
424
449
  *
425
450
  * Example #1: Then the XML should use the namespace "http://www.w3.org/2005/Atom"
426
451
  * Example #2: Then the XML should use the namespace "http://www.sitemaps.org/schemas/sitemap/0.9"
@@ -430,14 +455,19 @@ Then('the XML element {string} should have {int} element(s)', async function (xp
430
455
  *
431
456
  */
432
457
  Then('the XML should use the namespace {string}', async function (ns) {
433
- const doc = ensureXml(this);
434
- const root = doc.documentElement;
435
- const found = Array.from(root.attributes || []).some((a) => a.value === ns);
436
- assert.ok(found, `Namespace "${ns}" not declared.`);
458
+ const found = usedNamespaces(ensureXml(this));
459
+ if (!found.has(ns)) {
460
+ throw friendly(
461
+ `The XML does not use the namespace "${ns}".\n` +
462
+ ` Found: ${listNamespaces(found)}\n` +
463
+ ' Hint: the step reads every xmlns declaration of the document, and the namespace of every element and attribute; the URI must match exactly.'
464
+ );
465
+ }
437
466
  });
438
467
 
439
468
  /**
440
- * Assert the XML root does NOT declare a namespace URI.
469
+ * Assert the XML document does NOT use a namespace: no element declares it
470
+ * and no element or attribute is in it.
441
471
  *
442
472
  * Example #1: Then the XML should not use the namespace "http://example.com/legacy"
443
473
  * Example #2: Then the XML should not use the namespace "http://example.com/internal"
@@ -447,10 +477,14 @@ Then('the XML should use the namespace {string}', async function (ns) {
447
477
  *
448
478
  */
449
479
  Then('the XML should not use the namespace {string}', async function (ns) {
450
- const doc = ensureXml(this);
451
- const root = doc.documentElement;
452
- const found = Array.from(root.attributes || []).some((a) => a.value === ns);
453
- assert.ok(!found, `Namespace "${ns}" should not be declared.`);
480
+ const found = usedNamespaces(ensureXml(this));
481
+ if (found.has(ns)) {
482
+ throw friendly(
483
+ `The XML uses the namespace "${ns}", but it should not.\n` +
484
+ ` Found: ${listNamespaces(found)}\n` +
485
+ ' Hint: the step reads every xmlns declaration of the document, and the namespace of every element and attribute.'
486
+ );
487
+ }
454
488
  });
455
489
 
456
490
  /**
@@ -1,6 +1,6 @@
1
1
  'use strict';
2
2
 
3
- const { friendly } = require('./webship');
3
+ const { friendly, failure, resolveAssetFile } = require('./webship');
4
4
 
5
5
  // Parse and assert against YAML response bodies.
6
6
  //
@@ -17,7 +17,6 @@ const { friendly } = require('./webship');
17
17
  const { Given, Then, When } = require('@cucumber/cucumber');
18
18
  const assert = require('assert');
19
19
  const fs = require('fs');
20
- const path = require('path');
21
20
 
22
21
  let YAML; try { YAML = require('js-yaml'); } catch { /* lazy */ }
23
22
  let Ajv; let addFormats;
@@ -123,7 +122,8 @@ function typeOfNode(node) {
123
122
  // ---------------------------------------------------------------------------
124
123
 
125
124
  /**
126
- * Load YAML response content from a file under `tests/assets/`.
125
+ * Load YAML response content from a file under `tests/assets/` of the
126
+ * project, or from a path from the project root.
127
127
  *
128
128
  * Multi-document streams (`---`) are parsed via `loadAll`. The first document
129
129
  * becomes the default; switch with `Given the active YAML document is N`.
@@ -137,8 +137,7 @@ function typeOfNode(node) {
137
137
  */
138
138
  Given('the YAML response content from the file {string}', async function (filename) {
139
139
  requireYaml();
140
- const p = path.isAbsolute(filename) ? filename : path.join(this.assetsFolder || './tests/assets', filename);
141
- setYamlResponse(this, fs.readFileSync(p, 'utf-8'));
140
+ setYamlResponse(this, fs.readFileSync(resolveAssetFile(this, filename), 'utf-8'));
142
141
  });
143
142
 
144
143
  /**
@@ -596,17 +595,41 @@ Then('the YAML value at {string} should not be empty', function (p) {
596
595
  // Numeric comparisons
597
596
  // ---------------------------------------------------------------------------
598
597
 
599
- function numAt(doc, p) {
598
+ // What a YAML value is, in the words of a failure message.
599
+ function describeValue(v) {
600
+ if (v === null || v === undefined) return 'null';
601
+ if (typeof v === 'string') return `the string "${v}"`;
602
+ if (typeof v === 'boolean') return `the boolean ${v}`;
603
+ if (Array.isArray(v)) return 'a list';
604
+ if (typeof v === 'object') return 'a mapping';
605
+ return String(v);
606
+ }
607
+
608
+ // The number at a path. Only a YAML number compares: a quoted "3", true or
609
+ // null is not one, whatever Number() would make of it.
610
+ function numAt(world, doc, p) {
600
611
  const nodes = evalPath(doc, p);
601
612
  if (nodes.length === 0) throw friendly(`YAML element "${p}" not found.`);
602
613
  const v = nodes[0];
603
- const n = typeof v === 'number' ? v : Number(v);
604
- if (!Number.isFinite(n)) throw friendly(`YAML value at "${p}" is not numeric: ${v}`);
605
- return n;
614
+ if (typeof v !== 'number' || !Number.isFinite(v)) {
615
+ throw failure(world.page, `The YAML value at "${p}" is ${describeValue(v)}, not ${typeof v === 'number' ? 'a finite number' : 'a number'}.`, {
616
+ hint: 'a number compares only with a YAML number: write it without quotes (replicas: 3, not replicas: "3").',
617
+ });
618
+ }
619
+ return v;
606
620
  }
607
621
 
622
+ // Fail a comparison that does not hold, with the value and the words of the step.
623
+ function expectNumber(world, p, v, holds, words, hint) {
624
+ if (!holds) throw failure(world.page, `The YAML value at "${p}" is ${v}, not ${words}.`, { hint });
625
+ }
626
+
627
+ const ABOVE_HINT = '"greater than" leaves the number itself out; "greater than or equal to" lets it in.';
628
+ const BELOW_HINT = '"less than" leaves the number itself out; "less than or equal to" lets it in.';
629
+
608
630
  /**
609
- * Assert a numeric YAML node is greater than a value.
631
+ * Assert a numeric YAML node is greater than a value. Only a YAML number
632
+ * compares: a quoted "3", true or null fails, as in every numeric step below.
610
633
  *
611
634
  * Example #1: Then the YAML value at "/spec/replicas" should be greater than 0
612
635
  * Example #2: Then the YAML value at "/timeout" should be greater than 5
@@ -617,7 +640,8 @@ function numAt(doc, p) {
617
640
  */
618
641
  Then('the YAML value at {string} should be greater than {float}', function (p, n) {
619
642
  const doc = activeDoc(this); ensureLoaded(this);
620
- assert.ok(numAt(doc, p) > n);
643
+ const v = numAt(this, doc, p);
644
+ expectNumber(this, p, v, v > n, `greater than ${n}`, ABOVE_HINT);
621
645
  });
622
646
 
623
647
  /**
@@ -632,7 +656,8 @@ Then('the YAML value at {string} should be greater than {float}', function (p, n
632
656
  */
633
657
  Then('the YAML value at {string} should be greater than or equal to {float}', function (p, n) {
634
658
  const doc = activeDoc(this); ensureLoaded(this);
635
- assert.ok(numAt(doc, p) >= n);
659
+ const v = numAt(this, doc, p);
660
+ expectNumber(this, p, v, v >= n, `greater than or equal to ${n}`, ABOVE_HINT);
636
661
  });
637
662
 
638
663
  /**
@@ -647,7 +672,8 @@ Then('the YAML value at {string} should be greater than or equal to {float}', fu
647
672
  */
648
673
  Then('the YAML value at {string} should be less than {float}', function (p, n) {
649
674
  const doc = activeDoc(this); ensureLoaded(this);
650
- assert.ok(numAt(doc, p) < n);
675
+ const v = numAt(this, doc, p);
676
+ expectNumber(this, p, v, v < n, `less than ${n}`, BELOW_HINT);
651
677
  });
652
678
 
653
679
  /**
@@ -662,7 +688,8 @@ Then('the YAML value at {string} should be less than {float}', function (p, n) {
662
688
  */
663
689
  Then('the YAML value at {string} should be less than or equal to {float}', function (p, n) {
664
690
  const doc = activeDoc(this); ensureLoaded(this);
665
- assert.ok(numAt(doc, p) <= n);
691
+ const v = numAt(this, doc, p);
692
+ expectNumber(this, p, v, v <= n, `less than or equal to ${n}`, BELOW_HINT);
666
693
  });
667
694
 
668
695
  /**
@@ -677,8 +704,8 @@ Then('the YAML value at {string} should be less than or equal to {float}', funct
677
704
  */
678
705
  Then('the YAML value at {string} should be between {float} and {float}', function (p, lo, hi) {
679
706
  const doc = activeDoc(this); ensureLoaded(this);
680
- const v = numAt(doc, p);
681
- assert.ok(v >= lo && v <= hi, `Value ${v} not in [${lo}, ${hi}].`);
707
+ const v = numAt(this, doc, p);
708
+ expectNumber(this, p, v, v >= lo && v <= hi, `between ${lo} and ${hi}`, '"between" includes both ends of the range.');
682
709
  });
683
710
 
684
711
  // ---------------------------------------------------------------------------
@@ -815,8 +842,7 @@ Then('the YAML at {string} should have keys {string}', function (p, csv) {
815
842
  Then('the YAML should match JSON Schema {string}', function (schemaFile) {
816
843
  if (!Ajv) throw friendly('Schema validation requires ajv. Install with: npm i ajv ajv-formats');
817
844
  const doc = activeDoc(this); ensureLoaded(this);
818
- const p = path.isAbsolute(schemaFile) ? schemaFile : path.join(this.assetsFolder || './tests/assets', schemaFile);
819
- const schema = JSON.parse(fs.readFileSync(p, 'utf-8'));
845
+ const schema = JSON.parse(fs.readFileSync(resolveAssetFile(this, schemaFile), 'utf-8'));
820
846
  const ajv = new Ajv({ allErrors: true, strict: false });
821
847
  if (addFormats) addFormats(ajv);
822
848
  const validate = ajv.compile(schema);
@@ -844,8 +870,7 @@ Then('the YAML should match JSON Schema {string}', function (schemaFile) {
844
870
  Then('the YAML should equal the file {string} ignoring keys {string}', function (file, ignoreCsv) {
845
871
  requireYaml();
846
872
  const doc = activeDoc(this); ensureLoaded(this);
847
- const p = path.isAbsolute(file) ? file : path.join(this.assetsFolder || './tests/assets', file);
848
- const expected = YAML.load(fs.readFileSync(p, 'utf-8'));
873
+ const expected = YAML.load(fs.readFileSync(resolveAssetFile(this, file), 'utf-8'));
849
874
  const ignore = ignoreCsv.split(',').map((s) => s.trim()).filter(Boolean);
850
875
  const stripAt = (root, ptr) => {
851
876
  const parts = ptr.split('/').filter(Boolean);