webship-js 2.0.10 → 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 (248) hide show
  1. package/.circleci/config.yml +10 -1
  2. package/.drone.yml +7 -7
  3. package/.github/ISSUE_TEMPLATE/issue.md +37 -0
  4. package/.github/PULL_REQUEST_TEMPLATE.md +24 -0
  5. package/.github/workflows/github-actions.yml +101 -4
  6. package/.gitlab-ci.yml +9 -4
  7. package/.harness/webship-js-pipeline.yml +5 -6
  8. package/.semaphore/semaphore.yml +6 -9
  9. package/.teamcity/settings.kts +7 -6
  10. package/.travis.yml +6 -1
  11. package/AGENTS.md +1 -1
  12. package/CLAUDE.md +69 -24
  13. package/Jenkinsfile +5 -3
  14. package/README.md +13 -1
  15. package/azure-pipelines.yml +17 -8
  16. package/bamboo-specs/bamboo.yml +9 -15
  17. package/bin/generate-reports.js +51 -7
  18. package/bin/init-webship.js +127 -23
  19. package/bitbucket-pipelines.yml +5 -1
  20. package/buildspec.yml +6 -7
  21. package/cloudbuild.yaml +28 -12
  22. package/codefresh.yml +6 -6
  23. package/cucumber.js +46 -11
  24. package/docs/00-quick-start.md +38 -7
  25. package/docs/02-bbr-smart-waits.md +21 -10
  26. package/docs/03-selector-registry.md +24 -0
  27. package/docs/04-step-reference.md +53 -27
  28. package/docs/05-web-first-assertions.md +6 -0
  29. package/docs/07-auth-state.md +1 -1
  30. package/docs/08-clock-mocking.md +21 -2
  31. package/docs/09-api-testing.md +40 -2
  32. package/docs/10-accessibility.md +2 -0
  33. package/docs/11-debugging.md +24 -1
  34. package/docs/12-ai-agent-guide.md +8 -1
  35. package/docs/13-faq.md +75 -1
  36. package/docs/14-recipes-cookbook.md +2 -0
  37. package/docs/15-tag-conventions.md +5 -1
  38. package/docs/16-ci-cd.md +161 -124
  39. package/docs/README.md +5 -5
  40. package/docs/advanced-screenshots.md +3 -1
  41. package/docs/api-step-definitions.md +16 -2
  42. package/docs/global-settings.md +70 -18
  43. package/docs/install-webship-js/ddev-webship-js.md +3 -0
  44. package/docs/install-webship-js.md +16 -2
  45. package/docs/step-definitions/then-i-should-see.md +14 -1
  46. package/docs/step-definitions/then-item-checkbox.md +2 -0
  47. package/docs/step-definitions/when-i-fill.md +4 -0
  48. package/docs/step-definitions/when-i-select-option-select-list.md +2 -0
  49. package/examples/a11y-legacy-widget.html +34 -0
  50. package/examples/auth-state.html +42 -0
  51. package/examples/choice-controls.html +29 -0
  52. package/examples/clock.html +33 -0
  53. package/examples/datetime-fields.html +52 -0
  54. package/examples/downloads/webship-archive.zip +0 -0
  55. package/examples/downloads/webship-notes.txt +4 -0
  56. package/examples/downloads/webship-report.csv +4 -0
  57. package/examples/downloads.html +16 -0
  58. package/examples/element-selector-hint.html +16 -0
  59. package/examples/element-viewport.html +42 -0
  60. package/examples/field-states.html +27 -0
  61. package/examples/field-types.html +98 -0
  62. package/examples/fill-in-empty.html +26 -0
  63. package/examples/fill-unreachable.html +27 -0
  64. package/examples/iframe-inner.html +20 -0
  65. package/examples/iframe-nested.html +16 -0
  66. package/examples/iframe-newsletter.html +29 -0
  67. package/examples/iframe-order.html +26 -0
  68. package/examples/iframe-outer.html +15 -0
  69. package/examples/iframe.html +21 -0
  70. package/examples/javascript-errors.html +35 -0
  71. package/examples/links.html +1 -0
  72. package/examples/metatags.html +18 -0
  73. package/examples/mouse-and-pointer.html +83 -0
  74. package/examples/multi-value-fields.html +54 -0
  75. package/examples/native-dialogs.html +8 -0
  76. package/examples/network.html +83 -0
  77. package/examples/registered-names.html +15 -0
  78. package/examples/scroll-horizontal.html +50 -0
  79. package/examples/select-by-label.html +33 -0
  80. package/examples/selectors-position.html +29 -0
  81. package/examples/settle-budget.html +21 -0
  82. package/examples/sorted-tables.html +38 -0
  83. package/examples/storage.html +57 -0
  84. package/examples/text-matching.html +48 -0
  85. package/examples/text-order.html +25 -0
  86. package/examples/touch.html +22 -0
  87. package/examples/viewport-size.html +24 -0
  88. package/examples/viewport-top.html +36 -0
  89. package/examples/wait-conditions.html +69 -0
  90. package/examples/web-first.html +99 -0
  91. package/package.json +24 -2
  92. package/playwright.config.ts +3 -1
  93. package/tests/assets/catalog.xml +19 -0
  94. package/tests/assets/feed-namespaced.xml +13 -0
  95. package/tests/assets/sitemap.xml +14 -0
  96. package/tests/assets/webship-site-expected.yaml +21 -0
  97. package/tests/assets/webship-site.schema.json +46 -0
  98. package/tests/assets/webship-site.yaml +21 -0
  99. package/tests/check-api-launch-url.js +106 -0
  100. package/tests/check-assets.js +103 -0
  101. package/tests/check-attachments.js +105 -0
  102. package/tests/check-breakpoints.js +117 -0
  103. package/tests/check-clock.js +143 -0
  104. package/tests/check-config.js +90 -0
  105. package/tests/check-context.js +215 -0
  106. package/tests/check-dry-run.js +104 -0
  107. package/tests/check-examples.js +241 -0
  108. package/tests/check-exit-report.js +141 -0
  109. package/tests/check-javascript-errors.js +105 -0
  110. package/tests/check-must-fail.js +85 -0
  111. package/tests/check-paths.js +82 -0
  112. package/tests/check-report.js +119 -0
  113. package/tests/check-scaffold.js +246 -0
  114. package/tests/check-screenshots.js +117 -0
  115. package/tests/check-settle-verbs.js +137 -0
  116. package/tests/check-time-limit.js +104 -0
  117. package/tests/check-video.js +156 -0
  118. package/tests/check-world.js +167 -0
  119. package/tests/features/a11y.feature +18 -0
  120. package/tests/features/api-base-url.feature +25 -0
  121. package/tests/features/api-form-data.feature +18 -0
  122. package/tests/features/api-json-paths.feature +24 -0
  123. package/tests/features/api-response-contains.feature +21 -0
  124. package/tests/features/api-response-header-presence.feature +17 -0
  125. package/tests/features/api-response-header.feature +17 -0
  126. package/tests/features/api-saved-placeholders.feature +37 -0
  127. package/tests/features/api-step-definitions-individual.feature +1 -1
  128. package/tests/features/api-tables.feature +40 -0
  129. package/tests/features/auth-state.feature +32 -0
  130. package/tests/features/breakpoints.feature +25 -0
  131. package/tests/features/choice-controls.feature +35 -0
  132. package/tests/features/clock.feature +27 -0
  133. package/tests/features/complete-api-testing-examples.feature +1 -1
  134. package/tests/features/cookie.feature +9 -0
  135. package/tests/features/datetime-field-lookup.feature +29 -0
  136. package/tests/features/dialog.feature +27 -0
  137. package/tests/features/element-selector-hint.feature +14 -0
  138. package/tests/features/element.feature +47 -0
  139. package/tests/features/field-state.feature +21 -0
  140. package/tests/features/field.feature +104 -0
  141. package/tests/features/file-download.feature +64 -0
  142. package/tests/features/fill-in-empty-value.feature +41 -0
  143. package/tests/features/fill-reachable.feature +13 -0
  144. package/tests/features/iframe-nested.feature +43 -0
  145. package/tests/features/iframe.feature +83 -0
  146. package/tests/features/javascript-tolerated-errors.feature +20 -0
  147. package/tests/features/javascript.feature +47 -0
  148. package/tests/features/link.feature +11 -0
  149. package/tests/features/metatag.feature +38 -0
  150. package/tests/features/modal-open.feature +13 -0
  151. package/tests/features/mouse-and-pointer.feature +86 -0
  152. package/tests/features/multi-value-field-lookup.feature +30 -0
  153. package/tests/features/network-mocking.feature +80 -0
  154. package/tests/features/registered-names.feature +14 -0
  155. package/tests/features/responsive.feature +27 -0
  156. package/tests/features/scroll-horizontal.feature +55 -0
  157. package/tests/features/select-by-label.feature +31 -0
  158. package/tests/features/selector-files.feature +14 -0
  159. package/tests/features/selectors-position.feature +41 -0
  160. package/tests/features/selectors-table-header.feature +35 -0
  161. package/tests/features/settle-budget.feature +11 -0
  162. package/tests/features/sorted-tables.feature +19 -0
  163. package/tests/features/storage-quoted-values.feature +26 -0
  164. package/tests/features/storage.feature +98 -0
  165. package/tests/features/test--then--i-see-locator.feature +13 -0
  166. package/tests/features/test--then--i-should--see-text-in-element.feature +9 -1
  167. package/tests/features/test--then--the-field-should-contain-value.feature +8 -0
  168. package/tests/features/text-matching.feature +38 -0
  169. package/tests/features/text-order.feature +14 -0
  170. package/tests/features/touch.feature +21 -0
  171. package/tests/features/video.feature +1 -0
  172. package/tests/features/viewport-top.feature +13 -0
  173. package/tests/features/wait.feature +89 -0
  174. package/tests/features/web-first.feature +100 -0
  175. package/tests/features/xml-namespaces.feature +34 -0
  176. package/tests/features/xml.feature +96 -0
  177. package/tests/features/yaml.feature +75 -0
  178. package/tests/must-fail/api-json-paths.feature +21 -0
  179. package/tests/must-fail/api-response-contains.feature +23 -0
  180. package/tests/must-fail/api-response-header-presence.feature +17 -0
  181. package/tests/must-fail/api-response-header.feature +21 -0
  182. package/tests/must-fail/api-without-base-url.feature +11 -0
  183. package/tests/must-fail/assertions.feature +96 -0
  184. package/tests/must-fail/breakpoints.feature +15 -0
  185. package/tests/must-fail/choice-controls.feature +25 -0
  186. package/tests/must-fail/clock.feature +11 -0
  187. package/tests/must-fail/datetime-field.feature +10 -0
  188. package/tests/must-fail/element-selector-hint.feature +17 -0
  189. package/tests/must-fail/field-state.feature +20 -0
  190. package/tests/must-fail/fill-field.feature +30 -0
  191. package/tests/must-fail/iframe-text.feature +17 -0
  192. package/tests/must-fail/modal-open.feature +26 -0
  193. package/tests/must-fail/multi-value-field.feature +18 -0
  194. package/tests/must-fail/registered-names.feature +25 -0
  195. package/tests/must-fail/select-list.feature +15 -0
  196. package/tests/must-fail/selector-files.feature +10 -0
  197. package/tests/must-fail/sorted-tables.feature +20 -0
  198. package/tests/must-fail/storage-before-a-page.feature +13 -0
  199. package/tests/must-fail/text-matching.feature +16 -0
  200. package/tests/must-fail/text-order.feature +15 -0
  201. package/tests/must-fail/viewport-top.feature +20 -0
  202. package/tests/must-fail/waits.feature +51 -0
  203. package/tests/must-fail/yaml-numbers.feature +48 -0
  204. package/tests/reports/README.md +2 -2
  205. package/tests/step-definitions/a11y.steps.js +36 -23
  206. package/tests/step-definitions/action.steps.js +22 -8
  207. package/tests/step-definitions/api.steps.js +349 -67
  208. package/tests/step-definitions/assertion.steps.js +327 -63
  209. package/tests/step-definitions/auth.steps.js +15 -18
  210. package/tests/step-definitions/clock.steps.js +22 -0
  211. package/tests/step-definitions/debug.steps.js +8 -0
  212. package/tests/step-definitions/dialog.steps.js +9 -2
  213. package/tests/step-definitions/element.steps.js +135 -18
  214. package/tests/step-definitions/field.steps.js +523 -80
  215. package/tests/step-definitions/file-download.steps.js +74 -10
  216. package/tests/step-definitions/form.steps.js +76 -29
  217. package/tests/step-definitions/iframe.steps.js +89 -29
  218. package/tests/step-definitions/input.steps.js +26 -7
  219. package/tests/step-definitions/javascript.steps.js +64 -22
  220. package/tests/step-definitions/modal.steps.js +79 -13
  221. package/tests/step-definitions/navigation.steps.js +14 -0
  222. package/tests/step-definitions/network.steps.js +15 -5
  223. package/tests/step-definitions/response.steps.js +6 -4
  224. package/tests/step-definitions/responsive.steps.js +26 -33
  225. package/tests/step-definitions/screenshot.steps.js +26 -9
  226. package/tests/step-definitions/scroll.steps.js +20 -0
  227. package/tests/step-definitions/selectors.steps.js +104 -51
  228. package/tests/step-definitions/storage.steps.js +41 -16
  229. package/tests/step-definitions/table.steps.js +81 -6
  230. package/tests/step-definitions/video.steps.js +52 -55
  231. package/tests/step-definitions/wait.steps.js +209 -54
  232. package/tests/step-definitions/web-first.steps.js +69 -35
  233. package/tests/step-definitions/webship.js +807 -128
  234. package/tests/step-definitions/xml.steps.js +124 -28
  235. package/tests/step-definitions/yaml.steps.js +90 -46
  236. package/.scratch/commit.txt +0 -14
  237. package/.scratch/docs.py +0 -42
  238. package/.scratch/echo-server.js +0 -8
  239. package/.scratch/echo.js +0 -35
  240. package/.scratch/echo.pid +0 -1
  241. package/.scratch/features/cookies.feature +0 -22
  242. package/.scratch/http.pid +0 -1
  243. package/.scratch/https.pid +0 -1
  244. package/.scratch/issue.md +0 -49
  245. package/.scratch/one.js +0 -2
  246. package/.scratch/one.json +0 -280
  247. package/.scratch/patch.py +0 -163
  248. package/.scratch/pr.md +0 -30
@@ -148,10 +148,63 @@ Then('the downloaded file name should contain {string}', async function (part) {
148
148
  assert.ok(this._lastDownload.filename.indexOf(part) !== -1, `Filename "${this._lastDownload.filename}" does not contain "${part}".`);
149
149
  });
150
150
 
151
- // ZIP archive assertions: pending. Install `yauzl` or `adm-zip` to enable.
151
+ // ---------------------------------------------------------------------------
152
+ // ZIP archive assertions
153
+ // ---------------------------------------------------------------------------
154
+ //
155
+ // The names are read from the central directory of the archive, with no
156
+ // dependency: nothing is unpacked. Folder entries are left out, and a file in
157
+ // a folder is known by its path in the archive ("reports/summary.csv").
158
+
159
+ const ZIP_END_OF_CENTRAL_DIRECTORY = 0x06054b50;
160
+ const ZIP_CENTRAL_DIRECTORY_ENTRY = 0x02014b50;
161
+
162
+ function zipFileNames(buffer) {
163
+ const notZip = () => friendly('The downloaded file is not a zip archive.');
164
+ if (!buffer || buffer.length < 22) throw notZip();
165
+ // The end record sits at the end of the file, before an optional comment.
166
+ let end = -1;
167
+ const lowest = Math.max(0, buffer.length - 22 - 0xffff);
168
+ for (let i = buffer.length - 22; i >= lowest; i--) {
169
+ if (buffer.readUInt32LE(i) === ZIP_END_OF_CENTRAL_DIRECTORY) { end = i; break; }
170
+ }
171
+ if (end === -1) throw notZip();
172
+ const total = buffer.readUInt16LE(end + 10);
173
+ let offset = buffer.readUInt32LE(end + 16);
174
+ if (total === 0xffff || offset === 0xffffffff) {
175
+ throw friendly('The downloaded file is a Zip64 archive, which the zip archive steps do not read.');
176
+ }
177
+ const names = [];
178
+ for (let n = 0; n < total; n++) {
179
+ if (offset + 46 > buffer.length || buffer.readUInt32LE(offset) !== ZIP_CENTRAL_DIRECTORY_ENTRY) throw notZip();
180
+ const nameLength = buffer.readUInt16LE(offset + 28);
181
+ const extraLength = buffer.readUInt16LE(offset + 30);
182
+ const commentLength = buffer.readUInt16LE(offset + 32);
183
+ const name = buffer.slice(offset + 46, offset + 46 + nameLength).toString('utf-8');
184
+ if (!name.endsWith('/')) names.push(name);
185
+ offset += 46 + nameLength + extraLength + commentLength;
186
+ }
187
+ return names;
188
+ }
189
+
190
+ function downloadedZipFileNames(world) {
191
+ assert.ok(world._lastDownload, 'No download has been performed.');
192
+ return zipFileNames(world._lastDownload.content);
193
+ }
194
+
195
+ // One name per row, several names in a row, or both.
196
+ function listedNames(table) {
197
+ return table.raw().flat().map((v) => v.trim()).filter(Boolean);
198
+ }
199
+
200
+ function baseName(entry) {
201
+ return entry.slice(entry.lastIndexOf('/') + 1);
202
+ }
152
203
 
153
204
  /**
154
- * (Pending) Assert the downloaded ZIP archive contains the listed filenames exactly.
205
+ * Assert the downloaded ZIP archive contains every listed file. A name
206
+ * matches a file by its full path in the archive ("reports/summary.csv")
207
+ * or by its file name alone ("summary.csv"). Other files may be present.
155
208
  *
156
209
  * Example #1: Then the downloaded file should be a zip archive containing the following files named:
157
210
  * | report.pdf |
@@ -166,12 +219,16 @@ Then('the downloaded file name should contain {string}', async function (part) {
166
219
  * | manifest.json |
167
220
  *
168
221
  */
169
- Then('the downloaded file should be a zip archive containing the following files named:', async function () {
170
- return 'pending';
222
+ Then('the downloaded file should be a zip archive containing the following files named:', async function (table) {
223
+ const names = downloadedZipFileNames(this);
224
+ const missing = listedNames(table).filter((want) => !names.some((n) => n === want || baseName(n) === want));
225
+ assert.strictEqual(missing.length, 0,
226
+ `The zip archive has no file named: ${missing.join(', ')}. It contains: ${names.join(', ') || '(no files)'}.`);
171
227
  });
172
228
 
173
229
  /**
174
- * (Pending) Assert the downloaded ZIP contains files whose names contain the listed substrings.
230
+ * Assert the downloaded ZIP contains, for every listed text, a file whose
231
+ * path in the archive contains it.
175
232
  *
176
233
  * Example #1: Then the downloaded file should be a zip archive containing the following files partially named:
177
234
  * | report |
@@ -186,12 +243,16 @@ Then('the downloaded file should be a zip archive containing the following files
186
243
  * | manifest |
187
244
  *
188
245
  */
189
- Then('the downloaded file should be a zip archive containing the following files partially named:', async function () {
190
- return 'pending';
246
+ Then('the downloaded file should be a zip archive containing the following files partially named:', async function (table) {
247
+ const names = downloadedZipFileNames(this);
248
+ const missing = listedNames(table).filter((part) => !names.some((n) => n.indexOf(part) !== -1));
249
+ assert.strictEqual(missing.length, 0,
250
+ `The zip archive has no file with a name containing: ${missing.join(', ')}. It contains: ${names.join(', ') || '(no files)'}.`);
191
251
  });
192
252
 
193
253
  /**
194
- * (Pending) Assert the downloaded ZIP does NOT contain files whose names contain the listed substrings.
254
+ * Assert the downloaded ZIP has no file whose path in the archive contains
255
+ * one of the listed texts.
195
256
  *
196
257
  * Example #1: Then the downloaded file should be a zip archive not containing the following files partially named:
197
258
  * | secret |
@@ -206,6 +267,9 @@ Then('the downloaded file should be a zip archive containing the following files
206
267
  * | __MACOSX |
207
268
  *
208
269
  */
209
- Then('the downloaded file should be a zip archive not containing the following files partially named:', async function () {
210
- return 'pending';
270
+ Then('the downloaded file should be a zip archive not containing the following files partially named:', async function (table) {
271
+ const names = downloadedZipFileNames(this);
272
+ const found = names.filter((n) => listedNames(table).some((part) => n.indexOf(part) !== -1));
273
+ assert.strictEqual(found.length, 0,
274
+ `The zip archive should not contain: ${found.join(', ')}.`);
211
275
  });
@@ -5,7 +5,7 @@
5
5
  // check / uncheck, radio buttons.
6
6
 
7
7
  const { When } = require('@cucumber/cucumber');
8
- const { buildSelector, fillField, friendly } = require('./webship');
8
+ const { buildSelector, fillField, fillLocator, friendly, failure, humanize, isTimeout } = require('./webship');
9
9
 
10
10
  // ---------------------------------------------------------------------------
11
11
  // Fill — by label, attribute, table, reverse syntax
@@ -13,28 +13,32 @@ const { buildSelector, fillField, friendly } = require('./webship');
13
13
 
14
14
  /**
15
15
  * Fill an input field located by its label, placeholder, or name.
16
+ * An empty value ("") empties the field.
16
17
  *
17
18
  * Example #1: When I fill in "Username" with "John Smith"
18
19
  * Example #2: When I fill in "Email" with "jon@example.com"
19
20
  * Example #3: And we fill in "Organization" with "Webship.co"
20
21
  * Example #4: And I fill in "Password" with "1234"
22
+ * Example #5: When we fill in "Search" with "webship"
21
23
  *
22
24
  */
23
25
  When(/^(I |we )*fill in "([^"]*)?" with "([^"]*)?"$/, async function (pronounCase, field, value) {
24
- await fillField(this.page, field, value);
26
+ await fillField(this.page, field, value, this);
25
27
  });
26
28
 
27
29
  /**
28
- * Fill an input field located by its attribute.
30
+ * Fill an input field located by its attribute. An empty value ("") empties
31
+ * the field.
29
32
  *
30
33
  * Example #1: When I fill in "#uname" with "John Smith" by attr
31
34
  * Example #2: When I fill in "uname" with "John Smith" by attr
32
35
  * Example #3: And I fill in "pwordcss" with "1234" by "class" attr
33
36
  * Example #4: And I fill in "Your full name" with "John Smith" by its "placeholder" attribute
37
+ * Example #5: When we fill in "email" with "jon@example.com" by its "name" attribute
34
38
  *
35
39
  */
36
40
  When(/^(I |we )*fill in "([^"]*)?" with "([^"]*)?" by( its)*(?: "([^"]*)?")* (attribute|attr)$/, async function (pronounCase, attrValue, txtValue, itsCase, attr, attrWord) {
37
- await this.page.locator(buildSelector(attrValue, attr)).first().fill(txtValue);
41
+ await fillLocator(this.page, this.page.locator(buildSelector(attrValue, attr)).first(), txtValue, attrValue);
38
42
  });
39
43
 
40
44
  /**
@@ -43,10 +47,12 @@ When(/^(I |we )*fill in "([^"]*)?" with "([^"]*)?" by( its)*(?: "([^"]*)?")* (at
43
47
  * Example #1: When I fill in "Username" with:
44
48
  * Example #2: And we fill in "Email" with:
45
49
  * Example #3: And I fill in "Password" with:
50
+ * Example #4: When we fill in "Search" with:
51
+ * Example #5: When I fill in "Comment" with:
46
52
  *
47
53
  */
48
54
  When(/^(I |we )*fill in "([^"]*)?" with:$/, async function (pronounCase, field) {
49
- await fillField(this.page, field, '');
55
+ await fillField(this.page, field, '', this);
50
56
  });
51
57
 
52
58
  /**
@@ -56,35 +62,41 @@ When(/^(I |we )*fill in "([^"]*)?" with:$/, async function (pronounCase, field)
56
62
  * Example #2: When I fill in "uname" with: by attr
57
63
  * Example #3: And I fill in "pwordcss" with: by "class" attr
58
64
  * Example #4: And I fill in "Your full name" with: by its "placeholder" attribute
65
+ * Example #5: When we fill in "email" with: by its "name" attribute
59
66
  *
60
67
  */
61
68
  When(/^(I |we )*fill in "([^"]*)?" with: by( its)*(?: "([^"]*)?")* (attribute|attr)$/, async function (pronounCase, attrValue, itsCase, attr, attrWord) {
62
- await this.page.locator(buildSelector(attrValue, attr)).first().fill('');
69
+ await fillLocator(this.page, this.page.locator(buildSelector(attrValue, attr)).first(), '', attrValue);
63
70
  });
64
71
 
65
72
  /**
66
- * Fill an input field located by label (reverse syntax).
73
+ * Fill an input field located by label (reverse syntax). An empty value ("")
74
+ * empties the field.
67
75
  *
68
76
  * Example #1: When I fill in "jon-smith" for "Username"
69
77
  * Example #2: When we fill in "Testing" for "Organization options"
70
78
  * Example #3: And I fill in "1234" for "Password"
79
+ * Example #4: When we fill in "jon@example.com" for "Email"
80
+ * Example #5: And I fill in "Webship" for "Search"
71
81
  *
72
82
  */
73
83
  When(/^(I |we )*fill in "([^"]*)?" for "([^"]*)?"$/, async function (pronounCase, value, field) {
74
- await fillField(this.page, field, value);
84
+ await fillField(this.page, field, value, this);
75
85
  });
76
86
 
77
87
  /**
78
- * Fill an input field located by attribute (reverse syntax).
88
+ * Fill an input field located by attribute (reverse syntax). An empty value
89
+ * ("") empties the field.
79
90
  *
80
91
  * Example #1: When I fill in "John Smith" for "#uname" by attr
81
92
  * Example #2: When I fill in "John Smith" for "uname" by attr
82
93
  * Example #3: And I fill in "1234" for "password" by "class" attr
83
94
  * Example #4: And I fill in "John Smith" for "Your full name" by its "placeholder" attribute
95
+ * Example #5: When we fill in "jon@example.com" for "email" by its "name" attribute
84
96
  *
85
97
  */
86
98
  When(/^(I |we )*fill in "([^"]*)?" for "([^"]*)?" by( its)*(?: "([^"]*)?")* (attribute|attr)$/, async function (pronounCase, txtValue, attrValue, itsCase, attr, attrWord) {
87
- await this.page.locator(buildSelector(attrValue, attr)).first().fill(txtValue);
99
+ await fillLocator(this.page, this.page.locator(buildSelector(attrValue, attr)).first(), txtValue, attrValue);
88
100
  });
89
101
 
90
102
  /**
@@ -114,7 +126,7 @@ When(/^(I |we )*fill in "([^"]*)?" for "([^"]*)?" by( its)*(?: "([^"]*)?")* (att
114
126
  */
115
127
  When(/^(I |we )*fill in( the)* following:$/, async function (pronounCase, theCase, table) {
116
128
  for (const [field, value] of table.raw()) {
117
- await fillField(this.page, field, value);
129
+ await fillField(this.page, field, value, this);
118
130
  }
119
131
  });
120
132
 
@@ -144,7 +156,7 @@ When(/^(I |we )*fill in( the)* following:$/, async function (pronounCase, theCas
144
156
  */
145
157
  When(/^(I |we )*fill in( the)* following: by( its)*(?: "([^"]*)?")* (attribute|attr)$/, async function (pronounCase, theCase, itsCase, attr, attrWord, table) {
146
158
  for (const [attrValue, value] of table.raw()) {
147
- await this.page.locator(buildSelector(attrValue, attr)).first().fill(value);
159
+ await fillLocator(this.page, this.page.locator(buildSelector(attrValue, attr)).first(), value, attrValue);
148
160
  }
149
161
  });
150
162
 
@@ -152,39 +164,71 @@ When(/^(I |we )*fill in( the)* following: by( its)*(?: "([^"]*)?")* (attribute|a
152
164
  // Select dropdown
153
165
  // ---------------------------------------------------------------------------
154
166
 
167
+ /**
168
+ * Find the `<select>` a step names. A CSS selector (it starts with `#`, `.`
169
+ * or `[`) is used as written; any other text is the exact text of the label
170
+ * of the select list, else its name, else its id, whatever its length.
171
+ *
172
+ * @param {import('playwright').Page} page
173
+ * @param {string} name
174
+ * @returns {import('playwright').Locator}
175
+ */
176
+ function selectList(page, name) {
177
+ if (/^[#.[]/.test(name)) return page.locator(name).first();
178
+ const value = name.replace(/["\\]/g, '\\$&');
179
+ return page.getByLabel(name, { exact: true })
180
+ .or(page.locator(`select[name="${value}"]`))
181
+ .or(page.locator(`select[id="${value}"]`))
182
+ .first();
183
+ }
184
+
155
185
  /**
156
186
  * Select an option from a dropdown by label, id, class, or name.
157
187
  *
188
+ * The select list is named by the exact text of its label (one word or
189
+ * several), by its name, by its id, or by a CSS selector that starts with
190
+ * `#`, `.` or `[`. The option is named by its text, else by its value. A
191
+ * select list that is not on the page after 5 seconds, or that has no such
192
+ * option, fails the step at once with the options it has.
193
+ *
158
194
  * Example #1: When I select "Mercedes" from "Cars"
159
195
  * Example #2: When I select "saab" from "#cars"
160
196
  * Example #3: When I select "Mercedes" from "cars"
161
197
  * Example #4: And we select "English" from "Language"
198
+ * Example #5: When I select "Red" from "filters[colour]"
162
199
  *
163
200
  */
164
- When(/^(I |we )*select "([^"]*)?" from "([^"]*)?"$/, async function (pronounCase, option, selectList) {
165
- let loc;
166
- if (selectList.startsWith('#') || selectList.startsWith('.')) {
167
- loc = this.page.locator(selectList);
168
- } else if (!selectList.includes(' ')) {
169
- loc = this.page.locator(`[name="${selectList}"], #${selectList}`).first();
170
- } else {
171
- loc = this.page.getByLabel(selectList, { exact: true });
201
+ When(/^(I |we )*select "([^"]*)?" from "([^"]*)?"$/, async function (pronounCase, option, selectName) {
202
+ const loc = selectList(this.page, selectName);
203
+ try {
204
+ await loc.waitFor({ state: 'attached', timeout: 5000 });
205
+ } catch (e) {
206
+ if (!isTimeout(e)) throw e;
207
+ throw failure(this.page, /^[#.[]/.test(selectName)
208
+ ? `No select list matches "${selectName}" after 5 seconds.`
209
+ : `No select list with the label, the name or the id "${selectName}" was found after 5 seconds.`, {
210
+ hint: 'name the select list by the exact text of its label, by its name or its id, or by a CSS selector that starts with #, . or [.',
211
+ });
172
212
  }
173
213
  try {
174
214
  await loc.selectOption({ label: option }, { timeout: 3000 });
175
215
  return;
176
216
  } catch { /* fall through to value-based selection */ }
177
217
  try {
178
- await loc.selectOption(option);
218
+ await loc.selectOption(option, { timeout: 2000 });
179
219
  } catch (e) {
180
- throw friendly(
181
- `Could not select "${option}" from "${selectList}".\n` +
182
- ` ${(e.message || '').split('\n')[0]}\n` +
183
- ` Hints:\n` +
184
- ` - Confirm the option text matches exactly (case-sensitive).\n` +
185
- ` - For value-based selection pass the option's "value" attribute.\n` +
186
- ` - For multi-select, use "additionally select" instead.`
187
- );
220
+ const options = await loc.evaluate((el) => Array.from(el.options || []).map((o) => o.label || o.text)).catch(() => []);
221
+ const listed = options.length ? options.map((o) => `"${o}"`).join(', ') : 'no option';
222
+ if (!isTimeout(e) || options.includes(option)) {
223
+ throw failure(this.page, `Could not select "${option}" from "${selectName}".`, {
224
+ found: listed,
225
+ hint: `${humanize(e)}. A select list that is hidden or disabled cannot be changed.`,
226
+ });
227
+ }
228
+ throw failure(this.page, `The select list "${selectName}" has no option "${option}".`, {
229
+ found: listed,
230
+ hint: 'name the option by its text or by its value, as the page writes it (the letter case counts). For a select list that takes several options, use: I additionally select',
231
+ });
188
232
  }
189
233
  });
190
234
 
@@ -249,6 +293,7 @@ When(/^(I |we )*additionally select "([^"]*)" from "([^"]*)"$/, async function (
249
293
  * Example #2: When we check "Put site into maintenance mode"
250
294
  * Example #3: And I check "#newsletter"
251
295
  * Example #4: And we check ".terms-and-conditions"
296
+ * Example #5: When I check "I agree to the terms"
252
297
  *
253
298
  */
254
299
  When(/^(I |we )*check "([^"]*)?"$/, async function (pronounCase, item) {
@@ -279,6 +324,7 @@ When(/^(I |we )*check "([^"]*)?"$/, async function (pronounCase, item) {
279
324
  * Example #2: When we uncheck "Put site into maintenance mode"
280
325
  * Example #3: And I uncheck "#newsletter"
281
326
  * Example #4: And we uncheck ".terms-and-conditions"
327
+ * Example #5: When I uncheck "Send me the newsletter"
282
328
  *
283
329
  */
284
330
  When(/^(I |we )*uncheck "([^"]*)?"$/, async function (pronounCase, item) {
@@ -309,6 +355,7 @@ When(/^(I |we )*uncheck "([^"]*)?"$/, async function (pronounCase, item) {
309
355
  * Example #2: When I select radio button "female"
310
356
  * Example #3: When I select radio button "#gender-male"
311
357
  * Example #4: When we select radio button "option1"
358
+ * Example #5: And we select radio button "Monthly"
312
359
  *
313
360
  */
314
361
  When(/^(I |we )*select radio button "([^"]*)?"$/, async function (pronounCase, item) {
@@ -1,20 +1,57 @@
1
1
  'use strict';
2
2
 
3
- const { friendly } = require('./webship');
3
+ const { friendly, failure, isTimeout, buildSelector, fillLocator, pageTextLocator } = require('./webship');
4
4
 
5
5
  // Iframe / frame steps backed by Playwright's `frameLocator` API.
6
6
  //
7
7
  // Frames are addressed by CSS selector. Once switched, frame-scoped
8
8
  // interaction steps target the chosen frame instead of the main document.
9
- // Switch back with "I switch to the root document".
9
+ // While an iframe is active, a switch looks for the iframe inside it first,
10
+ // then in the page, so a scenario can go into a nested iframe or across to
11
+ // another iframe of the page. Switch back with "I switch to the root document".
10
12
 
11
13
  const { When, Then } = require('@cucumber/cucumber');
12
- const assert = require('assert');
13
14
 
14
15
  function frameRoot(world) {
15
16
  return world.frame || world.page;
16
17
  }
17
18
 
19
+ /**
20
+ * Make the iframe that `sel` names the active scope. While an iframe is
21
+ * active, an iframe inside it that matches is taken first, else one of the
22
+ * page; both are looked for during up to 5 seconds while the frames load.
23
+ * When neither shows, the iframe of the page is kept, and the next step that
24
+ * acts in it says what is missing.
25
+ *
26
+ * @param {Object} world
27
+ * @param {string} sel - CSS selector of the iframe element.
28
+ */
29
+ async function switchToFrame(world, sel) {
30
+ if (!world._rootPage) world._rootPage = world.page;
31
+ const fromPage = world.page.frameLocator(sel);
32
+ if (world.frame) {
33
+ const nested = world.frame.locator(sel);
34
+ const top = world.page.locator(sel);
35
+ const deadline = Date.now() + 5000;
36
+ for (;;) {
37
+ if (await nested.count().catch(() => 0)) {
38
+ world.frame = world.frame.frameLocator(sel);
39
+ return;
40
+ }
41
+ if (await top.count().catch(() => 0)) break;
42
+ if (Date.now() >= deadline) break;
43
+ await world.page.waitForTimeout(100);
44
+ }
45
+ }
46
+ world.frame = fromPage;
47
+ }
48
+
49
+ function noFrameHint(world) {
50
+ return world.frame
51
+ ? 'The step reads the iframe the scenario switched to last; switch to another one first if the text is there.'
52
+ : 'No iframe is active, so the step read the page: switch to the iframe first (When I switch to iframe "<selector>").';
53
+ }
54
+
18
55
  function explain(action, detail, e) {
19
56
  return friendly({
20
57
  action,
@@ -35,8 +72,7 @@ function explain(action, detail, e) {
35
72
  */
36
73
  When(/^(I |we )*switch to (the )?iframe "([^"]*)"$/, async function (pronoun, theCase, sel) {
37
74
  try {
38
- if (!this._rootPage) this._rootPage = this.page;
39
- this.frame = this.page.frameLocator(sel);
75
+ await switchToFrame(this, sel);
40
76
  } catch (e) {
41
77
  throw explain(`switch to iframe "${sel}"`, `selector tried: ${sel}`, e);
42
78
  }
@@ -54,8 +90,7 @@ When(/^(I |we )*switch to (the )?iframe "([^"]*)"$/, async function (pronoun, th
54
90
  */
55
91
  When(/^(I |we )*switch to iframe with locator "([^"]*)"$/, async function (pronoun, sel) {
56
92
  try {
57
- if (!this._rootPage) this._rootPage = this.page;
58
- this.frame = this.page.frameLocator(sel);
93
+ await switchToFrame(this, sel);
59
94
  } catch (e) {
60
95
  throw explain(`switch to iframe with locator "${sel}"`, `locator: ${sel}`, e);
61
96
  }
@@ -93,8 +128,7 @@ When(/^(I |we )*switch to the root document$/, async function (pronoun) {
93
128
  */
94
129
  When(/^(I |we )*switch to the iframe with title "([^"]*)"$/, async function (pronoun, title) {
95
130
  try {
96
- if (!this._rootPage) this._rootPage = this.page;
97
- this.frame = this.page.frameLocator(`iframe[title="${title}"]`);
131
+ await switchToFrame(this, `iframe[title="${title}"]`);
98
132
  } catch (e) {
99
133
  throw explain(`switch to iframe by title "${title}"`, `selector: iframe[title="${title}"]`, e);
100
134
  }
@@ -112,8 +146,7 @@ When(/^(I |we )*switch to the iframe with title "([^"]*)"$/, async function (pro
112
146
  */
113
147
  When(/^(I |we )*switch to the iframe with name "([^"]*)"$/, async function (pronoun, name) {
114
148
  try {
115
- if (!this._rootPage) this._rootPage = this.page;
116
- this.frame = this.page.frameLocator(`iframe[name="${name}"]`);
149
+ await switchToFrame(this, `iframe[name="${name}"]`);
117
150
  } catch (e) {
118
151
  throw explain(`switch to iframe by name "${name}"`, `selector: iframe[name="${name}"]`, e);
119
152
  }
@@ -150,7 +183,10 @@ When(/^(I |we )*click "([^"]*)" inside the iframe$/, async function (pronoun, te
150
183
  /**
151
184
  * Click an attribute-addressed element inside the active iframe.
152
185
  *
153
- * Tries id, class, name, and data-testid in that order.
186
+ * Tries the same attributes as `I click "…" by attr` on the page: id, class,
187
+ * name, data-testid, data-test-id, data-test, data-cy, aria-label, value,
188
+ * placeholder and title (a text with a space: value, placeholder,
189
+ * aria-label and title); a text that starts with #, . or [ is a CSS selector.
154
190
  *
155
191
  * Example #1: When I click "submit-btn" by attr inside the iframe
156
192
  * Example #2: When I click "cancel" by attr inside the iframe
@@ -162,41 +198,54 @@ When(/^(I |we )*click "([^"]*)" inside the iframe$/, async function (pronoun, te
162
198
  When(/^(I |we )*click "([^"]*)" by attr inside the iframe$/, async function (pronoun, attrValue) {
163
199
  try {
164
200
  const root = frameRoot(this);
165
- await root.locator(`#${attrValue}, .${attrValue}, [name="${attrValue}"], [data-testid="${attrValue}"]`).first().click();
201
+ await root.locator(buildSelector(attrValue)).first().click();
166
202
  } catch (e) {
167
203
  throw friendly({
168
204
  action: `click "${attrValue}" by attribute inside the iframe`,
169
205
  cause: e,
170
- hint: `switch to the iframe first; checked id, class, [name], [data-testid] — none matched.`,
206
+ hint: `switch to the iframe first; checked id, class, name, the test ids, aria-label, value, placeholder and title — none matched.`,
171
207
  });
172
208
  }
173
209
  });
174
210
 
175
211
  /**
176
- * Fill a field inside the active iframe by `[name]` or id.
212
+ * Fill a field inside the active iframe, found by the exact text of its
213
+ * label, by its placeholder, by its name or by its id, like the fill step of
214
+ * the page. A field that is not found within 5 seconds, or that is hidden,
215
+ * disabled or read-only, fails the step with what is wrong.
177
216
  *
178
217
  * Example #1: When I fill in "card_number" with "4242 4242 4242 4242" inside the iframe
179
218
  * Example #2: When I fill in "cvv" with "123" inside the iframe
180
219
  * Example #3: And we fill in "exp_date" with "12/30" inside the iframe
181
220
  * Example #4: When I fill in "email" with "alice@example.com" inside the iframe
182
221
  * Example #5: When I fill in "name" with "Alice" inside the iframe
222
+ * Example #6: When I fill in "Coupon code" with "SAVE10" inside the iframe
183
223
  *
184
224
  */
185
225
  When(/^(I |we )*fill in "([^"]*)" with "([^"]*)" inside the iframe$/, async function (pronoun, field, value) {
226
+ const root = frameRoot(this);
227
+ const q = field.replace(/["\\]/g, '\\$&');
228
+ const loc = root.getByLabel(field, { exact: true })
229
+ .or(root.getByPlaceholder(field, { exact: true }))
230
+ .or(root.locator(`[name="${q}"]`))
231
+ .or(root.locator(`[id="${q}"]`))
232
+ .first();
186
233
  try {
187
- const root = frameRoot(this);
188
- await root.locator(`[name="${field}"], #${field}`).first().fill(value);
234
+ await loc.waitFor({ state: 'attached', timeout: 5000 });
189
235
  } catch (e) {
190
- throw friendly({
191
- action: `fill "${field}" inside the iframe`,
192
- cause: e,
193
- hint: `switch to the iframe first; checked [name] and id — neither matched.`,
236
+ if (!isTimeout(e)) throw e;
237
+ throw failure(this.page, `No field with the label, the placeholder, the name or the id "${field}" was found inside the iframe after 5 seconds.`, {
238
+ hint: `name the field by the exact text of its label, its placeholder, its name or its id. ${noFrameHint(this)}`,
194
239
  });
195
240
  }
241
+ await fillLocator(this.page, loc, value, field);
196
242
  });
197
243
 
198
244
  /**
199
- * Assert visible text exists inside the active iframe.
245
+ * Assert a text is inside the active iframe. The iframe's text is read the
246
+ * way `I should see` reads the page: letter case ignored, white space
247
+ * collapsed, a text inside an element as well as its whole text, the text of
248
+ * hidden elements included. Waits up to 5 seconds for the text to come.
200
249
  *
201
250
  * Example #1: Then I should see "Payment received" inside the iframe
202
251
  * Example #2: Then I should see "Welcome" inside the iframe
@@ -206,13 +255,19 @@ When(/^(I |we )*fill in "([^"]*)" with "([^"]*)" inside the iframe$/, async func
206
255
  *
207
256
  */
208
257
  Then(/^I should see "([^"]*)" inside the iframe$/, async function (text) {
209
- const root = frameRoot(this);
210
- const count = await root.locator(`text="${text}"`).count();
211
- assert.ok(count > 0, `Expected to see "${text}" inside the iframe.`);
258
+ try {
259
+ await pageTextLocator(frameRoot(this), text).waitFor({ state: 'attached', timeout: 5000 });
260
+ } catch (e) {
261
+ if (!isTimeout(e)) throw e;
262
+ throw failure(this.page, `The text "${text}" was not found inside the iframe after 5 seconds.`, {
263
+ hint: `check the spelling; letter case is ignored. ${noFrameHint(this)}`,
264
+ });
265
+ }
212
266
  });
213
267
 
214
268
  /**
215
- * Assert visible text does NOT exist inside the active iframe.
269
+ * Assert a text is NOT inside the active iframe, read as `I should see
270
+ * "…" inside the iframe` reads it. Waits up to 5 seconds for the text to go.
216
271
  *
217
272
  * Example #1: Then I should not see "Error" inside the iframe
218
273
  * Example #2: Then I should not see "Declined" inside the iframe
@@ -222,7 +277,12 @@ Then(/^I should see "([^"]*)" inside the iframe$/, async function (text) {
222
277
  *
223
278
  */
224
279
  Then(/^I should not see "([^"]*)" inside the iframe$/, async function (text) {
225
- const root = frameRoot(this);
226
- const count = await root.locator(`text="${text}"`).count();
227
- assert.strictEqual(count, 0, `Expected NOT to see "${text}" inside the iframe.`);
280
+ try {
281
+ await pageTextLocator(frameRoot(this), text).waitFor({ state: 'detached', timeout: 5000 });
282
+ } catch (e) {
283
+ if (!isTimeout(e)) throw e;
284
+ throw failure(this.page, `The text "${text}" is inside the iframe, but it should not be.`, {
285
+ hint: `the step ignores letter case and reads all the text of the iframe, the text of hidden elements included; it waited 5 seconds for the text to go. ${noFrameHint(this)}`,
286
+ });
287
+ }
228
288
  });
@@ -179,8 +179,10 @@ When(/^(I |we )*set the viewport size to (\d+)x(\d+)$/, async function (pronoun,
179
179
  // ---------------------------------------------------------------------------
180
180
 
181
181
  /**
182
- * Touch-tap a CSS-addressed element. Falls back to a regular click if the
183
- * browser context was not opened with `hasTouch: true`.
182
+ * Touch-tap a CSS-addressed element. A scenario tagged @touch opens with
183
+ * touch on, so the tap fires the touch events (touchstart, touchend) a
184
+ * mobile control listens to. Without touch the browser context cannot tap:
185
+ * the step clicks instead and says so once per scenario.
184
186
  *
185
187
  * Example #1: When I tap on "#cta"
186
188
  * Example #2: When I tap on ".bottom-nav-item"
@@ -190,13 +192,30 @@ When(/^(I |we )*set the viewport size to (\d+)x(\d+)$/, async function (pronoun,
190
192
  *
191
193
  */
192
194
  When(/^(I |we )*tap on "([^"]*)"$/, async function (pronoun, sel) {
195
+ const target = this.page.locator(sel).first();
193
196
  try {
194
- await this.page.locator(sel).first().tap();
197
+ await target.tap();
198
+ return;
195
199
  } catch (e) {
196
- if (/hasTouch/i.test(e.message)) {
197
- await this.page.locator(sel).first().click();
198
- } else {
199
- throw e;
200
+ if (!/hasTouch/i.test(e.message)) {
201
+ throw friendly({
202
+ action: `tap on "${sel}"`,
203
+ cause: e,
204
+ hint: 'the selector is a CSS selector; check that the element is on the page and visible.',
205
+ });
200
206
  }
201
207
  }
208
+ if (!this.__tapAsClickNoted) {
209
+ this.__tapAsClickNoted = true;
210
+ process.stderr.write(`\n[webship-js] "tap on" clicked "${sel}": this browser context has no touch. Tag the scenario @touch for a real tap.\n`);
211
+ }
212
+ try {
213
+ await target.click();
214
+ } catch (e) {
215
+ throw friendly({
216
+ action: `tap on "${sel}"`,
217
+ cause: e,
218
+ hint: 'the selector is a CSS selector; check that the element is on the page and visible.',
219
+ });
220
+ }
202
221
  });