webship-js 2.0.9 → 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 (102) 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/09-api-testing.md +9 -2
  13. package/docs/11-debugging.md +21 -0
  14. package/docs/12-ai-agent-guide.md +3 -1
  15. package/docs/13-faq.md +3 -0
  16. package/docs/15-tag-conventions.md +4 -1
  17. package/docs/16-ci-cd.md +29 -13
  18. package/docs/api-step-definitions.md +13 -2
  19. package/docs/global-settings.md +2 -2
  20. package/docs/install-webship-js/ddev-webship-js.md +3 -0
  21. package/docs/install-webship-js.md +14 -2
  22. package/examples/a11y-legacy-widget.html +34 -0
  23. package/examples/auth-state.html +42 -0
  24. package/examples/clock.html +33 -0
  25. package/examples/downloads/webship-archive.zip +0 -0
  26. package/examples/downloads/webship-notes.txt +4 -0
  27. package/examples/downloads/webship-report.csv +4 -0
  28. package/examples/downloads.html +16 -0
  29. package/examples/element-viewport.html +42 -0
  30. package/examples/field-types.html +98 -0
  31. package/examples/iframe-newsletter.html +29 -0
  32. package/examples/iframe-order.html +26 -0
  33. package/examples/iframe.html +21 -0
  34. package/examples/javascript-errors.html +35 -0
  35. package/examples/links.html +1 -0
  36. package/examples/metatags.html +18 -0
  37. package/examples/mouse-and-pointer.html +83 -0
  38. package/examples/native-dialogs.html +8 -0
  39. package/examples/network.html +83 -0
  40. package/examples/scroll-horizontal.html +50 -0
  41. package/examples/selectors-position.html +29 -0
  42. package/examples/storage.html +57 -0
  43. package/examples/viewport-size.html +24 -0
  44. package/examples/wait-conditions.html +69 -0
  45. package/examples/web-first.html +99 -0
  46. package/package.json +9 -2
  47. package/tests/assets/catalog.xml +19 -0
  48. package/tests/assets/feed-namespaced.xml +13 -0
  49. package/tests/assets/sitemap.xml +14 -0
  50. package/tests/assets/webship-site-expected.yaml +21 -0
  51. package/tests/assets/webship-site.schema.json +46 -0
  52. package/tests/assets/webship-site.yaml +21 -0
  53. package/tests/check-examples.js +235 -0
  54. package/tests/check-must-fail.js +84 -0
  55. package/tests/check-paths.js +82 -0
  56. package/tests/check-report.js +119 -0
  57. package/tests/check-scaffold.js +211 -0
  58. package/tests/features/a11y.feature +18 -0
  59. package/tests/features/auth-state.feature +32 -0
  60. package/tests/features/clock.feature +27 -0
  61. package/tests/features/cookie.feature +9 -0
  62. package/tests/features/dialog.feature +27 -0
  63. package/tests/features/element.feature +47 -0
  64. package/tests/features/field.feature +104 -0
  65. package/tests/features/file-download.feature +64 -0
  66. package/tests/features/iframe.feature +83 -0
  67. package/tests/features/javascript.feature +47 -0
  68. package/tests/features/link.feature +11 -0
  69. package/tests/features/metatag.feature +38 -0
  70. package/tests/features/mouse-and-pointer.feature +86 -0
  71. package/tests/features/network-mocking.feature +80 -0
  72. package/tests/features/responsive.feature +27 -0
  73. package/tests/features/rest-and-api-requests.feature +120 -0
  74. package/tests/features/scroll-horizontal.feature +55 -0
  75. package/tests/features/selectors-position.feature +41 -0
  76. package/tests/features/storage.feature +98 -0
  77. package/tests/features/test--then--i-see-locator.feature +13 -0
  78. package/tests/features/test--then--i-should--see-text-in-element.feature +9 -1
  79. package/tests/features/test--then--the-field-should-contain-value.feature +8 -0
  80. package/tests/features/video.feature +1 -0
  81. package/tests/features/wait.feature +89 -0
  82. package/tests/features/web-first.feature +100 -0
  83. package/tests/features/xml.feature +96 -0
  84. package/tests/features/yaml.feature +75 -0
  85. package/tests/must-fail/assertions.feature +96 -0
  86. package/tests/must-fail/waits.feature +51 -0
  87. package/tests/reports/README.md +2 -2
  88. package/tests/step-definitions/a11y.steps.js +12 -8
  89. package/tests/step-definitions/api.steps.js +18 -45
  90. package/tests/step-definitions/assertion.steps.js +235 -61
  91. package/tests/step-definitions/dialog.steps.js +2 -2
  92. package/tests/step-definitions/element.steps.js +3 -1
  93. package/tests/step-definitions/field.steps.js +152 -22
  94. package/tests/step-definitions/file-download.steps.js +74 -10
  95. package/tests/step-definitions/rest.steps.js +23 -12
  96. package/tests/step-definitions/screenshot.steps.js +1 -1
  97. package/tests/step-definitions/selectors.steps.js +9 -3
  98. package/tests/step-definitions/storage.steps.js +3 -3
  99. package/tests/step-definitions/wait.steps.js +129 -39
  100. package/tests/step-definitions/webship.js +211 -3
  101. package/tests/step-definitions/xml.steps.js +76 -14
  102. package/tests/step-definitions/yaml.steps.js +46 -27
@@ -3,6 +3,11 @@
3
3
  const { friendly } = require('./webship');
4
4
 
5
5
  // Parse and assert against an XML response loaded from a file or doc string.
6
+ //
7
+ // The XPath of a step reads like the XML does: a prefixed name such as
8
+ // //dc:creator resolves against the xmlns:dc="..." declarations of the
9
+ // document, and a name without a prefix such as /urlset/url also matches an
10
+ // element of the default namespace (xmlns="..."), as in a sitemap or a feed.
6
11
 
7
12
  const { Given, Then, When } = require('@cucumber/cucumber');
8
13
  const assert = require('assert');
@@ -16,18 +21,80 @@ catch (e) {
16
21
  catch (e2) { /* will throw on use */ }
17
22
  }
18
23
 
19
- function ensureXml(world) {
24
+ function requireParser() {
20
25
  if (!DOMParser) throw friendly('XML steps require an XML DOM parser. Install @xmldom/xmldom.');
26
+ }
27
+
28
+ function ensureXml(world) {
29
+ requireParser();
30
+ if (world._xmlParseError) throw friendly(`The response is not valid XML: ${world._xmlParseError}`);
21
31
  if (!world._xml) throw friendly('No XML response has been set.');
22
32
  return world._xml;
23
33
  }
24
34
 
35
+ // Parse without throwing and without printing: returns the document, or the
36
+ // reason the content is not well-formed XML.
37
+ function parseXml(content) {
38
+ requireParser();
39
+ const problems = [];
40
+ let doc = null;
41
+ try {
42
+ doc = new DOMParser({
43
+ onError: (level, message) => { if (level !== 'warning') problems.push(String(message).trim()); },
44
+ }).parseFromString(String(content), 'text/xml');
45
+ } catch (e) {
46
+ if (problems.length === 0) problems.push(e.message);
47
+ }
48
+ if (problems.length === 0 && (!doc || !doc.documentElement)) problems.push('missing root element');
49
+ return problems.length ? { doc: null, error: problems[0] } : { doc, error: null };
50
+ }
51
+
52
+ // Keep the raw content even when it is not XML, so that the two format steps
53
+ // ("should be" / "should not be in XML format") can judge it.
54
+ function setXmlResponse(world, content) {
55
+ const { doc, error } = parseXml(content);
56
+ world._rawResponse = content;
57
+ world._xml = doc;
58
+ world._xmlParseError = error;
59
+ }
60
+
61
+ // Every prefix the document declares (xmlns:dc="..."), wherever it is declared.
62
+ function declaredNamespaces(doc) {
63
+ const map = {};
64
+ const walk = (el) => {
65
+ for (const a of Array.from(el.attributes || [])) {
66
+ if (a.name.indexOf('xmlns:') === 0 && !(a.name.slice(6) in map)) map[a.name.slice(6)] = a.value;
67
+ }
68
+ for (const c of Array.from(el.childNodes || [])) if (c.nodeType === 1) walk(c);
69
+ };
70
+ if (doc && doc.documentElement) walk(doc.documentElement);
71
+ return map;
72
+ }
73
+
25
74
  function evalXPath(doc, xpath) {
26
75
  // Minimal XPath: support /a/b and /a/b[@attr] and /a/b/text()
27
76
  // For richer XPath, users can install xpath module.
28
77
  let xpathLib;
29
78
  try { xpathLib = require('xpath'); } catch (e) { xpathLib = null; }
30
- if (xpathLib) return xpathLib.select(xpath, doc);
79
+ if (xpathLib) {
80
+ // The XPath reads like the XML does: a prefixed name (//dc:creator)
81
+ // resolves against the prefixes the document itself declares, and a name
82
+ // without a prefix (/urlset/url) also matches an element of the default
83
+ // namespace (xmlns="..."), which every sitemap and Atom feed declares.
84
+ try {
85
+ return xpathLib.parse(xpath).select({
86
+ node: doc,
87
+ namespaces: declaredNamespaces(doc),
88
+ allowAnyNamespaceForNoPrefix: true,
89
+ });
90
+ } catch (e) {
91
+ throw friendly({
92
+ action: `evaluate the XPath "${xpath}"`,
93
+ cause: e,
94
+ hint: 'check the XPath syntax; a prefix (dc:creator) must be declared in the XML with xmlns:dc="...".',
95
+ });
96
+ }
97
+ }
31
98
  // Fallback simple traversal
32
99
  const parts = xpath.split('/').filter(Boolean);
33
100
  let nodes = [doc.documentElement].filter((n) => n && n.nodeName === parts[0]);
@@ -54,9 +121,7 @@ function evalXPath(doc, xpath) {
54
121
  */
55
122
  Given('the response content from the file {string}', async function (filename) {
56
123
  const p = path.isAbsolute(filename) ? filename : path.join(this.assetsFolder || './tests/assets', filename);
57
- const content = fs.readFileSync(p, 'utf-8');
58
- this._rawResponse = content;
59
- this._xml = new DOMParser().parseFromString(content, 'text/xml');
124
+ setXmlResponse(this, fs.readFileSync(p, 'utf-8'));
60
125
  });
61
126
 
62
127
  /**
@@ -85,8 +150,7 @@ Given('the response content from the file {string}', async function (filename) {
85
150
  *
86
151
  */
87
152
  Given('the response content is the following:', async function (docString) {
88
- this._rawResponse = docString;
89
- this._xml = new DOMParser().parseFromString(docString, 'text/xml');
153
+ setXmlResponse(this, docString);
90
154
  });
91
155
 
92
156
  /**
@@ -107,8 +171,8 @@ Given('the response content is the following:', async function (docString) {
107
171
  */
108
172
  Then('the response should be in XML format', async function () {
109
173
  assert.ok(this._rawResponse, 'No response content set.');
110
- const doc = new DOMParser().parseFromString(this._rawResponse, 'text/xml');
111
- assert.ok(doc && doc.documentElement, 'Response is not valid XML.');
174
+ const { error } = parseXml(this._rawResponse);
175
+ assert.ok(!error, `Response is not valid XML: ${error}`);
112
176
  });
113
177
 
114
178
  /**
@@ -131,11 +195,9 @@ Then('the response should be in XML format', async function () {
131
195
  *
132
196
  */
133
197
  Then('the response should not be in XML format', async function () {
134
- if (!this._rawResponse) return;
135
- try {
136
- const doc = new DOMParser().parseFromString(this._rawResponse, 'text/xml');
137
- assert.ok(!doc || !doc.documentElement || doc.getElementsByTagName('parsererror').length > 0, 'Response is XML.');
138
- } catch (e) { /* good */ }
198
+ assert.ok(this._rawResponse, 'No response content set.');
199
+ const { error } = parseXml(this._rawResponse);
200
+ assert.ok(error, 'Response is valid XML.');
139
201
  });
140
202
 
141
203
  /**
@@ -31,10 +31,30 @@ function requireYaml() {
31
31
 
32
32
  function ensureLoaded(world) {
33
33
  requireYaml();
34
+ if (world._yamlParseError) {
35
+ throw friendly(`The response is not valid YAML: ${world._yamlParseError.message}`);
36
+ }
34
37
  if (world._yaml === undefined) throw friendly('No YAML response has been set.');
35
38
  return world._yaml;
36
39
  }
37
40
 
41
+ // Keep the raw content even when it does not parse, so that the two format
42
+ // steps ("should be" / "should not be in YAML format") can judge it.
43
+ function setYamlResponse(world, content) {
44
+ requireYaml();
45
+ world._rawYamlResponse = content;
46
+ world._yamlDocIndex = 0;
47
+ world._yamlParseError = null;
48
+ try {
49
+ world._yamlDocs = YAML.loadAll(content);
50
+ world._yaml = world._yamlDocs[0];
51
+ } catch (e) {
52
+ world._yamlDocs = [];
53
+ world._yaml = undefined;
54
+ world._yamlParseError = e;
55
+ }
56
+ }
57
+
38
58
  // Active document index for multi-document streams.
39
59
  function activeIndex(world) { return world._yamlDocIndex || 0; }
40
60
  function activeDoc(world) {
@@ -118,11 +138,7 @@ function typeOfNode(node) {
118
138
  Given('the YAML response content from the file {string}', async function (filename) {
119
139
  requireYaml();
120
140
  const p = path.isAbsolute(filename) ? filename : path.join(this.assetsFolder || './tests/assets', filename);
121
- const content = fs.readFileSync(p, 'utf-8');
122
- this._rawYamlResponse = content;
123
- this._yamlDocs = YAML.loadAll(content);
124
- this._yaml = this._yamlDocs[0];
125
- this._yamlDocIndex = 0;
141
+ setYamlResponse(this, fs.readFileSync(p, 'utf-8'));
126
142
  });
127
143
 
128
144
  /**
@@ -162,11 +178,7 @@ Given('the YAML response content from the file {string}', async function (filena
162
178
  *
163
179
  */
164
180
  Given('the YAML response content is the following:', async function (docString) {
165
- requireYaml();
166
- this._rawYamlResponse = docString;
167
- this._yamlDocs = YAML.loadAll(docString);
168
- this._yaml = this._yamlDocs[0];
169
- this._yamlDocIndex = 0;
181
+ setYamlResponse(this, docString);
170
182
  });
171
183
 
172
184
  /**
@@ -236,12 +248,13 @@ Then('the response should be in YAML format', async function () {
236
248
  });
237
249
 
238
250
  /**
239
- * Assert the loaded response is NOT valid YAML.
251
+ * Assert the loaded response is NOT valid YAML. Fails when the content
252
+ * parses: a line of plain text or a JSON document is valid YAML too.
240
253
  *
241
254
  * Example #1: Then the response should not be in YAML format
242
255
  * Example #2: Given the YAML response content is the following:
243
256
  * """
244
- * <not> yaml </not>
257
+ * items: [one, two
245
258
  * """
246
259
  * Then the response should not be in YAML format
247
260
  * Example #3: And the response should not be in YAML format
@@ -255,9 +268,11 @@ Then('the response should be in YAML format', async function () {
255
268
  *
256
269
  */
257
270
  Then('the response should not be in YAML format', async function () {
258
- if (!this._rawYamlResponse || !YAML) return;
271
+ requireYaml();
272
+ assert.ok(this._rawYamlResponse, 'No YAML response content set.');
259
273
  try { YAML.loadAll(this._rawYamlResponse); }
260
274
  catch (e) { return; /* expected */ }
275
+ assert.fail('Response is valid YAML.');
261
276
  });
262
277
 
263
278
  /**
@@ -853,6 +868,17 @@ Then('the YAML should equal the file {string} ignoring keys {string}', function
853
868
  // Namespace + debug
854
869
  // ---------------------------------------------------------------------------
855
870
 
871
+ // One answer for both namespace steps: a top-level value equal to the
872
+ // namespace, or the namespace anywhere in the raw text.
873
+ function usesNamespace(world, ns) {
874
+ const doc = activeDoc(world);
875
+ if (doc && typeof doc === 'object') {
876
+ const values = Object.values(doc).map((v) => (v == null ? '' : String(v)));
877
+ if (values.includes(ns)) return true;
878
+ }
879
+ return (world._rawYamlResponse || '').indexOf(ns) !== -1;
880
+ }
881
+
856
882
  /**
857
883
  * Assert the YAML document declares a namespace value (mirrors xml.steps.js).
858
884
  * Checks top-level scalar values and falls back to a raw-text scan.
@@ -865,16 +891,14 @@ Then('the YAML should equal the file {string} ignoring keys {string}', function
865
891
  *
866
892
  */
867
893
  Then('the YAML should use the namespace {string}', function (ns) {
868
- const doc = activeDoc(this); ensureLoaded(this);
869
- if (doc && typeof doc === 'object') {
870
- const values = Object.values(doc).map((v) => (v == null ? '' : String(v)));
871
- if (values.includes(ns)) return;
872
- }
873
- assert.ok((this._rawYamlResponse || '').indexOf(ns) !== -1, `Namespace "${ns}" not declared.`);
894
+ ensureLoaded(this);
895
+ assert.ok(usesNamespace(this, ns), `Namespace "${ns}" not declared.`);
874
896
  });
875
897
 
876
898
  /**
877
- * Assert the YAML document does NOT declare a namespace value.
899
+ * Assert the YAML document does NOT declare a namespace value: the exact
900
+ * opposite of the step above (no top-level value equal to it, and the raw
901
+ * text does not carry it).
878
902
  *
879
903
  * Example #1: Then the YAML should not use the namespace "v0"
880
904
  * Example #2: Then the YAML should not use the namespace "internal/v1"
@@ -884,13 +908,8 @@ Then('the YAML should use the namespace {string}', function (ns) {
884
908
  *
885
909
  */
886
910
  Then('the YAML should not use the namespace {string}', function (ns) {
887
- const doc = activeDoc(this); ensureLoaded(this);
888
- if (doc && typeof doc === 'object') {
889
- const values = Object.values(doc).map((v) => (v == null ? '' : String(v)));
890
- assert.ok(!values.includes(ns), `Namespace "${ns}" should not be declared.`);
891
- return;
892
- }
893
- assert.ok((this._rawYamlResponse || '').indexOf(ns) === -1, `Namespace "${ns}" should not be declared.`);
911
+ ensureLoaded(this);
912
+ assert.ok(!usesNamespace(this, ns), `Namespace "${ns}" should not be declared.`);
894
913
  });
895
914
 
896
915
  /**