webship-js 2.0.11 → 2.0.12

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 (168) hide show
  1. package/.circleci/config.yml +10 -1
  2. package/.drone.yml +7 -7
  3. package/.github/workflows/github-actions.yml +45 -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 +44 -8
  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/choice-controls.html +29 -0
  45. package/examples/datetime-fields.html +52 -0
  46. package/examples/element-selector-hint.html +16 -0
  47. package/examples/field-states.html +27 -0
  48. package/examples/fill-in-empty.html +26 -0
  49. package/examples/fill-unreachable.html +27 -0
  50. package/examples/iframe-inner.html +20 -0
  51. package/examples/iframe-nested.html +16 -0
  52. package/examples/iframe-outer.html +15 -0
  53. package/examples/multi-value-fields.html +54 -0
  54. package/examples/registered-names.html +15 -0
  55. package/examples/select-by-label.html +33 -0
  56. package/examples/settle-budget.html +21 -0
  57. package/examples/sorted-tables.html +38 -0
  58. package/examples/text-matching.html +48 -0
  59. package/examples/text-order.html +25 -0
  60. package/examples/touch.html +22 -0
  61. package/examples/viewport-top.html +36 -0
  62. package/package.json +16 -1
  63. package/playwright.config.ts +3 -1
  64. package/tests/check-api-launch-url.js +106 -0
  65. package/tests/check-assets.js +103 -0
  66. package/tests/check-attachments.js +105 -0
  67. package/tests/check-breakpoints.js +117 -0
  68. package/tests/check-clock.js +143 -0
  69. package/tests/check-config.js +90 -0
  70. package/tests/check-context.js +215 -0
  71. package/tests/check-dry-run.js +104 -0
  72. package/tests/check-examples.js +10 -4
  73. package/tests/check-exit-report.js +141 -0
  74. package/tests/check-javascript-errors.js +105 -0
  75. package/tests/check-must-fail.js +5 -4
  76. package/tests/check-scaffold.js +36 -1
  77. package/tests/check-screenshots.js +117 -0
  78. package/tests/check-settle-verbs.js +137 -0
  79. package/tests/check-time-limit.js +104 -0
  80. package/tests/check-video.js +156 -0
  81. package/tests/check-world.js +167 -0
  82. package/tests/features/api-base-url.feature +25 -0
  83. package/tests/features/api-form-data.feature +18 -0
  84. package/tests/features/api-json-paths.feature +24 -0
  85. package/tests/features/api-response-contains.feature +21 -0
  86. package/tests/features/api-response-header-presence.feature +17 -0
  87. package/tests/features/api-response-header.feature +17 -0
  88. package/tests/features/api-saved-placeholders.feature +37 -0
  89. package/tests/features/api-step-definitions-individual.feature +1 -1
  90. package/tests/features/api-tables.feature +40 -0
  91. package/tests/features/breakpoints.feature +25 -0
  92. package/tests/features/choice-controls.feature +35 -0
  93. package/tests/features/complete-api-testing-examples.feature +1 -1
  94. package/tests/features/datetime-field-lookup.feature +29 -0
  95. package/tests/features/element-selector-hint.feature +14 -0
  96. package/tests/features/field-state.feature +21 -0
  97. package/tests/features/fill-in-empty-value.feature +41 -0
  98. package/tests/features/fill-reachable.feature +13 -0
  99. package/tests/features/iframe-nested.feature +43 -0
  100. package/tests/features/javascript-tolerated-errors.feature +20 -0
  101. package/tests/features/modal-open.feature +13 -0
  102. package/tests/features/multi-value-field-lookup.feature +30 -0
  103. package/tests/features/registered-names.feature +14 -0
  104. package/tests/features/select-by-label.feature +31 -0
  105. package/tests/features/selector-files.feature +14 -0
  106. package/tests/features/selectors-table-header.feature +35 -0
  107. package/tests/features/settle-budget.feature +11 -0
  108. package/tests/features/sorted-tables.feature +19 -0
  109. package/tests/features/storage-quoted-values.feature +26 -0
  110. package/tests/features/text-matching.feature +38 -0
  111. package/tests/features/text-order.feature +14 -0
  112. package/tests/features/touch.feature +21 -0
  113. package/tests/features/viewport-top.feature +13 -0
  114. package/tests/features/xml-namespaces.feature +34 -0
  115. package/tests/must-fail/api-json-paths.feature +21 -0
  116. package/tests/must-fail/api-response-contains.feature +23 -0
  117. package/tests/must-fail/api-response-header-presence.feature +17 -0
  118. package/tests/must-fail/api-response-header.feature +21 -0
  119. package/tests/must-fail/api-without-base-url.feature +11 -0
  120. package/tests/must-fail/breakpoints.feature +15 -0
  121. package/tests/must-fail/choice-controls.feature +25 -0
  122. package/tests/must-fail/clock.feature +11 -0
  123. package/tests/must-fail/datetime-field.feature +10 -0
  124. package/tests/must-fail/element-selector-hint.feature +17 -0
  125. package/tests/must-fail/field-state.feature +20 -0
  126. package/tests/must-fail/fill-field.feature +30 -0
  127. package/tests/must-fail/iframe-text.feature +17 -0
  128. package/tests/must-fail/modal-open.feature +26 -0
  129. package/tests/must-fail/multi-value-field.feature +18 -0
  130. package/tests/must-fail/registered-names.feature +25 -0
  131. package/tests/must-fail/select-list.feature +15 -0
  132. package/tests/must-fail/selector-files.feature +10 -0
  133. package/tests/must-fail/sorted-tables.feature +20 -0
  134. package/tests/must-fail/storage-before-a-page.feature +13 -0
  135. package/tests/must-fail/text-matching.feature +16 -0
  136. package/tests/must-fail/text-order.feature +15 -0
  137. package/tests/must-fail/viewport-top.feature +20 -0
  138. package/tests/must-fail/yaml-numbers.feature +48 -0
  139. package/tests/step-definitions/a11y.steps.js +24 -15
  140. package/tests/step-definitions/action.steps.js +22 -8
  141. package/tests/step-definitions/api.steps.js +349 -67
  142. package/tests/step-definitions/assertion.steps.js +100 -10
  143. package/tests/step-definitions/auth.steps.js +15 -18
  144. package/tests/step-definitions/clock.steps.js +22 -0
  145. package/tests/step-definitions/debug.steps.js +8 -0
  146. package/tests/step-definitions/dialog.steps.js +7 -0
  147. package/tests/step-definitions/element.steps.js +132 -17
  148. package/tests/step-definitions/field.steps.js +409 -96
  149. package/tests/step-definitions/form.steps.js +76 -29
  150. package/tests/step-definitions/iframe.steps.js +89 -29
  151. package/tests/step-definitions/input.steps.js +26 -7
  152. package/tests/step-definitions/javascript.steps.js +64 -22
  153. package/tests/step-definitions/modal.steps.js +79 -13
  154. package/tests/step-definitions/navigation.steps.js +14 -0
  155. package/tests/step-definitions/network.steps.js +15 -5
  156. package/tests/step-definitions/response.steps.js +6 -4
  157. package/tests/step-definitions/responsive.steps.js +26 -33
  158. package/tests/step-definitions/screenshot.steps.js +25 -8
  159. package/tests/step-definitions/scroll.steps.js +20 -0
  160. package/tests/step-definitions/selectors.steps.js +95 -48
  161. package/tests/step-definitions/storage.steps.js +38 -13
  162. package/tests/step-definitions/table.steps.js +81 -6
  163. package/tests/step-definitions/video.steps.js +52 -55
  164. package/tests/step-definitions/wait.steps.js +88 -23
  165. package/tests/step-definitions/web-first.steps.js +69 -35
  166. package/tests/step-definitions/webship.js +681 -143
  167. package/tests/step-definitions/xml.steps.js +49 -15
  168. package/tests/step-definitions/yaml.steps.js +45 -20
@@ -20,6 +20,7 @@ const { When } = require('@cucumber/cucumber');
20
20
  * Example #2: When I scroll down 800
21
21
  * Example #3: And we scroll down 500
22
22
  * Example #4: When scrolling down 1200
23
+ * Example #5: Then we scroll down 200
23
24
  *
24
25
  */
25
26
  When(/^(I scroll|we scroll|scrolling)? down(?: (\d+))?$/, async function (pronounCase, numValue) {
@@ -33,6 +34,7 @@ When(/^(I scroll|we scroll|scrolling)? down(?: (\d+))?$/, async function (pronou
33
34
  * Example #2: When I scroll up 1000
34
35
  * Example #3: And we scroll up 300
35
36
  * Example #4: When scrolling up 750
37
+ * Example #5: Then we scroll up 200
36
38
  *
37
39
  */
38
40
  When(/^(I scroll|we scroll|scrolling)? up(?: (\d+))?$/, async function (pronounCase, numValue) {
@@ -45,6 +47,8 @@ When(/^(I scroll|we scroll|scrolling)? up(?: (\d+))?$/, async function (pronounC
45
47
  * Example #1: When I scroll to top
46
48
  * Example #2: And we scroll to the top
47
49
  * Example #3: When scrolling to the top of the page
50
+ * Example #4: Then we scroll to the top of the page
51
+ * Example #5: When I scroll to the top
48
52
  *
49
53
  */
50
54
  When(/^(I scroll|we scroll|scrolling)? to( the)* top( of the page)*$/, async function (pronounCase, theCase, pageCase) {
@@ -57,6 +61,8 @@ When(/^(I scroll|we scroll|scrolling)? to( the)* top( of the page)*$/, async fun
57
61
  * Example #1: When I scroll to the bottom
58
62
  * Example #2: And we scroll to bottom
59
63
  * Example #3: When scrolling to the bottom of the page
64
+ * Example #4: Then I scroll to the bottom of the page
65
+ * Example #5: When we scroll to the bottom
60
66
  *
61
67
  */
62
68
  When(/^(I scroll|we scroll|scrolling)? to( the)* bottom( of the page)*$/, async function (pronounCase, theCase, pageCase) {
@@ -82,6 +88,8 @@ When(/^(I scroll|we scroll|scrolling)? to( the)* bottom( of the page)*$/, async
82
88
  * Example #1: When I scroll to top of "#off-canvas"
83
89
  * Example #2: And we scroll to top of "#sidebar"
84
90
  * Example #3: When scrolling to top of "#main-container"
91
+ * Example #4: When I scroll to top of ".chat-history"
92
+ * Example #5: And we scroll to top of "#results"
85
93
  *
86
94
  */
87
95
  When(/^(I scroll|we scroll|scrolling)? to top of "([^"]*)"$/, async function (pronounCase, selector) {
@@ -97,6 +105,8 @@ When(/^(I scroll|we scroll|scrolling)? to top of "([^"]*)"$/, async function (pr
97
105
  * Example #1: When I scroll to bottom of "#off-canvas"
98
106
  * Example #2: And we scroll to bottom of "#sidebar"
99
107
  * Example #3: When scrolling to bottom of "#main-container"
108
+ * Example #4: When I scroll to bottom of ".chat-history"
109
+ * Example #5: And we scroll to bottom of "#results"
100
110
  *
101
111
  */
102
112
  When(/^(I scroll|we scroll|scrolling)? to bottom of "([^"]*)"$/, async function (pronounCase, selector) {
@@ -117,6 +127,7 @@ When(/^(I scroll|we scroll|scrolling)? to bottom of "([^"]*)"$/, async function
117
127
  * Example #2: When I scroll right 1000
118
128
  * Example #3: And we scroll right 300
119
129
  * Example #4: When scrolling right 750
130
+ * Example #5: Then we scroll right 200
120
131
  *
121
132
  */
122
133
  When(/^(I scroll|we scroll|scrolling)? right(?: (\d+))?$/, async function (pronounCase, numValue) {
@@ -130,6 +141,7 @@ When(/^(I scroll|we scroll|scrolling)? right(?: (\d+))?$/, async function (prono
130
141
  * Example #2: When I scroll left 800
131
142
  * Example #3: And we scroll left 500
132
143
  * Example #4: When scrolling left 1200
144
+ * Example #5: Then we scroll left 200
133
145
  *
134
146
  */
135
147
  When(/^(I scroll|we scroll|scrolling)? left(?: (\d+))?$/, async function (pronounCase, numValue) {
@@ -142,6 +154,8 @@ When(/^(I scroll|we scroll|scrolling)? left(?: (\d+))?$/, async function (pronou
142
154
  * Example #1: When I scroll to start
143
155
  * Example #2: And we scroll to the start
144
156
  * Example #3: When scrolling to the start of the page
157
+ * Example #4: Then I scroll to the start of the page
158
+ * Example #5: When we scroll to start
145
159
  *
146
160
  */
147
161
  When(/^(I scroll|we scroll|scrolling)? to( the)* start( of the page)*$/, async function (pronounCase, theCase, pageCase) {
@@ -154,6 +168,8 @@ When(/^(I scroll|we scroll|scrolling)? to( the)* start( of the page)*$/, async f
154
168
  * Example #1: When I scroll to the end
155
169
  * Example #2: And we scroll to end
156
170
  * Example #3: When scrolling to the end of the page
171
+ * Example #4: Then I scroll to the end of the page
172
+ * Example #5: When we scroll to the end
157
173
  *
158
174
  */
159
175
  When(/^(I scroll|we scroll|scrolling)? to( the)* end( of the page)*$/, async function (pronounCase, theCase, pageCase) {
@@ -170,6 +186,8 @@ When(/^(I scroll|we scroll|scrolling)? to( the)* end( of the page)*$/, async fun
170
186
  * Example #1: When I scroll to start of "#off-canvas"
171
187
  * Example #2: And we scroll to start of "#sidebar"
172
188
  * Example #3: When scrolling to start of "#main-container"
189
+ * Example #4: When I scroll to start of ".carousel"
190
+ * Example #5: And we scroll to start of "#gallery"
173
191
  *
174
192
  */
175
193
  When(/^(I scroll|we scroll|scrolling)? to start of "([^"]*)"$/, async function (pronounCase, selector) {
@@ -182,6 +200,8 @@ When(/^(I scroll|we scroll|scrolling)? to start of "([^"]*)"$/, async function (
182
200
  * Example #1: When I scroll to end of "#off-canvas"
183
201
  * Example #2: And we scroll to end of "#sidebar"
184
202
  * Example #3: When scrolling to end of "#main-container"
203
+ * Example #4: When I scroll to end of ".carousel"
204
+ * Example #5: And we scroll to end of "#gallery"
185
205
  *
186
206
  */
187
207
  When(/^(I scroll|we scroll|scrolling)? to end of "([^"]*)"$/, async function (pronounCase, selector) {
@@ -1,6 +1,6 @@
1
1
  'use strict';
2
2
 
3
- const { friendly } = require('./webship');
3
+ const { friendly, failure, breakpoint } = require('./webship');
4
4
 
5
5
  // ---------------------------------------------------------------------------
6
6
  // Webship-JS — Selectors step definitions
@@ -20,8 +20,9 @@ const { friendly } = require('./webship');
20
20
  // 3. built-in defaults
21
21
  //
22
22
  // Supported env vars / worldParameters keys:
23
- // WEBSHIP_SELECTORS_OFFSET offset scroll offset in px, default 60
24
- // WEBSHIP_SELECTORS_BREAKPOINTS (JSON string) named breakpoints
23
+ // WEBSHIP_SELECTORS_BREAKPOINTS (JSON object) named breakpoints, merged over
24
+ // worldParameters.selectors.breakpoints (one
25
+ // registry for every step and tag: webship.js)
25
26
  //
26
27
  // Unified config block (worldParameters.selectors):
27
28
  // selectors: {
@@ -34,7 +35,6 @@ const { friendly } = require('./webship');
34
35
  // xpath: {
35
36
  // 'page title': '//h1[contains(@class,"page-title")]',
36
37
  // },
37
- // offset: 60, // scroll offset (px)
38
38
  // breakpoints: {
39
39
  // xs: { width: 375, height: 667 }, // phone portrait
40
40
  // sm: { width: 576, height: 800 }, // large phone / phablet
@@ -69,36 +69,45 @@ function parseFile(filePath) {
69
69
  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
70
70
  }
71
71
 
72
+ // Folder of the selector files when worldParameters.selectors.filesPath is not
73
+ // set: the one the scaffold writes.
74
+ const DEFAULT_FILES_PATH = './tests/selectors/';
75
+
76
+ /**
77
+ * Find a selector file of worldParameters.selectors.files or of the "add
78
+ * selectors from ... file" step. A name is looked for in the folder of
79
+ * filesPath first (auth.json), then as written from the project root
80
+ * (tests/selectors/auth.json): the first that exists wins.
81
+ *
82
+ * @param {{filesPath: string}} cfg
83
+ * @param {string} file
84
+ * @param {import('playwright').Page} [page] - Named in the failure, when there is one.
85
+ * @returns {string} The path of the file.
86
+ */
87
+ function resolveSelectorFile(cfg, file, page) {
88
+ const name = String(file || '').trim();
89
+ const tried = path.isAbsolute(name)
90
+ ? [name]
91
+ : [...new Set([path.join(cfg.filesPath || '', name), path.normalize(name)])];
92
+ const found = tried.find((candidate) => fs.existsSync(candidate));
93
+ if (found) return found;
94
+ const message = `The selector file "${name}" was not found.`;
95
+ const details = {
96
+ found: `nothing at ${tried.join(', ')}`,
97
+ hint: `name the file by its name in the selectors folder (${cfg.filesPath || DEFAULT_FILES_PATH}) or by its path from the project root.`,
98
+ };
99
+ if (page) throw failure(page, message, details);
100
+ throw friendly(`Selectors: ${message}\n Found: ${details.found}\n Hint: ${details.hint}`);
101
+ }
102
+
72
103
  // ---------------------------------------------------------------------------
73
104
  // Config
74
105
  // ---------------------------------------------------------------------------
75
- function pick(envVal, paramVal, fallback) {
76
- if (envVal !== undefined && envVal !== '') return envVal;
77
- if (paramVal !== undefined && paramVal !== '' && paramVal !== null) return paramVal;
78
- return fallback;
79
- }
80
-
81
106
  function resolveConfig(parameters) {
82
107
  const s = (parameters && parameters.selectors) || {};
83
108
 
84
- let breakpoints = s.breakpoints || {
85
- xs: { width: 375, height: 667 },
86
- sm: { width: 576, height: 800 },
87
- md: { width: 768, height: 1024 },
88
- lg: { width: 992, height: 768 },
89
- xl: { width: 1200, height: 900, default: true },
90
- xxl: { width: 1400, height: 900 },
91
- xxxl: { width: 1920, height: 1080 },
92
- };
93
-
94
- if (process.env.WEBSHIP_SELECTORS_BREAKPOINTS) {
95
- try { breakpoints = JSON.parse(process.env.WEBSHIP_SELECTORS_BREAKPOINTS); } catch { /* ignore */ }
96
- }
97
-
98
109
  return {
99
- offset: parseInt(pick(process.env.WEBSHIP_SELECTORS_OFFSET, s.offset, '60'), 10),
100
- breakpoints,
101
- filesPath: s.filesPath || '',
110
+ filesPath: s.filesPath || DEFAULT_FILES_PATH,
102
111
  files: Array.isArray(s.files) ? s.files : [],
103
112
  css: Object.assign({}, s.css || {}),
104
113
  xpath: Object.assign({}, s.xpath || {}),
@@ -116,7 +125,7 @@ Before(function () {
116
125
 
117
126
  // Auto-load selector files specified in worldParameters.
118
127
  for (const file of cfg.files) {
119
- const filePath = cfg.filesPath ? path.join(cfg.filesPath, file) : file;
128
+ const filePath = resolveSelectorFile(cfg, file);
120
129
  try {
121
130
  const parsed = parseFile(filePath);
122
131
  if (parsed && parsed.css) Object.assign(this.__selectorsCss, parsed.css);
@@ -185,6 +194,18 @@ function resolveSelector(world, name) {
185
194
  );
186
195
  }
187
196
 
197
+ // The rows of a "define css/xpath selectors" table. A first row that names
198
+ // the columns, as the docs write it (| name | css selector |), is a header,
199
+ // not a selector.
200
+ function selectorRows(dataTable) {
201
+ const rows = dataTable.raw();
202
+ if (rows.length === 0) return rows;
203
+ const [name, selector] = rows[0].map((cell) => String(cell || '').trim().toLowerCase());
204
+ const header = (name === 'name' || name === 'selector name')
205
+ && /^(?:(?:css|xpath)(?: selector| expression)?|selector)$/.test(selector || '');
206
+ return header ? rows.slice(1) : rows;
207
+ }
208
+
188
209
  // Names are separated by a comma or by the whole word "and" ("a, b and c",
189
210
  // "a, b, and c"), never by the letters "and" inside a name ("brand logo").
190
211
  function parseNames(text) {
@@ -334,8 +355,9 @@ When(/^(I |we )*add "([^"]*)" selector for "([^"]*)" xpath selector$/, function
334
355
  });
335
356
 
336
357
  /**
337
- * Load CSS and XPath selectors from a JSON file.
338
- * File path is relative to worldParameters.selectors.filesPath.
358
+ * Load CSS and XPath selectors from a JSON file. The file is looked for in the
359
+ * folder of worldParameters.selectors.filesPath (default ./tests/selectors/)
360
+ * first, then as written from the project root.
339
361
  *
340
362
  * Example #1: When I add selectors from "selectors.json" file
341
363
  * Example #2: When I add selectors from "admin-selectors.json" file
@@ -364,8 +386,7 @@ When(/^(I |we )*add "([^"]*)" selector for "([^"]*)" xpath selector$/, function
364
386
  When(/^(I |we )*add selectors from "([^"]*)" file$/, function (pronounCase, fileName) {
365
387
  const cfg = this.__selectorsConfig;
366
388
  if (!fileName) throw friendly('Selectors: file name must not be empty.');
367
- if (!cfg.filesPath) throw friendly('Selectors: worldParameters.selectors.filesPath must be set to load selector files.');
368
- const filePath = path.join(cfg.filesPath, fileName);
389
+ const filePath = resolveSelectorFile(cfg, fileName, this.page);
369
390
  let parsed;
370
391
  try { parsed = parseFile(filePath); } catch (e) {
371
392
  throw friendly(`Selectors: failed to load selector file "${filePath}": ${e.message}`);
@@ -423,6 +444,9 @@ Then(/^(I |we )*print xpath selectors$/, function (_pronounCase) {
423
444
  /**
424
445
  * Define named CSS selectors in bulk for the current scenario.
425
446
  *
447
+ * The table may start with a header row that names its columns
448
+ * (`| name | css selector |`): that row registers nothing.
449
+ *
426
450
  * Example #1:
427
451
  * Given I define css selectors:
428
452
  * | header | #header |
@@ -498,9 +522,15 @@ Then(/^(I |we )*print xpath selectors$/, function (_pronounCase) {
498
522
  * | nav | nav[role=navigation] |
499
523
  * | main | main |
500
524
  * | footer | footer |
525
+ *
526
+ * Example #14: A header row names the columns and registers nothing:
527
+ * Given I define css selectors:
528
+ * | name | css selector |
529
+ * | heading | h1 |
530
+ * | list | ul |
501
531
  */
502
532
  Given(/^(I |we )*define css selectors:$/, function (pronounCase, dataTable) {
503
- for (const [name, selector] of dataTable.raw()) {
533
+ for (const [name, selector] of selectorRows(dataTable)) {
504
534
  if (name && selector) this.__selectorsCss[name.trim()] = selector.trim();
505
535
  }
506
536
  });
@@ -508,6 +538,9 @@ Given(/^(I |we )*define css selectors:$/, function (pronounCase, dataTable) {
508
538
  /**
509
539
  * Define named XPath selectors in bulk for the current scenario.
510
540
  *
541
+ * The table may start with a header row that names its columns
542
+ * (`| name | xpath selector |`): that row registers nothing.
543
+ *
511
544
  * Example #1:
512
545
  * Given I define xpath selectors:
513
546
  * | first heading | //h1[1] |
@@ -540,24 +573,36 @@ Given(/^(I |we )*define css selectors:$/, function (pronounCase, dataTable) {
540
573
  * Example #10:
541
574
  * Given I define xpath selectors:
542
575
  * | user menu | //*[@id='user-menu'] |
576
+ * Example #11:
577
+ * Given I define xpath selectors:
578
+ * | name | xpath selector |
579
+ * | first heading | //h1[1] |
543
580
  */
544
581
  Given(/^(I |we )*define xpath selectors:$/, function (pronounCase, dataTable) {
545
- for (const [name, selector] of dataTable.raw()) {
582
+ for (const [name, selector] of selectorRows(dataTable)) {
546
583
  if (name && selector) this.__selectorsXpath[name.trim()] = selector.trim();
547
584
  }
548
585
  });
549
586
 
550
587
  /**
551
- * Resize viewport to a named breakpoint.
552
- * Built-in names: xs, sm, md, lg, xl, xxl, xxxl.
588
+ * Resize viewport to a named breakpoint. The same registry as "I set the
589
+ * viewport to the "…" breakpoint" and the @mobile / @desktop tags: the
590
+ * built-in names below, replaced or extended by
591
+ * worldParameters.selectors.breakpoints, WEBSHIP_SELECTORS_BREAKPOINTS and
592
+ * "the following responsive breakpoints:". An unknown name fails with the
593
+ * list of the known ones.
553
594
  *
554
- * xs 375 x 667 phone portrait
555
- * sm 576 x 800 large phone / phablet
556
- * md 768 x 1024 tablet portrait
557
- * lg 992 x 768 small laptop / tablet landscape
558
- * xl 1200 x 900 desktop (default)
559
- * xxl 1400 x 900 wide desktop / HD
560
- * xxxl 1920 x 1080 Full HD / large monitor
595
+ * xs 375 x 667 phone portrait
596
+ * sm 576 x 800 large phone / phablet
597
+ * md 768 x 1024 tablet portrait
598
+ * lg 992 x 768 small laptop / tablet landscape
599
+ * xl 1200 x 900 desktop (marked default: true in the scaffold)
600
+ * xxl 1400 x 900 wide desktop / HD
601
+ * xxxl 1920 x 1080 Full HD / large monitor
602
+ * mobile 375 x 667 the size of the @mobile tag
603
+ * tablet 768 x 1024
604
+ * desktop 1200 x 900 the size of the @desktop tag; without a desktop of
605
+ * the project's own, the breakpoint marked default: true
561
606
  *
562
607
  * Example #1: Given I am viewing the site on a xl screen
563
608
  * Example #2: Given I am viewing the site on a xs screen
@@ -573,11 +618,7 @@ Given(/^(I |we )*define xpath selectors:$/, function (pronounCase, dataTable) {
573
618
  * Example #12: Given viewing the site on a lg screen
574
619
  */
575
620
  Given(/^(I am |we are )?viewing the site on a (?:"([^"]+)"|([a-zA-Z0-9 _,]+)) (?:screen|device)$/, async function (pronounCase, quoted, bare) {
576
- const name = (quoted || bare || '').trim();
577
- const cfg = this.__selectorsConfig;
578
- if (!cfg.breakpoints[name]) throw friendly(`Selectors: breakpoint "${name}" not defined in worldParameters.selectors.breakpoints.`);
579
- const { width, height } = cfg.breakpoints[name];
580
- await this.page.setViewportSize({ width, height });
621
+ await this.page.setViewportSize(breakpoint(this, quoted || bare));
581
622
  });
582
623
 
583
624
  // ===========================================================================
@@ -968,6 +1009,12 @@ When(/^(I |we )*select "([^"]*)" text in "([^"]*)" field$/, async function (pron
968
1009
  /**
969
1010
  * Click one or more named components — uses locator.click() which auto-scrolls.
970
1011
  *
1012
+ * The names are read without quotes, so the step matches any unquoted words
1013
+ * after "click" (registered names such as "sign in button" need that). A
1014
+ * custom step that starts the same way, such as "I click next button in
1015
+ * tour", is ambiguous with this one: give a custom step a quoted argument
1016
+ * and words of its own ("I click "Next" in the tour") instead.
1017
+ *
971
1018
  * Example #1: When I click nav
972
1019
  * Example #2: When I click search button
973
1020
  * Example #3: When click cta
@@ -11,6 +11,27 @@
11
11
  // page's origin and require a navigated page first.
12
12
 
13
13
  const { Given } = require('@cucumber/cucumber');
14
+ const { failure } = require('./webship');
15
+
16
+ // Local storage and session storage belong to the site of the page. On a page
17
+ // that has none (about:blank before the first "I am on", a data: page) the
18
+ // browser refuses them with a SecurityError: say so, and what to do.
19
+ async function inPageStorage(world, what, script, arg) {
20
+ try {
21
+ return await world.page.evaluate(script, arg);
22
+ } catch (e) {
23
+ if (!/SecurityError|Access is denied|operation is insecure/i.test(String((e && e.message) || ''))) throw e;
24
+ throw failure(world.page, `Could not ${what}: the page has no site yet.`, {
25
+ hint: 'local storage and session storage belong to the site of the page: open a page of the site first, for example: Given I am on "/"',
26
+ });
27
+ }
28
+ }
29
+
30
+ // A quoted key or value may hold a double quote written \" (a JSON value, a
31
+ // quoted cookie value), read as {string} reads it in the cookie assertions.
32
+ function unquote(text) {
33
+ return String(text === undefined || text === null ? '' : text).replace(/\\"/g, '"').replace(/\\'/g, "'");
34
+ }
14
35
 
15
36
  // ---------------------------------------------------------------------------
16
37
  // Cookies — context-level
@@ -28,7 +49,9 @@ const { Given } = require('@cucumber/cucumber');
28
49
  * And I am on "/dashboard"
29
50
  *
30
51
  */
31
- Given(/^(?:the cookie|cookie) "([^"]*)" is set to "([^"]*)"$/, async function (name, value) {
52
+ Given(/^(?:the cookie|cookie) "((?:[^"\\]|\\.)*)" is set to "((?:[^"\\]|\\.)*)"$/, async function (name, value) {
53
+ name = unquote(name);
54
+ value = unquote(value);
32
55
  const url = this.page.url() && this.page.url() !== 'about:blank' ? this.page.url() : (this.launchUrl || 'http://localhost');
33
56
  const u = new URL(url);
34
57
  await this.context.addCookies([{
@@ -53,7 +76,8 @@ Given(/^(?:the cookie|cookie) "([^"]*)" is set to "([^"]*)"$/, async function (n
53
76
  * When I follow "Pricing"
54
77
  *
55
78
  */
56
- Given(/^the cookie "([^"]*)" is removed$/, async function (name) {
79
+ Given(/^the cookie "((?:[^"\\]|\\.)*)" is removed$/, async function (name) {
80
+ name = unquote(name);
57
81
  const cookies = await this.context.cookies();
58
82
  const remaining = cookies.filter((c) => c.name !== name);
59
83
  await this.context.clearCookies();
@@ -88,7 +112,8 @@ Given(/^all cookies are cleared$/, async function () {
88
112
  * Set a local storage entry on the current page.
89
113
  *
90
114
  * The page must be loaded first (local storage is per-origin). Stored value
91
- * is always a string — JSON-encode complex objects manually.
115
+ * is always a string — JSON-encode complex objects manually, writing each
116
+ * double quote as \" inside the step's quotes.
92
117
  *
93
118
  * Example #1: Given the local storage "user" is set to "Alice"
94
119
  * Example #2: Given I am on the homepage
@@ -102,8 +127,8 @@ Given(/^all cookies are cleared$/, async function () {
102
127
  * Example #5: Given the local storage "feature_flag" is set to "enabled"
103
128
  *
104
129
  */
105
- Given(/^(?:the )?local storage "([^"]*)" is set to "([^"]*)"$/, async function (key, value) {
106
- await this.page.evaluate(({ k, v }) => localStorage.setItem(k, v), { k: key, v: value });
130
+ Given(/^(?:the )?local storage "((?:[^"\\]|\\.)*)" is set to "((?:[^"\\]|\\.)*)"$/, async function (key, value) {
131
+ await inPageStorage(this, `set the local storage "${unquote(key)}"`, ({ k, v }) => localStorage.setItem(k, v), { k: unquote(key), v: unquote(value) });
107
132
  });
108
133
 
109
134
  /**
@@ -120,8 +145,8 @@ Given(/^(?:the )?local storage "([^"]*)" is set to "([^"]*)"$/, async function (
120
145
  * Example #5: Given the local storage "auth_token" is removed
121
146
  *
122
147
  */
123
- Given(/^(?:the )?local storage "([^"]*)" is removed$/, async function (key) {
124
- await this.page.evaluate((k) => localStorage.removeItem(k), key);
148
+ Given(/^(?:the )?local storage "((?:[^"\\]|\\.)*)" is removed$/, async function (key) {
149
+ await inPageStorage(this, `remove the local storage "${unquote(key)}"`, (k) => localStorage.removeItem(k), unquote(key));
125
150
  });
126
151
 
127
152
  /**
@@ -140,7 +165,7 @@ Given(/^(?:the )?local storage "([^"]*)" is removed$/, async function (key) {
140
165
  *
141
166
  */
142
167
  Given(/^local storage is cleared$/, async function () {
143
- await this.page.evaluate(() => localStorage.clear());
168
+ await inPageStorage(this, 'clear the local storage', () => localStorage.clear());
144
169
  });
145
170
 
146
171
  /**
@@ -155,8 +180,8 @@ Given(/^local storage is cleared$/, async function () {
155
180
  * And I am on "/cart"
156
181
  *
157
182
  */
158
- Given(/^(?:the )?session storage "([^"]*)" is set to "([^"]*)"$/, async function (key, value) {
159
- await this.page.evaluate(({ k, v }) => sessionStorage.setItem(k, v), { k: key, v: value });
183
+ Given(/^(?:the )?session storage "((?:[^"\\]|\\.)*)" is set to "((?:[^"\\]|\\.)*)"$/, async function (key, value) {
184
+ await inPageStorage(this, `set the session storage "${unquote(key)}"`, ({ k, v }) => sessionStorage.setItem(k, v), { k: unquote(key), v: unquote(value) });
160
185
  });
161
186
 
162
187
  /**
@@ -171,8 +196,8 @@ Given(/^(?:the )?session storage "([^"]*)" is set to "([^"]*)"$/, async function
171
196
  * Example #5: Given the session storage "from checkout" is removed
172
197
  *
173
198
  */
174
- Given(/^(?:the )?session storage "([^"]*)" is removed$/, async function (key) {
175
- await this.page.evaluate((k) => sessionStorage.removeItem(k), key);
199
+ Given(/^(?:the )?session storage "((?:[^"\\]|\\.)*)" is removed$/, async function (key) {
200
+ await inPageStorage(this, `remove the session storage "${unquote(key)}"`, (k) => sessionStorage.removeItem(k), unquote(key));
176
201
  });
177
202
 
178
203
  /**
@@ -190,5 +215,5 @@ Given(/^(?:the )?session storage "([^"]*)" is removed$/, async function (key) {
190
215
  *
191
216
  */
192
217
  Given(/^session storage is cleared$/, async function () {
193
- await this.page.evaluate(() => sessionStorage.clear());
218
+ await inPageStorage(this, 'clear the session storage', () => sessionStorage.clear());
194
219
  });
@@ -4,6 +4,7 @@
4
4
 
5
5
  const { Then } = require('@cucumber/cucumber');
6
6
  const assert = require('assert');
7
+ const { failure } = require('./webship');
7
8
 
8
9
  async function getTable(page, sel) {
9
10
  return await page.locator(sel).first().evaluate((tbl) => {
@@ -100,10 +101,66 @@ Then('the table {string} should not be empty', async function (sel) {
100
101
  assert.ok(t.rowCount > 0, `Table "${sel}" should not be empty.`);
101
102
  });
102
103
 
104
+ /**
105
+ * The number a table cell reads as, or null: digits with an optional sign,
106
+ * thousands separators and decimals, after a currency sign or code and before
107
+ * a percent sign, a unit or a word (`$1,299.00`, `USD 40`, `12 %`, `3.5 kg`).
108
+ * A word before the number ("Item 2") makes the cell text.
109
+ *
110
+ * @param {string} cell
111
+ * @returns {number|null}
112
+ */
113
+ function cellNumber(cell) {
114
+ const m = String(cell).replace(/[\s\u00a0]+/g, ' ').trim()
115
+ .match(/^(?:[A-Z]{3} ?)?[^\p{L}\d+-]*([+-]?(?:\d{1,3}(?:,\d{3})+|\d+)(?:\.\d+)?)[^\d]*$/u);
116
+ return m ? parseFloat(m[1].replace(/,/g, '')) : null;
117
+ }
118
+
119
+ /**
120
+ * The time a table cell reads as, in ms, or null when it is not a date.
121
+ *
122
+ * @param {string} cell
123
+ * @returns {number|null}
124
+ */
125
+ function cellDate(cell) {
126
+ const text = String(cell).trim();
127
+ if (!/\d/.test(text)) return null;
128
+ const ms = Date.parse(text);
129
+ return Number.isNaN(ms) ? null : ms;
130
+ }
131
+
132
+ /**
133
+ * How the cells of a column compare, the way a reader orders them: as numbers
134
+ * when every cell reads as a number, else as dates when every cell reads as a
135
+ * date, else as text with letter case ignored and the numbers inside the text
136
+ * in number order ("Item 2" before "Item 10").
137
+ *
138
+ * @param {string[]} values
139
+ * @returns {{kind: string, compare: function(string, string): number}}
140
+ */
141
+ function columnOrder(values) {
142
+ if (values.length && values.every((v) => cellNumber(v) !== null)) {
143
+ return { kind: 'numbers', compare: (a, b) => cellNumber(a) - cellNumber(b) };
144
+ }
145
+ if (values.length && values.every((v) => cellDate(v) !== null)) {
146
+ return { kind: 'dates', compare: (a, b) => cellDate(a) - cellDate(b) };
147
+ }
148
+ return {
149
+ kind: 'text, letter case ignored',
150
+ compare: (a, b) => a.localeCompare(b, undefined, { numeric: true, sensitivity: 'base' }),
151
+ };
152
+ }
153
+
103
154
  /**
104
155
  * Assert a table is sorted ascending or descending by a header.
105
156
  *
106
- * Direction accepts `ascending` / `asc` / `descending` / `desc`.
157
+ * The cells of the column are compared the way a reader orders them: as
158
+ * numbers when every cell reads as a number (`$9.99`, `1,299`, `12 %`), else
159
+ * as dates when every cell reads as a date, else as text with letter case
160
+ * ignored and the numbers inside it in number order ("Item 2" before
161
+ * "Item 10"). Each row is compared with the next one, so equal cells may come
162
+ * in any order. "descending" or "desc" checks the reverse order; any other
163
+ * word checks the ascending order.
107
164
  *
108
165
  * Example #1: Then the table "#users" should be sorted by "Name" in "ascending" order
109
166
  * Example #2: Then the table "table.orders" should be sorted by "Total" in "descending" order
@@ -113,13 +170,31 @@ Then('the table {string} should not be empty', async function (sel) {
113
170
  *
114
171
  */
115
172
  Then('the table {string} should be sorted by {string} in {string} order', async function (sel, column, direction) {
173
+ if (!(await this.page.locator(sel).count())) {
174
+ throw failure(this.page, `No table matches "${sel}".`, {
175
+ hint: 'the first argument is a CSS selector of the table, such as "#users" or "table.orders".',
176
+ });
177
+ }
116
178
  const t = await getTable(this.page, sel);
117
179
  const idx = t.head.findIndex((h) => h === column);
118
- assert.ok(idx !== -1, `Column "${column}" not found.`);
119
- const values = t.body.map((r) => r[idx]);
120
- const sorted = [...values].sort();
121
- if (direction.toLowerCase() === 'descending' || direction.toLowerCase() === 'desc') sorted.reverse();
122
- assert.deepStrictEqual(values, sorted, `Table "${sel}" not sorted by "${column}" ${direction}.`);
180
+ if (idx === -1) {
181
+ throw failure(this.page, `The table "${sel}" has no "${column}" column.`, {
182
+ found: t.head.length ? t.head.map((h) => `"${h}"`).join(', ') : 'no header cells (<th>)',
183
+ hint: 'the column is named by the exact text of its header cell.',
184
+ });
185
+ }
186
+ const descending = ['descending', 'desc'].includes(direction.toLowerCase());
187
+ const values = t.body.map((r) => (r[idx] === undefined ? '' : r[idx]));
188
+ const order = columnOrder(values);
189
+ for (let i = 1; i < values.length; i++) {
190
+ const diff = order.compare(values[i - 1], values[i]);
191
+ if (descending ? diff < 0 : diff > 0) {
192
+ throw failure(this.page, `The table "${sel}" is not sorted by "${column}" in ${descending ? 'descending' : 'ascending'} order: row ${i} ("${values[i - 1]}") comes before row ${i + 1} ("${values[i]}").`, {
193
+ found: values.map((v) => `"${v}"`).join(', '),
194
+ hint: `the cells were compared as ${order.kind}.`,
195
+ });
196
+ }
197
+ }
123
198
  });
124
199
 
125
200
  /**