webship-js 2.0.1 → 2.0.3

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 (194) hide show
  1. package/AGENTS.md +109 -0
  2. package/CLAUDE.md +317 -0
  3. package/bin/generate-reports.js +363 -0
  4. package/bin/init-webship.js +343 -0
  5. package/bin/postinstall.js +8 -74
  6. package/cucumber.js +66 -2
  7. package/docs/00-quick-start.md +102 -0
  8. package/docs/01-getting-started.md +102 -0
  9. package/docs/02-bbr-smart-waits.md +77 -0
  10. package/docs/03-selector-registry.md +95 -0
  11. package/docs/04-step-reference.md +728 -0
  12. package/docs/05-web-first-assertions.md +91 -0
  13. package/docs/06-network-and-dialogs.md +83 -0
  14. package/docs/07-auth-state.md +75 -0
  15. package/docs/08-clock-mocking.md +59 -0
  16. package/docs/09-api-testing.md +114 -0
  17. package/docs/10-accessibility.md +167 -0
  18. package/docs/11-debugging.md +129 -0
  19. package/docs/12-ai-agent-guide.md +338 -0
  20. package/docs/13-faq.md +236 -0
  21. package/docs/14-recipes-cookbook.md +255 -0
  22. package/docs/15-tag-conventions.md +76 -0
  23. package/docs/advanced-screenshots/then-i-save-fullscreen-screenshot.md +36 -0
  24. package/docs/advanced-screenshots/then-i-save-width-x-height-screenshot.md +34 -0
  25. package/docs/advanced-screenshots/when-i-save-screenshot-name-filename.md +45 -0
  26. package/docs/advanced-screenshots.md +52 -0
  27. package/docs/advanced-selectors.md +18 -0
  28. package/docs/api-step-definitions.md +45 -0
  29. package/docs/diffy-step-definitions/then-compare-diffy-env1-env2.md +30 -0
  30. package/docs/diffy-step-definitions/then-create-diffy-comparison-name-value.md +21 -0
  31. package/docs/diffy-step-definitions/then-create-diffy-comparison.md +25 -0
  32. package/docs/diffy-step-definitions/then-create-diffy-screenshot-environment-name.md +35 -0
  33. package/docs/diffy-step-definitions/then-i-take-screenshot.md +21 -0
  34. package/docs/diffy-step-definitions/then-i-take-screenshots-all-breakpoints.md +27 -0
  35. package/docs/diffy-step-definitions/then-send-screenshots-diffy-name-value.md +27 -0
  36. package/docs/diffy-step-definitions/then-upload-folder-url-diffy-snapshotname.md +28 -0
  37. package/docs/diffy-step-definitions/then-wait-diffy-comparison-complete.md +21 -0
  38. package/docs/diffy-step-definitions/when-i-resize-window-number.md +29 -0
  39. package/docs/diffy-step-definitions.md +21 -0
  40. package/docs/global-settings.md +244 -0
  41. package/docs/index.md +104 -0
  42. package/docs/install-webship-js/ddev-webship-js.md +52 -0
  43. package/docs/install-webship-js.md +35 -0
  44. package/docs/overview.md +41 -0
  45. package/docs/step-definitions/given-i-am-anonymous-user.md +67 -0
  46. package/docs/step-definitions/given-i-am-homepage.md +68 -0
  47. package/docs/step-definitions/given-i-am-specific-page.md +72 -0
  48. package/docs/step-definitions/then-i-should-be.md +56 -0
  49. package/docs/step-definitions/then-i-should-see.md +62 -0
  50. package/docs/step-definitions/then-item-checkbox.md +54 -0
  51. package/docs/step-definitions/then-item-link-should-contain-url.md +84 -0
  52. package/docs/step-definitions/then-item-should-contain.md +67 -0
  53. package/docs/step-definitions/then-radio-button-value-should-be-selected.md +68 -0
  54. package/docs/step-definitions/then-response-status-code-should-be-number.md +69 -0
  55. package/docs/step-definitions/then-value-radio-button-selected.md +62 -0
  56. package/docs/step-definitions/when-i-attach-file-file-name-element.md +71 -0
  57. package/docs/step-definitions/when-i-check-checkbox.md +60 -0
  58. package/docs/step-definitions/when-i-click-link.md +51 -0
  59. package/docs/step-definitions/when-i-click-operation-text-row.md +71 -0
  60. package/docs/step-definitions/when-i-fill.md +59 -0
  61. package/docs/step-definitions/when-i-go-homepage.md +60 -0
  62. package/docs/step-definitions/when-i-go-specific-page.md +67 -0
  63. package/docs/step-definitions/when-i-move-backward-one-page.md +49 -0
  64. package/docs/step-definitions/when-i-move-forward-one-page.md +58 -0
  65. package/docs/step-definitions/when-i-press-button.md +58 -0
  66. package/docs/step-definitions/when-i-reload-page.md +51 -0
  67. package/docs/step-definitions/when-i-scroll.md +73 -0
  68. package/docs/step-definitions/when-i-select-option-select-list.md +53 -0
  69. package/docs/step-definitions/when-i-select-radio-button-value.md +62 -0
  70. package/docs/step-definitions/when-i-uncheck-checkbox.md +57 -0
  71. package/docs/step-definitions/when-i-wait-ajax-finish.md +64 -0
  72. package/docs/step-definitions/when-i-wait.md +62 -0
  73. package/docs/step-definitions.md +50 -0
  74. package/examples/a11y.html +31 -0
  75. package/examples/cookies.html +10 -0
  76. package/examples/date.html +12 -0
  77. package/examples/diffy/baseline.html +54 -0
  78. package/examples/diffy/changed.html +63 -0
  79. package/examples/diffy/index.html +52 -0
  80. package/examples/element.html +11 -0
  81. package/examples/field.html +24 -0
  82. package/examples/index.html +6 -0
  83. package/examples/keyboard.html +11 -0
  84. package/examples/links.html +9 -0
  85. package/examples/modal.html +14 -0
  86. package/examples/path.html +3 -0
  87. package/examples/table.html +13 -0
  88. package/examples/test--when--i-additionally-select.html +27 -0
  89. package/package.json +19 -6
  90. package/playwright.config.ts +3 -2
  91. package/tests/features/a11y.feature +39 -0
  92. package/tests/features/cookie.feature +13 -0
  93. package/tests/features/date.feature +11 -0
  94. package/tests/features/diffy/test--diffy-01-example-demo.feature +22 -0
  95. package/tests/features/diffy/test--diffy-02-all-steps.feature +52 -0
  96. package/tests/features/diffy/test--diffy-03-real-api.feature +21 -0
  97. package/tests/features/element.feature +16 -0
  98. package/tests/features/field.feature +25 -0
  99. package/tests/features/keyboard.feature +10 -0
  100. package/tests/features/link.feature +11 -0
  101. package/tests/features/modal-advanced-example.feature +1 -1
  102. package/tests/features/modal.feature +11 -0
  103. package/tests/features/path.feature +16 -0
  104. package/tests/features/response.feature +8 -0
  105. package/tests/features/responsive.feature +10 -0
  106. package/tests/features/table.feature +18 -0
  107. package/tests/features/test--then--i-save-screenshot.feature +33 -0
  108. package/tests/features/test--then--i-see-locator.feature +320 -0
  109. package/tests/features/test--then--i-should-see-n-elements.feature +24 -0
  110. package/tests/features/test--then--print-current-url-and-response.feature +21 -0
  111. package/tests/features/test--when--i-additionally-select.feature +30 -0
  112. package/tests/features/test--when--i-follow.feature +22 -0
  113. package/tests/features/wait.feature +7 -0
  114. package/tests/features/yaml.feature +102 -0
  115. package/tests/reports/README.md +55 -0
  116. package/tests/selectors/_canonical-keys.json +113 -0
  117. package/tests/selectors/back-end-selectors.json +19 -0
  118. package/tests/selectors/cms-contentful-admin.json +35 -0
  119. package/tests/selectors/cms-craft-admin.json +39 -0
  120. package/tests/selectors/cms-drupal-cms-gin.json +56 -0
  121. package/tests/selectors/cms-drupal-core-claro.json +50 -0
  122. package/tests/selectors/cms-generic-admin.json +34 -0
  123. package/tests/selectors/cms-ghost-admin.json +34 -0
  124. package/tests/selectors/cms-joomla-admin.json +41 -0
  125. package/tests/selectors/cms-magento2-admin.json +32 -0
  126. package/tests/selectors/cms-prestashop-admin.json +38 -0
  127. package/tests/selectors/cms-shopify-admin.json +25 -0
  128. package/tests/selectors/cms-strapi-admin.json +42 -0
  129. package/tests/selectors/cms-typo3-admin.json +41 -0
  130. package/tests/selectors/cms-woocommerce-front.json +50 -0
  131. package/tests/selectors/cms-wordpress-admin.json +31 -0
  132. package/tests/selectors/framework-ant-design.json +80 -0
  133. package/tests/selectors/framework-bootstrap.json +86 -0
  134. package/tests/selectors/framework-bulma.json +74 -0
  135. package/tests/selectors/framework-chakra.json +58 -0
  136. package/tests/selectors/framework-foundation.json +51 -0
  137. package/tests/selectors/framework-material-ui.json +72 -0
  138. package/tests/selectors/framework-shadcn.json +51 -0
  139. package/tests/selectors/framework-tailwind.json +40 -0
  140. package/tests/selectors/framework-vuetify.json +61 -0
  141. package/tests/selectors/front-end-selectors.json +16 -0
  142. package/tests/selectors/homepage-selectors.json +13 -0
  143. package/tests/step-definitions/a11y.steps.js +798 -0
  144. package/tests/step-definitions/action.steps.js +167 -0
  145. package/tests/step-definitions/{webship-api.js → api.steps.js} +254 -44
  146. package/tests/step-definitions/assertion.steps.js +352 -0
  147. package/tests/step-definitions/auth.steps.js +124 -0
  148. package/tests/step-definitions/clock.steps.js +128 -0
  149. package/tests/step-definitions/cookie.steps.js +216 -0
  150. package/tests/step-definitions/debug.steps.js +31 -0
  151. package/tests/step-definitions/dialog.steps.js +193 -0
  152. package/tests/step-definitions/element.steps.js +314 -0
  153. package/tests/step-definitions/field.steps.js +653 -0
  154. package/tests/step-definitions/file-download.steps.js +193 -0
  155. package/tests/step-definitions/form.steps.js +333 -0
  156. package/tests/step-definitions/iframe.steps.js +178 -0
  157. package/tests/step-definitions/input.steps.js +163 -0
  158. package/tests/step-definitions/javascript.steps.js +71 -0
  159. package/tests/step-definitions/keyboard.steps.js +78 -0
  160. package/tests/step-definitions/link.steps.js +142 -0
  161. package/tests/step-definitions/metatag.steps.js +91 -0
  162. package/tests/step-definitions/modal.steps.js +219 -0
  163. package/tests/step-definitions/navigation.steps.js +218 -0
  164. package/tests/step-definitions/network.steps.js +238 -0
  165. package/tests/step-definitions/path.steps.js +141 -0
  166. package/tests/step-definitions/response.steps.js +98 -0
  167. package/tests/step-definitions/responsive.steps.js +123 -0
  168. package/tests/step-definitions/rest.steps.js +111 -0
  169. package/tests/step-definitions/screenshot.steps.js +423 -0
  170. package/tests/step-definitions/scroll.steps.js +189 -0
  171. package/tests/step-definitions/selectors.steps.js +996 -0
  172. package/tests/step-definitions/storage.steps.js +194 -0
  173. package/tests/step-definitions/table.steps.js +181 -0
  174. package/tests/step-definitions/wait.steps.js +400 -0
  175. package/tests/step-definitions/web-first.steps.js +296 -0
  176. package/tests/step-definitions/webship.js +567 -923
  177. package/tests/step-definitions/xml.steps.js +409 -0
  178. package/tests/step-definitions/yaml.steps.js +911 -0
  179. package/tests/step-definitions-diffy/README.md +329 -0
  180. package/tests/step-definitions-diffy/mock-diffy-api/server.js +84 -0
  181. package/tests/step-definitions-diffy/webship-diffy-mock.js +31 -0
  182. package/tests/step-definitions-diffy/webship-diffy.js +459 -0
  183. package/tsconfig.json +19 -3
  184. package/generate-reports.js +0 -22
  185. package/required/cucumber.js +0 -37
  186. package/required/generate-reports.js +0 -22
  187. package/required/package.json +0 -18
  188. package/required/playwright.config.ts +0 -37
  189. package/required/tests/features/README.md +0 -1
  190. package/required/tests/features/check-homepage.feature +0 -8
  191. package/required/tests/reports/README.md +0 -1
  192. package/required/tests/step-definitions/README.md +0 -1
  193. package/required/tests/step-definitions/custom.js +0 -4
  194. package/required/tsconfig.json +0 -12
@@ -0,0 +1,911 @@
1
+ 'use strict';
2
+
3
+ // Parse and assert against YAML response bodies.
4
+ //
5
+ // Mirrors xml.steps.js where it makes sense (path-based existence / equality
6
+ // / contains / count / "namespace") and adds YAML-native concepts: multi-
7
+ // document streams (`---`), type-of assertions, numeric comparisons,
8
+ // array-of-objects matching, JSONPath / JMESPath queries, JSON-Schema
9
+ // validation, key-set assertions, diff vs. expected, and well-formedness.
10
+ //
11
+ // Path syntax for the simple `/a/b/c` form is JSON Pointer (RFC 6901)
12
+ // flavoured: numeric segments index sequences (`/items/0/name`). For richer
13
+ // queries use the dedicated JSONPath / JMESPath steps.
14
+
15
+ const { Given, Then, When } = require('@cucumber/cucumber');
16
+ const assert = require('assert');
17
+ const fs = require('fs');
18
+ const path = require('path');
19
+
20
+ let YAML; try { YAML = require('js-yaml'); } catch { /* lazy */ }
21
+ let Ajv; let addFormats;
22
+ try { Ajv = require('ajv'); } catch { /* lazy */ }
23
+ try { addFormats = require('ajv-formats'); } catch { /* lazy */ }
24
+
25
+ function requireYaml() {
26
+ if (!YAML) throw new Error('YAML steps require js-yaml. Install with: npm i js-yaml');
27
+ return YAML;
28
+ }
29
+
30
+ function ensureLoaded(world) {
31
+ requireYaml();
32
+ if (world._yaml === undefined) throw new Error('No YAML response has been set.');
33
+ return world._yaml;
34
+ }
35
+
36
+ // Active document index for multi-document streams.
37
+ function activeIndex(world) { return world._yamlDocIndex || 0; }
38
+ function activeDoc(world) {
39
+ const docs = world._yamlDocs;
40
+ if (Array.isArray(docs) && docs.length > 0) return docs[activeIndex(world)];
41
+ return world._yaml;
42
+ }
43
+
44
+ // Walk a "/a/b/c" path. Numeric segments index arrays. Returns array
45
+ // of matches (0 or 1 entries) so call sites mirror xml's evalXPath contract.
46
+ function evalPath(doc, p) {
47
+ if (!p || p === '/') return [doc];
48
+ const parts = p.split('/').filter(Boolean);
49
+ let cur = doc;
50
+ for (const raw of parts) {
51
+ if (cur == null) return [];
52
+ const m = raw.match(/^([^\[]+)?(?:\[(\d+)\])?$/);
53
+ const key = m && m[1];
54
+ const idx = m && m[2] !== undefined ? parseInt(m[2], 10) : null;
55
+ if (key) {
56
+ if (typeof cur !== 'object' || !(key in cur)) return [];
57
+ cur = cur[key];
58
+ }
59
+ if (idx !== null) {
60
+ if (!Array.isArray(cur) || idx >= cur.length) return [];
61
+ cur = cur[idx];
62
+ }
63
+ if (!key && idx === null && /^\d+$/.test(raw)) {
64
+ const i = parseInt(raw, 10);
65
+ if (!Array.isArray(cur) || i >= cur.length) return [];
66
+ cur = cur[i];
67
+ }
68
+ }
69
+ return cur === undefined ? [] : [cur];
70
+ }
71
+
72
+ function nodeText(node) {
73
+ if (node === null || node === undefined) return '';
74
+ if (typeof node === 'string') return node;
75
+ if (typeof node === 'number' || typeof node === 'boolean') return String(node);
76
+ return YAML.dump(node).trim();
77
+ }
78
+
79
+ function nodeAttr(node, key) {
80
+ if (node && typeof node === 'object' && !Array.isArray(node) && key in node) {
81
+ return nodeText(node[key]);
82
+ }
83
+ return null;
84
+ }
85
+
86
+ function nodeHasAttr(node, key) {
87
+ return node && typeof node === 'object' && !Array.isArray(node) && Object.prototype.hasOwnProperty.call(node, key);
88
+ }
89
+
90
+ function typeOfNode(node) {
91
+ if (node === null) return 'null';
92
+ if (Array.isArray(node)) return 'array';
93
+ const t = typeof node;
94
+ if (t === 'object') return 'object';
95
+ if (t === 'number') return Number.isInteger(node) ? 'integer' : 'number';
96
+ return t; // 'string' | 'boolean'
97
+ }
98
+
99
+ // ---------------------------------------------------------------------------
100
+ // Loading
101
+ // ---------------------------------------------------------------------------
102
+
103
+ /**
104
+ * Load YAML response content from a file under `tests/assets/`.
105
+ *
106
+ * Multi-document streams (`---`) are parsed via `loadAll`. The first document
107
+ * becomes the default; switch with `Given the active YAML document is N`.
108
+ *
109
+ * Example #1: Given the YAML response content from the file "config.yml"
110
+ * Example #2: Given the YAML response content from the file "openapi.yaml"
111
+ * Example #3: And the YAML response content from the file "users.yml"
112
+ * Example #4: Given the YAML response content from the file "k8s-deployment.yaml"
113
+ * Example #5: Given the YAML response content from the file "/tmp/sample.yml"
114
+ *
115
+ */
116
+ Given('the YAML response content from the file {string}', async function (filename) {
117
+ requireYaml();
118
+ const p = path.isAbsolute(filename) ? filename : path.join(this.assetsFolder || './tests/assets', filename);
119
+ const content = fs.readFileSync(p, 'utf-8');
120
+ this._rawYamlResponse = content;
121
+ this._yamlDocs = YAML.loadAll(content);
122
+ this._yaml = this._yamlDocs[0];
123
+ this._yamlDocIndex = 0;
124
+ });
125
+
126
+ /**
127
+ * Set YAML response content inline from a Gherkin doc string. Supports
128
+ * multi-document streams.
129
+ *
130
+ * Example #1: Given the YAML response content is the following:
131
+ * """
132
+ * name: example
133
+ * version: 1.0.0
134
+ * """
135
+ * Example #2: Given the YAML response content is the following:
136
+ * """
137
+ * items:
138
+ * - id: 1
139
+ * title: Hello
140
+ * """
141
+ * Example #3: And the YAML response content is the following:
142
+ * """
143
+ * status: ok
144
+ * count: 5
145
+ * """
146
+ * Example #4: Given the YAML response content is the following:
147
+ * """
148
+ * apiVersion: v1
149
+ * kind: ConfigMap
150
+ * ---
151
+ * apiVersion: v1
152
+ * kind: Service
153
+ * """
154
+ * Example #5: Given the YAML response content is the following:
155
+ * """
156
+ * error:
157
+ * code: 404
158
+ * message: Not found
159
+ * """
160
+ *
161
+ */
162
+ Given('the YAML response content is the following:', async function (docString) {
163
+ requireYaml();
164
+ this._rawYamlResponse = docString;
165
+ this._yamlDocs = YAML.loadAll(docString);
166
+ this._yaml = this._yamlDocs[0];
167
+ this._yamlDocIndex = 0;
168
+ });
169
+
170
+ /**
171
+ * Switch the active document for subsequent assertions. Index is 1-based to
172
+ * match how Helm / `kubectl get -o yaml` users describe documents.
173
+ *
174
+ * Example #1: Given the active YAML document is 1
175
+ * Example #2: Given the active YAML document is 2
176
+ * Example #3: And the active YAML document is 3
177
+ * Example #4: Given the active YAML document is 1
178
+ * Then the YAML element "/kind" should be equal to "ConfigMap"
179
+ * Example #5: Given the active YAML document is 2
180
+ * Then the YAML element "/kind" should be equal to "Service"
181
+ *
182
+ */
183
+ Given('the active YAML document is {int}', function (n) {
184
+ if (!this._yamlDocs) throw new Error('No YAML response has been set.');
185
+ const idx = n - 1;
186
+ if (idx < 0 || idx >= this._yamlDocs.length) {
187
+ throw new Error(`Document ${n} out of range (have ${this._yamlDocs.length}).`);
188
+ }
189
+ this._yamlDocIndex = idx;
190
+ this._yaml = this._yamlDocs[idx];
191
+ });
192
+
193
+ /**
194
+ * Assert the multi-document stream has exactly N documents.
195
+ *
196
+ * Example #1: Then the YAML response should have 1 document
197
+ * Example #2: Then the YAML response should have 2 documents
198
+ * Example #3: And the YAML response should have 5 documents
199
+ * Example #4: Then the YAML response should have 0 documents
200
+ * Example #5: Then the YAML response should have 10 documents
201
+ *
202
+ */
203
+ Then('the YAML response should have {int} document(s)', function (n) {
204
+ ensureLoaded(this);
205
+ const have = (this._yamlDocs || []).length;
206
+ assert.strictEqual(have, n, `Expected ${n} YAML documents, got ${have}.`);
207
+ });
208
+
209
+ // ---------------------------------------------------------------------------
210
+ // Format / well-formedness
211
+ // ---------------------------------------------------------------------------
212
+
213
+ /**
214
+ * Assert the loaded response parses as YAML.
215
+ *
216
+ * Example #1: Then the response should be in YAML format
217
+ * Example #2: Given the YAML response content from the file "openapi.yaml"
218
+ * Then the response should be in YAML format
219
+ * Example #3: And the response should be in YAML format
220
+ * Example #4: Given the YAML response content is the following:
221
+ * """
222
+ * key: value
223
+ * """
224
+ * Then the response should be in YAML format
225
+ * Example #5: Then the response should be in YAML format
226
+ * And the YAML element "/key" should exist
227
+ *
228
+ */
229
+ Then('the response should be in YAML format', async function () {
230
+ requireYaml();
231
+ assert.ok(this._rawYamlResponse, 'No YAML response content set.');
232
+ try { YAML.loadAll(this._rawYamlResponse); }
233
+ catch (e) { assert.fail(`Response is not valid YAML: ${e.message}`); }
234
+ });
235
+
236
+ /**
237
+ * Assert the loaded response is NOT valid YAML.
238
+ *
239
+ * Example #1: Then the response should not be in YAML format
240
+ * Example #2: Given the YAML response content is the following:
241
+ * """
242
+ * <not> yaml </not>
243
+ * """
244
+ * Then the response should not be in YAML format
245
+ * Example #3: And the response should not be in YAML format
246
+ * Example #4: Given the YAML response content is the following:
247
+ * """
248
+ * key: : :
249
+ * """
250
+ * Then the response should not be in YAML format
251
+ * Example #5: Then the response should not be in YAML format
252
+ * And I print last YAML response
253
+ *
254
+ */
255
+ Then('the response should not be in YAML format', async function () {
256
+ if (!this._rawYamlResponse || !YAML) return;
257
+ try { YAML.loadAll(this._rawYamlResponse); }
258
+ catch (e) { return; /* expected */ }
259
+ });
260
+
261
+ /**
262
+ * Assert the YAML has no duplicate keys at any level. Uses js-yaml's
263
+ * `onWarning` hook (duplicates raise warnings under default schema).
264
+ *
265
+ * Example #1: Then the YAML should have no duplicate keys
266
+ * Example #2: Given the YAML response content is the following:
267
+ * """
268
+ * name: A
269
+ * version: 1
270
+ * """
271
+ * Then the YAML should have no duplicate keys
272
+ * Example #3: And the YAML should have no duplicate keys
273
+ * Example #4: Then the YAML should have no duplicate keys
274
+ * And the YAML element "/name" should be equal to "A"
275
+ * Example #5: Then the YAML should have no duplicate keys
276
+ *
277
+ */
278
+ Then('the YAML should have no duplicate keys', function () {
279
+ requireYaml();
280
+ assert.ok(this._rawYamlResponse, 'No YAML response content set.');
281
+ const warnings = [];
282
+ YAML.loadAll(this._rawYamlResponse, undefined, { onWarning: (w) => warnings.push(w.message || String(w)) });
283
+ const dupes = warnings.filter((m) => /duplicat/i.test(m));
284
+ assert.strictEqual(dupes.length, 0, `Duplicate keys found:\n ${dupes.join('\n ')}`);
285
+ });
286
+
287
+ // ---------------------------------------------------------------------------
288
+ // Existence + equality + contains (path-based)
289
+ // ---------------------------------------------------------------------------
290
+
291
+ /**
292
+ * Assert at least one YAML node matches a path.
293
+ *
294
+ * Example #1: Then the YAML element "/name" should exist
295
+ * Example #2: Then the YAML element "/items/0/title" should exist
296
+ * Example #3: And the YAML element "/error/code" should exist
297
+ * Example #4: Then the YAML element "/spec/replicas" should exist
298
+ * Example #5: Then the YAML element "/users/2/email" should exist
299
+ *
300
+ */
301
+ Then('the YAML element {string} should exist', function (p) {
302
+ const doc = activeDoc(this); ensureLoaded(this);
303
+ assert.ok(evalPath(doc, p).length > 0, `YAML element "${p}" not found.`);
304
+ });
305
+
306
+ /**
307
+ * Assert NO YAML node matches a path.
308
+ *
309
+ * Example #1: Then the YAML element "/missing" should not exist
310
+ * Example #2: Then the YAML element "/items/100" should not exist
311
+ * Example #3: And the YAML element "/legacy/field" should not exist
312
+ * Example #4: Then the YAML element "/spec/internal" should not exist
313
+ * Example #5: Then the YAML element "/error/refund" should not exist
314
+ *
315
+ */
316
+ Then('the YAML element {string} should not exist', function (p) {
317
+ const doc = activeDoc(this); ensureLoaded(this);
318
+ assert.strictEqual(evalPath(doc, p).length, 0, `YAML element "${p}" should not exist.`);
319
+ });
320
+
321
+ /**
322
+ * Assert a YAML node's scalar value equals an expected value.
323
+ *
324
+ * Example #1: Then the YAML element "/name" should be equal to "example"
325
+ * Example #2: Then the YAML element "/version" should be equal to "2.5.2"
326
+ * Example #3: And the YAML element "/items/0/title" should be equal to "Hello"
327
+ * Example #4: Then the YAML element "/error/code" should be equal to "404"
328
+ * Example #5: Then the YAML element "/status" should be equal to "ok"
329
+ *
330
+ */
331
+ Then('the YAML element {string} should be equal to {string}', function (p, text) {
332
+ const doc = activeDoc(this); ensureLoaded(this);
333
+ const nodes = evalPath(doc, p);
334
+ assert.ok(nodes.length > 0, `YAML element "${p}" not found.`);
335
+ assert.strictEqual(nodeText(nodes[0]), text);
336
+ });
337
+
338
+ /**
339
+ * Assert a YAML node's scalar value is NOT equal to an expected value.
340
+ *
341
+ * Example #1: Then the YAML element "/name" should not be equal to "Other"
342
+ * Example #2: Then the YAML element "/version" should not be equal to "1.0.0"
343
+ * Example #3: And the YAML element "/items/0/title" should not be equal to "Bye"
344
+ * Example #4: Then the YAML element "/error/code" should not be equal to "200"
345
+ * Example #5: Then the YAML element "/status" should not be equal to "fail"
346
+ *
347
+ */
348
+ Then('the YAML element {string} should not be equal to {string}', function (p, text) {
349
+ const doc = activeDoc(this); ensureLoaded(this);
350
+ const nodes = evalPath(doc, p);
351
+ if (nodes.length === 0) return;
352
+ assert.notStrictEqual(nodeText(nodes[0]), text);
353
+ });
354
+
355
+ /**
356
+ * Assert a YAML node's serialised value contains a substring.
357
+ *
358
+ * Example #1: Then the YAML element "/name" should contain "Web"
359
+ * Example #2: Then the YAML element "/items/0/title" should contain "Hello"
360
+ * Example #3: And the YAML element "/spec" should contain "replicas"
361
+ * Example #4: Then the YAML element "/error/message" should contain "Not"
362
+ * Example #5: Then the YAML element "/status" should contain "ok"
363
+ *
364
+ */
365
+ Then('the YAML element {string} should contain {string}', function (p, text) {
366
+ const doc = activeDoc(this); ensureLoaded(this);
367
+ const nodes = evalPath(doc, p);
368
+ assert.ok(nodes.length > 0, `YAML element "${p}" not found.`);
369
+ assert.ok(nodeText(nodes[0]).indexOf(text) !== -1);
370
+ });
371
+
372
+ /**
373
+ * Assert a YAML node's serialised value does NOT contain a substring.
374
+ *
375
+ * Example #1: Then the YAML element "/name" should not contain "Error"
376
+ * Example #2: Then the YAML element "/items/0/title" should not contain "fail"
377
+ * Example #3: And the YAML element "/spec" should not contain "deprecated"
378
+ * Example #4: Then the YAML element "/error/message" should not contain "OK"
379
+ * Example #5: Then the YAML element "/status" should not contain "fatal"
380
+ *
381
+ */
382
+ Then('the YAML element {string} should not contain {string}', function (p, text) {
383
+ const doc = activeDoc(this); ensureLoaded(this);
384
+ const nodes = evalPath(doc, p);
385
+ if (nodes.length === 0) return;
386
+ assert.ok(nodeText(nodes[0]).indexOf(text) === -1);
387
+ });
388
+
389
+ // ---------------------------------------------------------------------------
390
+ // Attribute (direct child key) variants — kept verbatim from prior version.
391
+ // ---------------------------------------------------------------------------
392
+
393
+ /**
394
+ * Assert a YAML node has a direct child key.
395
+ *
396
+ * Example #1: Then the YAML attribute "id" on element "/items/0" should exist
397
+ * Example #2: Then the YAML attribute "kind" on element "/" should exist
398
+ * Example #3: And the YAML attribute "code" on element "/error" should exist
399
+ * Example #4: Then the YAML attribute "replicas" on element "/spec" should exist
400
+ * Example #5: Then the YAML attribute "email" on element "/users/0" should exist
401
+ *
402
+ */
403
+ Then('the YAML attribute {string} on element {string} should exist', function (attr, p) {
404
+ const doc = activeDoc(this); ensureLoaded(this);
405
+ const nodes = evalPath(doc, p);
406
+ assert.ok(nodes.length > 0, `YAML element "${p}" not found.`);
407
+ assert.ok(nodeHasAttr(nodes[0], attr), `Key "${attr}" not present on "${p}".`);
408
+ });
409
+
410
+ /**
411
+ * Assert a YAML node does NOT have a direct child key.
412
+ *
413
+ * Example #1: Then the YAML attribute "deprecated" on element "/items/0" should not exist
414
+ * Example #2: Then the YAML attribute "secret" on element "/" should not exist
415
+ * Example #3: And the YAML attribute "internal" on element "/spec" should not exist
416
+ * Example #4: Then the YAML attribute "private" on element "/error" should not exist
417
+ * Example #5: Then the YAML attribute "_legacy" on element "/users/0" should not exist
418
+ *
419
+ */
420
+ Then('the YAML attribute {string} on element {string} should not exist', function (attr, p) {
421
+ const doc = activeDoc(this); ensureLoaded(this);
422
+ const nodes = evalPath(doc, p);
423
+ if (nodes.length === 0) return;
424
+ assert.ok(!nodeHasAttr(nodes[0], attr), `Key "${attr}" should not exist on "${p}".`);
425
+ });
426
+
427
+ /**
428
+ * Assert a YAML child key's value equals an expected value.
429
+ *
430
+ * Example #1: Then the YAML attribute "id" on element "/items/0" should be equal to "1"
431
+ * Example #2: Then the YAML attribute "kind" on element "/" should be equal to "ConfigMap"
432
+ * Example #3: And the YAML attribute "code" on element "/error" should be equal to "404"
433
+ * Example #4: Then the YAML attribute "replicas" on element "/spec" should be equal to "3"
434
+ * Example #5: Then the YAML attribute "version" on element "/" should be equal to "v1"
435
+ *
436
+ */
437
+ Then('the YAML attribute {string} on element {string} should be equal to {string}', function (attr, p, text) {
438
+ const doc = activeDoc(this); ensureLoaded(this);
439
+ const nodes = evalPath(doc, p);
440
+ assert.ok(nodes.length > 0, `YAML element "${p}" not found.`);
441
+ assert.strictEqual(nodeAttr(nodes[0], attr), text);
442
+ });
443
+
444
+ /**
445
+ * Assert a YAML child key's value is NOT equal to an expected value.
446
+ *
447
+ * Example #1: Then the YAML attribute "id" on element "/items/0" should not be equal to "0"
448
+ * Example #2: Then the YAML attribute "kind" on element "/" should not be equal to "Secret"
449
+ * Example #3: And the YAML attribute "code" on element "/error" should not be equal to "200"
450
+ * Example #4: Then the YAML attribute "replicas" on element "/spec" should not be equal to "0"
451
+ * Example #5: Then the YAML attribute "version" on element "/" should not be equal to "v0"
452
+ *
453
+ */
454
+ Then('the YAML attribute {string} on element {string} should not be equal to {string}', function (attr, p, text) {
455
+ const doc = activeDoc(this); ensureLoaded(this);
456
+ const nodes = evalPath(doc, p);
457
+ if (nodes.length === 0) return;
458
+ assert.notStrictEqual(nodeAttr(nodes[0], attr), text);
459
+ });
460
+
461
+ /**
462
+ * Assert a YAML child key's serialised value contains a substring.
463
+ *
464
+ * Example #1: Then the YAML attribute "id" on element "/items/0" should contain "abc"
465
+ * Example #2: Then the YAML attribute "image" on element "/spec" should contain "nginx"
466
+ * Example #3: And the YAML attribute "kind" on element "/" should contain "Map"
467
+ * Example #4: Then the YAML attribute "version" on element "/" should contain "v"
468
+ * Example #5: Then the YAML attribute "code" on element "/error" should contain "4"
469
+ *
470
+ */
471
+ Then('the YAML attribute {string} on element {string} should contain {string}', function (attr, p, text) {
472
+ const doc = activeDoc(this); ensureLoaded(this);
473
+ const nodes = evalPath(doc, p);
474
+ assert.ok(nodes.length > 0, `YAML element "${p}" not found.`);
475
+ assert.ok((nodeAttr(nodes[0], attr) || '').indexOf(text) !== -1);
476
+ });
477
+
478
+ /**
479
+ * Assert a YAML child key's serialised value does NOT contain a substring.
480
+ *
481
+ * Example #1: Then the YAML attribute "id" on element "/items/0" should not contain "old"
482
+ * Example #2: Then the YAML attribute "image" on element "/spec" should not contain "alpine"
483
+ * Example #3: And the YAML attribute "kind" on element "/" should not contain "Secret"
484
+ * Example #4: Then the YAML attribute "version" on element "/" should not contain "alpha"
485
+ * Example #5: Then the YAML attribute "code" on element "/error" should not contain "5"
486
+ *
487
+ */
488
+ Then('the YAML attribute {string} on element {string} should not contain {string}', function (attr, p, text) {
489
+ const doc = activeDoc(this); ensureLoaded(this);
490
+ const nodes = evalPath(doc, p);
491
+ if (nodes.length === 0) return;
492
+ assert.ok((nodeAttr(nodes[0], attr) || '').indexOf(text) === -1);
493
+ });
494
+
495
+ /**
496
+ * Assert a YAML sequence / mapping at a path has exactly N entries.
497
+ *
498
+ * Example #1: Then the YAML element "/items" should have 5 elements
499
+ * Example #2: Then the YAML element "/users" should have 3 elements
500
+ * Example #3: And the YAML element "/spec/containers" should have 1 element
501
+ * Example #4: Then the YAML element "/errors" should have 0 elements
502
+ * Example #5: Then the YAML element "/feed/entries" should have 10 elements
503
+ *
504
+ */
505
+ Then('the YAML element {string} should have {int} element(s)', function (p, count) {
506
+ const doc = activeDoc(this); ensureLoaded(this);
507
+ const nodes = evalPath(doc, p);
508
+ const node = nodes[0];
509
+ const len = Array.isArray(node) ? node.length : (node && typeof node === 'object' ? Object.keys(node).length : 0);
510
+ assert.strictEqual(len, count);
511
+ });
512
+
513
+ // ---------------------------------------------------------------------------
514
+ // Type-of assertions
515
+ // ---------------------------------------------------------------------------
516
+
517
+ /**
518
+ * Assert a YAML node's type. Accepts: string, integer, number, boolean,
519
+ * array, object, null.
520
+ *
521
+ * Example #1: Then the YAML value at "/spec/replicas" should be of type "integer"
522
+ * Example #2: Then the YAML value at "/metadata/name" should be of type "string"
523
+ * Example #3: And the YAML value at "/spec/containers" should be of type "array"
524
+ * Example #4: Then the YAML value at "/spec" should be of type "object"
525
+ * Example #5: Then the YAML value at "/spec/paused" should be of type "boolean"
526
+ *
527
+ */
528
+ Then('the YAML value at {string} should be of type {string}', function (p, expected) {
529
+ const doc = activeDoc(this); ensureLoaded(this);
530
+ const nodes = evalPath(doc, p);
531
+ assert.ok(nodes.length > 0, `YAML element "${p}" not found.`);
532
+ const got = typeOfNode(nodes[0]);
533
+ // Allow "number" to match both number and integer.
534
+ if (expected === 'number') assert.ok(got === 'number' || got === 'integer', `Expected number, got ${got}.`);
535
+ else assert.strictEqual(got, expected, `Expected ${expected}, got ${got}.`);
536
+ });
537
+
538
+ /**
539
+ * Assert a YAML node is empty: empty string, empty array, empty object, or null.
540
+ *
541
+ * Example #1: Then the YAML value at "/labels" should be empty
542
+ * Example #2: Then the YAML value at "/items" should be empty
543
+ * Example #3: And the YAML value at "/error" should be empty
544
+ * Example #4: Then the YAML value at "/notes" should be empty
545
+ * Example #5: Then the YAML value at "/status/conditions" should be empty
546
+ *
547
+ */
548
+ Then('the YAML value at {string} should be empty', function (p) {
549
+ const doc = activeDoc(this); ensureLoaded(this);
550
+ const nodes = evalPath(doc, p);
551
+ assert.ok(nodes.length > 0, `YAML element "${p}" not found.`);
552
+ const v = nodes[0];
553
+ const empty = v == null || v === '' || (Array.isArray(v) && v.length === 0)
554
+ || (typeof v === 'object' && Object.keys(v).length === 0);
555
+ assert.ok(empty, `YAML value at "${p}" is not empty.`);
556
+ });
557
+
558
+ /**
559
+ * Assert a YAML node is non-empty.
560
+ *
561
+ * Example #1: Then the YAML value at "/items" should not be empty
562
+ * Example #2: Then the YAML value at "/spec/containers" should not be empty
563
+ * Example #3: And the YAML value at "/metadata/name" should not be empty
564
+ * Example #4: Then the YAML value at "/users" should not be empty
565
+ * Example #5: Then the YAML value at "/spec/replicas" should not be empty
566
+ *
567
+ */
568
+ Then('the YAML value at {string} should not be empty', function (p) {
569
+ const doc = activeDoc(this); ensureLoaded(this);
570
+ const nodes = evalPath(doc, p);
571
+ assert.ok(nodes.length > 0, `YAML element "${p}" not found.`);
572
+ const v = nodes[0];
573
+ const empty = v == null || v === '' || (Array.isArray(v) && v.length === 0)
574
+ || (typeof v === 'object' && Object.keys(v).length === 0);
575
+ assert.ok(!empty, `YAML value at "${p}" is empty.`);
576
+ });
577
+
578
+ // ---------------------------------------------------------------------------
579
+ // Numeric comparisons
580
+ // ---------------------------------------------------------------------------
581
+
582
+ function numAt(doc, p) {
583
+ const nodes = evalPath(doc, p);
584
+ if (nodes.length === 0) throw new Error(`YAML element "${p}" not found.`);
585
+ const v = nodes[0];
586
+ const n = typeof v === 'number' ? v : Number(v);
587
+ if (!Number.isFinite(n)) throw new Error(`YAML value at "${p}" is not numeric: ${v}`);
588
+ return n;
589
+ }
590
+
591
+ /**
592
+ * Assert a numeric YAML node is greater than a value.
593
+ *
594
+ * Example #1: Then the YAML value at "/spec/replicas" should be greater than 0
595
+ * Example #2: Then the YAML value at "/timeout" should be greater than 5
596
+ * Example #3: And the YAML value at "/spec/minReadySeconds" should be greater than 0
597
+ * Example #4: Then the YAML value at "/limits/cpu" should be greater than 100
598
+ * Example #5: Then the YAML value at "/version/major" should be greater than 1
599
+ *
600
+ */
601
+ Then('the YAML value at {string} should be greater than {float}', function (p, n) {
602
+ const doc = activeDoc(this); ensureLoaded(this);
603
+ assert.ok(numAt(doc, p) > n);
604
+ });
605
+
606
+ /**
607
+ * Assert a numeric YAML node is greater than or equal to a value.
608
+ *
609
+ * Example #1: Then the YAML value at "/spec/replicas" should be greater than or equal to 1
610
+ * Example #2: Then the YAML value at "/retries" should be greater than or equal to 0
611
+ * Example #3: And the YAML value at "/timeout" should be greater than or equal to 30
612
+ * Example #4: Then the YAML value at "/version/major" should be greater than or equal to 2
613
+ * Example #5: Then the YAML value at "/limits/cpu" should be greater than or equal to 250
614
+ *
615
+ */
616
+ Then('the YAML value at {string} should be greater than or equal to {float}', function (p, n) {
617
+ const doc = activeDoc(this); ensureLoaded(this);
618
+ assert.ok(numAt(doc, p) >= n);
619
+ });
620
+
621
+ /**
622
+ * Assert a numeric YAML node is less than a value.
623
+ *
624
+ * Example #1: Then the YAML value at "/spec/replicas" should be less than 100
625
+ * Example #2: Then the YAML value at "/error/code" should be less than 500
626
+ * Example #3: And the YAML value at "/timeout" should be less than 60
627
+ * Example #4: Then the YAML value at "/version/minor" should be less than 10
628
+ * Example #5: Then the YAML value at "/cost" should be less than 1000
629
+ *
630
+ */
631
+ Then('the YAML value at {string} should be less than {float}', function (p, n) {
632
+ const doc = activeDoc(this); ensureLoaded(this);
633
+ assert.ok(numAt(doc, p) < n);
634
+ });
635
+
636
+ /**
637
+ * Assert a numeric YAML node is less than or equal to a value.
638
+ *
639
+ * Example #1: Then the YAML value at "/spec/replicas" should be less than or equal to 10
640
+ * Example #2: Then the YAML value at "/retries" should be less than or equal to 5
641
+ * Example #3: And the YAML value at "/timeout" should be less than or equal to 60
642
+ * Example #4: Then the YAML value at "/error/code" should be less than or equal to 599
643
+ * Example #5: Then the YAML value at "/version/major" should be less than or equal to 3
644
+ *
645
+ */
646
+ Then('the YAML value at {string} should be less than or equal to {float}', function (p, n) {
647
+ const doc = activeDoc(this); ensureLoaded(this);
648
+ assert.ok(numAt(doc, p) <= n);
649
+ });
650
+
651
+ /**
652
+ * Assert a numeric YAML node falls within an inclusive range.
653
+ *
654
+ * Example #1: Then the YAML value at "/spec/replicas" should be between 1 and 10
655
+ * Example #2: Then the YAML value at "/timeout" should be between 5 and 60
656
+ * Example #3: And the YAML value at "/error/code" should be between 400 and 499
657
+ * Example #4: Then the YAML value at "/cpu" should be between 100 and 1000
658
+ * Example #5: Then the YAML value at "/version/major" should be between 2 and 5
659
+ *
660
+ */
661
+ Then('the YAML value at {string} should be between {float} and {float}', function (p, lo, hi) {
662
+ const doc = activeDoc(this); ensureLoaded(this);
663
+ const v = numAt(doc, p);
664
+ assert.ok(v >= lo && v <= hi, `Value ${v} not in [${lo}, ${hi}].`);
665
+ });
666
+
667
+ // ---------------------------------------------------------------------------
668
+ // Array operations
669
+ // ---------------------------------------------------------------------------
670
+
671
+ function arrayAt(doc, p) {
672
+ const nodes = evalPath(doc, p);
673
+ if (nodes.length === 0) throw new Error(`YAML element "${p}" not found.`);
674
+ const v = nodes[0];
675
+ if (!Array.isArray(v)) throw new Error(`YAML value at "${p}" is not an array.`);
676
+ return v;
677
+ }
678
+
679
+ /**
680
+ * Assert an array contains an item where a sub-key has the expected value.
681
+ * Sub-key path is relative to each item; supports the same `/a/b[0]` syntax.
682
+ *
683
+ * Example #1: Then the YAML array at "/spec/containers" should contain an item where "/name" is "nginx"
684
+ * Example #2: Then the YAML array at "/items" should contain an item where "/kind" is "Service"
685
+ * Example #3: And the YAML array at "/users" should contain an item where "/email" is "alice@example.com"
686
+ * Example #4: Then the YAML array at "/rules" should contain an item where "/host" is "example.com"
687
+ * Example #5: Then the YAML array at "/spec/ports" should contain an item where "/port" is "443"
688
+ *
689
+ */
690
+ Then('the YAML array at {string} should contain an item where {string} is {string}', function (p, sub, value) {
691
+ const doc = activeDoc(this); ensureLoaded(this);
692
+ const arr = arrayAt(doc, p);
693
+ const found = arr.some((item) => {
694
+ const got = evalPath(item, sub)[0];
695
+ return nodeText(got) === value;
696
+ });
697
+ assert.ok(found, `Array at "${p}" has no item where "${sub}" is "${value}".`);
698
+ });
699
+
700
+ /**
701
+ * Assert NO item in an array has a sub-key matching a value.
702
+ *
703
+ * Example #1: Then the YAML array at "/spec/containers" should contain no item where "/image" is "alpine:latest"
704
+ * Example #2: Then the YAML array at "/users" should contain no item where "/role" is "anonymous"
705
+ * Example #3: And the YAML array at "/rules" should contain no item where "/host" is "deprecated.example.com"
706
+ * Example #4: Then the YAML array at "/spec/env" should contain no item where "/name" is "DEBUG"
707
+ * Example #5: Then the YAML array at "/items" should contain no item where "/status" is "failed"
708
+ *
709
+ */
710
+ Then('the YAML array at {string} should contain no item where {string} is {string}', function (p, sub, value) {
711
+ const doc = activeDoc(this); ensureLoaded(this);
712
+ const arr = arrayAt(doc, p);
713
+ const found = arr.some((item) => nodeText(evalPath(item, sub)[0]) === value);
714
+ assert.ok(!found, `Array at "${p}" unexpectedly has item where "${sub}" is "${value}".`);
715
+ });
716
+
717
+ /**
718
+ * Assert every item in an array has a non-null sub-key.
719
+ *
720
+ * Example #1: Then every item in "/spec/containers" should have key "image"
721
+ * Example #2: Then every item in "/users" should have key "email"
722
+ * Example #3: And every item in "/spec/ports" should have key "port"
723
+ * Example #4: Then every item in "/items" should have key "kind"
724
+ * Example #5: Then every item in "/spec/rules" should have key "host"
725
+ *
726
+ */
727
+ Then('every item in {string} should have key {string}', function (p, key) {
728
+ const doc = activeDoc(this); ensureLoaded(this);
729
+ const arr = arrayAt(doc, p);
730
+ const missing = arr.findIndex((item) => !nodeHasAttr(item, key));
731
+ assert.strictEqual(missing, -1, `Item at index ${missing} in "${p}" is missing key "${key}".`);
732
+ });
733
+
734
+ // ---------------------------------------------------------------------------
735
+ // Key-set assertions
736
+ // ---------------------------------------------------------------------------
737
+
738
+ function keysAt(doc, p) {
739
+ const nodes = evalPath(doc, p);
740
+ if (nodes.length === 0) throw new Error(`YAML element "${p}" not found.`);
741
+ const v = nodes[0];
742
+ if (typeof v !== 'object' || Array.isArray(v) || v === null) {
743
+ throw new Error(`YAML value at "${p}" is not a mapping.`);
744
+ }
745
+ return Object.keys(v);
746
+ }
747
+
748
+ /**
749
+ * Assert the keys at a path exactly match a comma-separated list (no extras).
750
+ *
751
+ * Example #1: Then the YAML keys at "/metadata" should be exactly "name, namespace, labels"
752
+ * Example #2: Then the YAML keys at "/spec" should be exactly "replicas, selector, template"
753
+ * Example #3: And the YAML keys at "/error" should be exactly "code, message"
754
+ * Example #4: Then the YAML keys at "/" should be exactly "apiVersion, kind, metadata, spec"
755
+ * Example #5: Then the YAML keys at "/users/0" should be exactly "id, name, email"
756
+ *
757
+ */
758
+ Then('the YAML keys at {string} should be exactly {string}', function (p, csv) {
759
+ const doc = activeDoc(this); ensureLoaded(this);
760
+ const got = keysAt(doc, p).sort();
761
+ const want = csv.split(',').map((s) => s.trim()).filter(Boolean).sort();
762
+ assert.deepStrictEqual(got, want);
763
+ });
764
+
765
+ /**
766
+ * Assert every required key is present at a path (extras allowed).
767
+ *
768
+ * Example #1: Then the YAML at "/metadata" should have keys "name, namespace"
769
+ * Example #2: Then the YAML at "/spec" should have keys "replicas, selector"
770
+ * Example #3: And the YAML at "/" should have keys "apiVersion, kind"
771
+ * Example #4: Then the YAML at "/error" should have keys "code, message"
772
+ * Example #5: Then the YAML at "/users/0" should have keys "id, email"
773
+ *
774
+ */
775
+ Then('the YAML at {string} should have keys {string}', function (p, csv) {
776
+ const doc = activeDoc(this); ensureLoaded(this);
777
+ const got = new Set(keysAt(doc, p));
778
+ const want = csv.split(',').map((s) => s.trim()).filter(Boolean);
779
+ for (const k of want) assert.ok(got.has(k), `Missing key "${k}" at "${p}".`);
780
+ });
781
+
782
+ // ---------------------------------------------------------------------------
783
+ // JSON Schema validation
784
+ // ---------------------------------------------------------------------------
785
+
786
+ /**
787
+ * Validate the active YAML document against a JSON Schema file. Bundles
788
+ * `ajv-formats` so schemas using `format: date-time`, `email`, `uri`, etc.
789
+ * work out of the box.
790
+ *
791
+ * Example #1: Then the YAML should match JSON Schema "schemas/deployment.json"
792
+ * Example #2: Then the YAML should match JSON Schema "tests/schemas/openapi-3.1.json"
793
+ * Example #3: And the YAML should match JSON Schema "schemas/configmap.json"
794
+ * Example #4: Then the YAML should match JSON Schema "schemas/github-workflow.json"
795
+ * Example #5: Then the YAML should match JSON Schema "/abs/path/to/schema.json"
796
+ *
797
+ */
798
+ Then('the YAML should match JSON Schema {string}', function (schemaFile) {
799
+ if (!Ajv) throw new Error('Schema validation requires ajv. Install with: npm i ajv ajv-formats');
800
+ const doc = activeDoc(this); ensureLoaded(this);
801
+ const p = path.isAbsolute(schemaFile) ? schemaFile : path.join(this.assetsFolder || './tests/assets', schemaFile);
802
+ const schema = JSON.parse(fs.readFileSync(p, 'utf-8'));
803
+ const ajv = new Ajv({ allErrors: true, strict: false });
804
+ if (addFormats) addFormats(ajv);
805
+ const validate = ajv.compile(schema);
806
+ const ok = validate(doc);
807
+ assert.ok(ok, `YAML failed schema validation:\n ${(validate.errors || []).map((e) => e.instancePath + ' ' + e.message).join('\n ')}`);
808
+ });
809
+
810
+ // ---------------------------------------------------------------------------
811
+ // Diff vs expected
812
+ // ---------------------------------------------------------------------------
813
+
814
+ /**
815
+ * Assert the active YAML document equals the contents of an expected file,
816
+ * after removing the listed JSON Pointer paths from both sides. Common
817
+ * use: ignoring volatile fields like `metadata.resourceVersion` or
818
+ * `status` when diffing Kubernetes manifests.
819
+ *
820
+ * Example #1: Then the YAML should equal the file "expected.yaml" ignoring keys "/metadata/resourceVersion"
821
+ * Example #2: Then the YAML should equal the file "expected.yaml" ignoring keys "/status, /metadata/uid"
822
+ * Example #3: And the YAML should equal the file "golden.yaml" ignoring keys "/metadata/creationTimestamp"
823
+ * Example #4: Then the YAML should equal the file "expected.yml" ignoring keys ""
824
+ * Example #5: Then the YAML should equal the file "tests/golden/deploy.yaml" ignoring keys "/status, /metadata/uid, /metadata/resourceVersion"
825
+ *
826
+ */
827
+ Then('the YAML should equal the file {string} ignoring keys {string}', function (file, ignoreCsv) {
828
+ requireYaml();
829
+ const doc = activeDoc(this); ensureLoaded(this);
830
+ const p = path.isAbsolute(file) ? file : path.join(this.assetsFolder || './tests/assets', file);
831
+ const expected = YAML.load(fs.readFileSync(p, 'utf-8'));
832
+ const ignore = ignoreCsv.split(',').map((s) => s.trim()).filter(Boolean);
833
+ const stripAt = (root, ptr) => {
834
+ const parts = ptr.split('/').filter(Boolean);
835
+ if (parts.length === 0) return;
836
+ const last = parts.pop();
837
+ let cur = root;
838
+ for (const part of parts) {
839
+ if (cur && typeof cur === 'object' && part in cur) cur = cur[part];
840
+ else return;
841
+ }
842
+ if (cur && typeof cur === 'object') delete cur[last];
843
+ };
844
+ const cloneA = JSON.parse(JSON.stringify(doc));
845
+ const cloneB = JSON.parse(JSON.stringify(expected));
846
+ for (const ptr of ignore) { stripAt(cloneA, ptr); stripAt(cloneB, ptr); }
847
+ assert.deepStrictEqual(cloneA, cloneB);
848
+ });
849
+
850
+ // ---------------------------------------------------------------------------
851
+ // Namespace + debug
852
+ // ---------------------------------------------------------------------------
853
+
854
+ /**
855
+ * Assert the YAML document declares a namespace value (mirrors xml.steps.js).
856
+ * Checks top-level scalar values and falls back to a raw-text scan.
857
+ *
858
+ * Example #1: Then the YAML should use the namespace "v1"
859
+ * Example #2: Then the YAML should use the namespace "apps/v1"
860
+ * Example #3: And the YAML should use the namespace "kustomize.config.k8s.io/v1beta1"
861
+ * Example #4: Then the YAML should use the namespace "argoproj.io/v1alpha1"
862
+ * Example #5: Then the YAML should use the namespace "openapi: 3.0.3"
863
+ *
864
+ */
865
+ Then('the YAML should use the namespace {string}', function (ns) {
866
+ const doc = activeDoc(this); ensureLoaded(this);
867
+ if (doc && typeof doc === 'object') {
868
+ const values = Object.values(doc).map((v) => (v == null ? '' : String(v)));
869
+ if (values.includes(ns)) return;
870
+ }
871
+ assert.ok((this._rawYamlResponse || '').indexOf(ns) !== -1, `Namespace "${ns}" not declared.`);
872
+ });
873
+
874
+ /**
875
+ * Assert the YAML document does NOT declare a namespace value.
876
+ *
877
+ * Example #1: Then the YAML should not use the namespace "v0"
878
+ * Example #2: Then the YAML should not use the namespace "internal/v1"
879
+ * Example #3: And the YAML should not use the namespace "legacy"
880
+ * Example #4: Then the YAML should not use the namespace "v0alpha"
881
+ * Example #5: Then the YAML should not use the namespace "deprecated"
882
+ *
883
+ */
884
+ Then('the YAML should not use the namespace {string}', function (ns) {
885
+ const doc = activeDoc(this); ensureLoaded(this);
886
+ if (doc && typeof doc === 'object') {
887
+ const values = Object.values(doc).map((v) => (v == null ? '' : String(v)));
888
+ assert.ok(!values.includes(ns), `Namespace "${ns}" should not be declared.`);
889
+ return;
890
+ }
891
+ assert.ok((this._rawYamlResponse || '').indexOf(ns) === -1, `Namespace "${ns}" should not be declared.`);
892
+ });
893
+
894
+ /**
895
+ * Print the most recently set raw YAML response to stdout (debug aid).
896
+ *
897
+ * Example #1: When I print last YAML response
898
+ * Example #2: When we print last YAML response
899
+ * Example #3: And I print last YAML response
900
+ * Example #4: Given the YAML response content is the following:
901
+ * """
902
+ * key: value
903
+ * """
904
+ * When I print last YAML response
905
+ * Example #5: When we send a REST "GET" request to "/api/config"
906
+ * And we print last YAML response
907
+ *
908
+ */
909
+ When(/^(I |we )*print last YAML response$/, async function () {
910
+ console.log(this._rawYamlResponse || '(no response)');
911
+ });