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
@@ -9,8 +9,7 @@
9
9
  // Modal assertions live in modal.steps.js.
10
10
 
11
11
  const { Then } = require('@cucumber/cucumber');
12
- const assert = require('assert');
13
- const { buildSelector, getLocatorText, friendly } = require('./webship');
12
+ const { buildSelector, getLocatorText, locateByLabelOrSelector, failure, excerpt, isTimeout, pageTextLocator } = require('./webship');
14
13
  const { getLastResponse } = require('./response.steps');
15
14
 
16
15
  // ---------------------------------------------------------------------------
@@ -18,20 +17,77 @@ const { getLastResponse } = require('./response.steps');
18
17
  // ---------------------------------------------------------------------------
19
18
 
20
19
  /**
21
- * Assert that text is or is not present on the page.
20
+ * Where a text is on the page, for a failure message: the excerpt of the
21
+ * element that holds it, the element, and whether a visitor can see it.
22
+ *
23
+ * @param {import('playwright').Page} page
24
+ * @param {string} text
25
+ * @returns {Promise<string|undefined>} undefined when it cannot be told.
26
+ */
27
+ async function whereTextIs(page, text) {
28
+ try {
29
+ const match = page.locator('body').getByText(text).first();
30
+ if (!(await match.count())) return undefined;
31
+ const info = await match.evaluate((el) => ({
32
+ tag: el.tagName.toLowerCase(),
33
+ id: el.id || '',
34
+ cls: typeof el.className === 'string' ? el.className.trim().split(/\s+/)[0] : '',
35
+ text: el.textContent || el.value || '',
36
+ }), null, { timeout: 1000 });
37
+ const visible = await match.isVisible().catch(() => true);
38
+ const attr = info.id ? ` id="${info.id}"` : info.cls ? ` class="${info.cls}"` : '';
39
+ return `"${excerpt(info.text, 80)}" in ${visible ? '' : 'a hidden '}<${info.tag}${attr}>`;
40
+ } catch {
41
+ return undefined;
42
+ }
43
+ }
44
+
45
+ /**
46
+ * Assert that a text is, or is not, on the page.
47
+ *
48
+ * Both polarities read the page the same way, as `eventually I should see`
49
+ * does: the text of the page as Playwright's text matching reads it, letter
50
+ * case ignored, runs of white space collapsed, the text of hidden elements
51
+ * included, the text of `<script>` and `<style>` left out. On a page that
52
+ * reads "Next page", `I should see "next page"` passes and `I should not see
53
+ * "next page"` fails. "should see" waits up to 5 seconds for the text to
54
+ * come, "should not see" up to 5 seconds for it to go.
55
+ *
56
+ * For the text a visitor can see, with its letter case, use `I wait for the
57
+ * text "..." to appear` or `... to disappear`; for an element,
58
+ * `"<selector>" should be visible`.
22
59
  *
23
60
  * Example #1: Then I should see "Welcome"
24
61
  * Example #2: Then we should see "Your accounts for the group is public"
25
62
  * Example #3: Then I should not see "Access denied"
26
63
  * Example #4: Then we should not see "Edit layout"
64
+ * Example #5: When I press "Save"
65
+ * Then I should see "Saved"
66
+ * And I should not see "Saving"
27
67
  *
28
68
  */
29
69
  Then(/^(I |we )*should( not)* see "([^"]*)?"$/, async function (pronounCase, notCase, expectedText) {
70
+ const text = expectedText === undefined || expectedText === null ? '' : expectedText;
71
+ const onPage = pageTextLocator(this.page, text);
30
72
  if (notCase) {
31
- const text = await this.page.locator('body').textContent() || '';
32
- assert.ok(!text.includes(expectedText), `Page should NOT contain "${expectedText}" but it does.`);
73
+ try {
74
+ await onPage.waitFor({ state: 'detached', timeout: 5000 });
75
+ } catch (e) {
76
+ if (!isTimeout(e)) throw e;
77
+ throw failure(this.page, `The text "${text}" is on the page, but it should not be.`, {
78
+ found: await whereTextIs(this.page, text),
79
+ hint: `the step ignores letter case and reads all the text of the page, the text of hidden elements included (not the text of <script> or <style>); it waited 5 seconds for the text to go. To check only the text a visitor can see, with its letter case, use: I wait for the text "${text}" to disappear`,
80
+ });
81
+ }
33
82
  } else {
34
- await this.page.locator('body').filter({ hasText: expectedText }).waitFor({ timeout: 5000 });
83
+ try {
84
+ await onPage.waitFor({ state: 'attached', timeout: 5000 });
85
+ } catch (e) {
86
+ if (!isTimeout(e)) throw e;
87
+ throw failure(this.page, `The text "${text}" was not found on the page after 5 seconds.`, {
88
+ hint: `check the spelling; letter case is ignored and the text of hidden elements counts. The value of a field, an image and the content of an iframe are not page text. For a text that arrives late, use: eventually I should see "${text}" within 30 seconds`,
89
+ });
90
+ }
35
91
  }
36
92
  });
37
93
 
@@ -41,15 +97,31 @@ Then(/^(I |we )*should( not)* see "([^"]*)?"$/, async function (pronounCase, not
41
97
  * Example #1: Then I should see text matching "^T\w+"
42
98
  * Example #2: Then I should not see text matching "^O\w+"
43
99
  * Example #3: And we should see text matching "\d{4}"
100
+ * Example #4: Then I should see text matching "[0-9]+ items?"
101
+ * Example #5: Then we should not see text matching "Error [0-9]{3}"
44
102
  *
45
103
  */
46
104
  Then(/^(I |we )*should( not)* see text matching "([^"]*)?"$/, async function (pronounCase, notCase, textPattern) {
47
105
  const bodyText = await this.page.evaluate(() => document.body.innerText || '');
48
- const regex = new RegExp(textPattern);
49
- if (notCase) {
50
- assert.ok(!regex.test(bodyText), `Page text should NOT match "${textPattern}" but it does.`);
51
- } else {
52
- assert.ok(regex.test(bodyText), `Page text should match "${textPattern}" but it does not.`);
106
+ let regex;
107
+ try {
108
+ regex = new RegExp(textPattern);
109
+ } catch (e) {
110
+ throw failure(this.page, `"${textPattern}" is not a valid regular expression: ${e.message}`, {
111
+ hint: 'escape the characters that have a meaning in a regular expression, such as ( ) [ ] ? + * and .',
112
+ });
113
+ }
114
+ const match = regex.exec(bodyText);
115
+ if (notCase && match) {
116
+ throw failure(this.page, `The text of the page matches "${textPattern}", but it should not.`, {
117
+ found: `"${excerpt(match[0])}"`,
118
+ hint: 'the pattern is a regular expression tried against the visible text of the whole page.',
119
+ });
120
+ }
121
+ if (!notCase && !match) {
122
+ throw failure(this.page, `No text of the page matches "${textPattern}".`, {
123
+ hint: 'the pattern is a regular expression tried against the visible text of the whole page; ^ and $ stand for the start and the end of that whole text.',
124
+ });
53
125
  }
54
126
  });
55
127
 
@@ -74,10 +146,19 @@ Then(/^(I |we )*should( not)* see "([^"]*)?" in( the)* "([^"]*)?" row$/, async f
74
146
  const rows = Array.from(document.querySelectorAll('tr'));
75
147
  return rows.filter(r => r.textContent.includes(id)).some(r => r.textContent.includes(text));
76
148
  }, { id: rowIdentifier, text: expectedText });
77
- if (notCase) {
78
- assert.ok(!found, `Found "${expectedText}" in the "${rowIdentifier}" row, but it should not be there.`);
79
- } else {
80
- assert.ok(found, `Could not find "${expectedText}" in the "${rowIdentifier}" row.`);
149
+ if (notCase && found) {
150
+ throw failure(this.page, `The "${rowIdentifier}" row contains "${expectedText}", but it should not.`, {
151
+ hint: `the row is every table row whose text contains "${rowIdentifier}".`,
152
+ });
153
+ }
154
+ if (!notCase && !found) {
155
+ const rows = await this.page.locator('tr').filter({ hasText: rowIdentifier }).count();
156
+ throw failure(this.page, rows
157
+ ? `The "${rowIdentifier}" row does not contain "${expectedText}".`
158
+ : `No table row contains "${rowIdentifier}", so "${expectedText}" could not be looked for in it.`, {
159
+ found: rows ? `"${excerpt(await this.page.locator('tr').filter({ hasText: rowIdentifier }).first().textContent())}"` : undefined,
160
+ hint: 'check the spelling and the letter case of both texts; the step reads the table rows that are on the page now.',
161
+ });
81
162
  }
82
163
  });
83
164
 
@@ -85,6 +166,32 @@ Then(/^(I |we )*should( not)* see "([^"]*)?" in( the)* "([^"]*)?" row$/, async f
85
166
  // Element existence + content
86
167
  // ---------------------------------------------------------------------------
87
168
 
169
+ // Tag names a tester may write where a step reads a text.
170
+ const TAG_NAMES = new Set([
171
+ 'a', 'article', 'aside', 'body', 'button', 'dialog', 'div', 'footer', 'form',
172
+ 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'header', 'iframe', 'img', 'input',
173
+ 'label', 'li', 'main', 'nav', 'ol', 'p', 'section', 'select', 'span', 'table',
174
+ 'tbody', 'td', 'textarea', 'th', 'thead', 'tr', 'ul', 'video',
175
+ ]);
176
+
177
+ /**
178
+ * True when a step argument reads like a CSS selector rather than a text: it
179
+ * starts with `.`, `#` or `[`, holds selector syntax (`div.card`,
180
+ * `input[name=q]`, `li:first-child`, `ul > li`), is an XPath, or is a bare tag
181
+ * name such as `header`. Used for hints only.
182
+ *
183
+ * @param {string} value
184
+ * @returns {boolean}
185
+ */
186
+ function looksLikeSelector(value) {
187
+ const v = String(value === undefined || value === null ? '' : value).trim();
188
+ if (!v) return false;
189
+ if (/^(?:\/\/|xpath=|css=)/.test(v)) return true;
190
+ const parts = v.split(/\s*[>+~]\s*|\s+/).filter(Boolean);
191
+ const simple = /^(?:[a-z][a-z0-9-]*)?(?:[.#][A-Za-z_-][\w-]*|\[[^\]]+\]|::?[a-z-]+(?:\([^)]*\))?)*$/;
192
+ return parts.every((part) => simple.test(part) && (/[.#[:]/.test(part) || TAG_NAMES.has(part)));
193
+ }
194
+
88
195
  /**
89
196
  * Assert that an element is, or is not, visible on the page. The element is
90
197
  * named by its exact visible text; a `<label for="...">` stands for the
@@ -94,6 +201,10 @@ Then(/^(I |we )*should( not)* see "([^"]*)?" in( the)* "([^"]*)?" row$/, async f
94
201
  * "should not see" is the opposite of "should see": it passes when no element
95
202
  * named that way is visible, so an element that is hidden does not fail it.
96
203
  *
204
+ * An argument that looks like a selector (`.news-item`, `#main`, `header`) is
205
+ * still read as a text: a failure says so, and the negative prints a warning
206
+ * when it passes while that selector matches a visible element.
207
+ *
97
208
  * Example #1: Then I should see a "Username" element
98
209
  * Example #2: Then I should not see a "Username" element
99
210
  * Example #3: And we should see an "Email" element
@@ -110,15 +221,38 @@ Then(/^(I |we )*should( not)* see (a|an) "([^"]*)?" element$/, async function (p
110
221
  const target = forIds[i]
111
222
  ? this.page.locator(`[id="${forIds[i].replace(/["\\]/g, '\\$&')}"]`).first()
112
223
  : named.nth(i);
113
- assert.ok(!(await target.isVisible()), `Element "${element}" should NOT be visible but it is.`);
224
+ if (await target.isVisible()) {
225
+ throw failure(this.page, `The element "${element}" is visible, but it should not be.`, {
226
+ hint: 'this step finds an element by its exact visible text or by its label.',
227
+ });
228
+ }
229
+ }
230
+ if (looksLikeSelector(element) && await this.page.locator(element).first().isVisible().catch(() => false)) {
231
+ console.warn(`\x1b[33m[webship-js] I should not see a "${element}" element: passed, because no element reads "${element}". It looks like a CSS selector, and that selector matches a visible element; this step reads a text. For a selector, use: "${element}" should not be visible\x1b[0m`);
114
232
  }
115
233
  } else {
234
+ const hint = looksLikeSelector(element)
235
+ ? `"${element}" looks like a CSS selector, but this step reads it as the exact text of an element or of a label. For a selector, use: "${element}" should be visible`
236
+ : `this step finds an element by its exact visible text or by its label. To find it by its id, class, name or another attribute, use: I should see a "${element}" element by attr`;
116
237
  const loc = this.page.getByText(element, { exact: true }).first();
238
+ try {
239
+ await loc.waitFor({ state: 'attached', timeout: 3000 });
240
+ } catch (e) {
241
+ if (!isTimeout(e)) throw e;
242
+ throw failure(this.page, `No element with the text or the label "${element}" was found after 3 seconds.`, { hint });
243
+ }
117
244
  const forAttr = await loc.getAttribute('for').catch(() => null);
118
- if (forAttr) {
119
- await this.page.locator('#' + forAttr).waitFor({ state: 'visible', timeout: 3000 });
120
- } else {
121
- await loc.waitFor({ state: 'visible', timeout: 3000 });
245
+ try {
246
+ if (forAttr) {
247
+ await this.page.locator('#' + forAttr).waitFor({ state: 'visible', timeout: 3000 });
248
+ } else {
249
+ await loc.waitFor({ state: 'visible', timeout: 3000 });
250
+ }
251
+ } catch (e) {
252
+ if (!isTimeout(e)) throw e;
253
+ throw failure(this.page, forAttr
254
+ ? `The field of the label "${element}" (#${forAttr}) is not visible after 3 seconds.`
255
+ : `The element "${element}" is on the page but not visible after 3 seconds.`, { hint });
122
256
  }
123
257
  }
124
258
  });
@@ -130,34 +264,68 @@ Then(/^(I |we )*should( not)* see (a|an) "([^"]*)?" element$/, async function (p
130
264
  * Example #2: Then I should see a "pwordcss" element by attr
131
265
  * Example #3: Then I should not see an "emailId" element by its "id" attr
132
266
  * Example #4: And I should not see a "countryCss" element by attr
267
+ * Example #5: Then we should see a "search-box" element by its "data-testid" attribute
133
268
  *
134
269
  */
135
270
  Then(/^(I |we )*should( not)* see (a|an) "([^"]*)?" element by( its)*(?: "([^"]*)?")* (attribute|attr)$/, async function (pronounCase, notCase, aAnCase, attrValue, itsCase, attr, attrWord) {
136
- const loc = this.page.locator(buildSelector(attrValue, attr));
271
+ const selector = buildSelector(attrValue, attr);
272
+ const loc = this.page.locator(selector);
137
273
  if (notCase) {
138
- assert.strictEqual(await loc.count(), 0, `Element should NOT be present but it is.`);
274
+ const count = await loc.count();
275
+ if (count > 0) {
276
+ throw failure(this.page, `An element with "${attrValue}" is on the page, but it should not be.`, {
277
+ found: `${count} element(s)`,
278
+ hint: attr
279
+ ? `the step looked for an element whose "${attr}" attribute is "${attrValue}"; a hidden element counts too.`
280
+ : `without a named attribute the step tries "${attrValue}" as an id, a class, a name, a test id, an aria-label, a value, a placeholder and a title; a hidden element counts too.`,
281
+ });
282
+ }
139
283
  } else {
140
- await loc.first().waitFor({ state: 'visible', timeout: 3000 });
284
+ try {
285
+ await loc.first().waitFor({ state: 'visible', timeout: 3000 });
286
+ } catch (e) {
287
+ if (!isTimeout(e)) throw e;
288
+ const count = await loc.count().catch(() => 0);
289
+ throw failure(this.page, count
290
+ ? `The element with "${attrValue}" is on the page but not visible after 3 seconds.`
291
+ : `No element with "${attrValue}" was found after 3 seconds.`, {
292
+ hint: attr
293
+ ? `the step looked for an element whose "${attr}" attribute is "${attrValue}".`
294
+ : `without a named attribute the step tries "${attrValue}" as an id, a class, a name, a test id, an aria-label, a value, a placeholder and a title.`,
295
+ });
296
+ }
141
297
  }
142
298
  });
143
299
 
144
300
  /**
145
- * Assert that an element (found by its label) contains or does not contain text.
301
+ * Assert that an element contains or does not contain text. The element is
302
+ * named by the exact text of its label, or by a CSS selector.
146
303
  *
147
304
  * Example #1: Then I should see "John Smith" in the "Username" element
148
305
  * Example #2: Then I should not see "Joe Smith" in the "Username" element
149
306
  * Example #3: And we should see "1234" in the "Password" element
307
+ * Example #4: Then I should see "About Us" in the "h1" element
308
+ * Example #5: Then we should not see "Error" in the "#status" element
150
309
  *
151
310
  */
152
311
  Then(/^(I |we )*should( not)* see "([^"]*)?" in( the)* "([^"]*)?" element$/, async function (pronounCase, notCase, expectedText, theCase, element) {
153
- const forAttr = await this.page.getByText(element, { exact: true }).getAttribute('for').catch(() => null);
154
- const loc = this.page.locator(forAttr ? '#' + forAttr : element).first();
155
- await loc.waitFor({ timeout: 5000 });
312
+ const loc = await locateByLabelOrSelector(this.page, element, 5000);
313
+ if (!loc) {
314
+ throw failure(this.page, `The element "${element}" was not found on the page after 5 seconds.`, {
315
+ hint: `"${element}" is read as the exact text of a label, else as a CSS selector. To find an element by its id, class, name or another attribute, add "by attr" to the step.`,
316
+ });
317
+ }
156
318
  const content = await getLocatorText(loc);
157
- if (notCase) {
158
- assert.ok(!content.includes(expectedText), `Element should NOT contain "${expectedText}" but it does.`);
159
- } else {
160
- assert.ok(content.includes(expectedText), `Element should contain "${expectedText}" but it does not.`);
319
+ if (notCase && content.includes(expectedText)) {
320
+ throw failure(this.page, `The element "${element}" contains "${expectedText}", but it should not.`, {
321
+ found: `"${excerpt(content)}"`,
322
+ });
323
+ }
324
+ if (!notCase && !content.includes(expectedText)) {
325
+ throw failure(this.page, `The element "${element}" does not contain "${expectedText}".`, {
326
+ found: `"${excerpt(content)}"`,
327
+ hint: 'check the spelling and the letter case; for a field the step reads its value.',
328
+ });
161
329
  }
162
330
  });
163
331
 
@@ -168,16 +336,32 @@ Then(/^(I |we )*should( not)* see "([^"]*)?" in( the)* "([^"]*)?" element$/, asy
168
336
  * Example #2: Then I should see "1234" in the "pwordcss" element by attr
169
337
  * Example #3: Then I should not see "John Smith" in the "uname" element by its "id" attr
170
338
  * Example #4: Then I should not see "1234" in the "pwordcss" element by attr
339
+ * Example #5: Then we should see "Welcome" in the "greeting" element by its "class" attribute
171
340
  *
172
341
  */
173
342
  Then(/^(I |we )*should( not)* see "([^"]*)?" in( the)* "([^"]*)?" element by( its)*(?: "([^"]*)?")* (attribute|attr)$/, async function (pronounCase, notCase, expectedText, theCase, attrValue, itsCase, attr, attrWord) {
174
343
  const loc = this.page.locator(buildSelector(attrValue, attr)).first();
175
- await loc.waitFor({ timeout: 10000 });
344
+ try {
345
+ await loc.waitFor({ timeout: 10000 });
346
+ } catch (e) {
347
+ if (!isTimeout(e)) throw e;
348
+ throw failure(this.page, `No visible element with "${attrValue}" was found after 10 seconds, so "${expectedText}" could not be looked for in it.`, {
349
+ hint: attr
350
+ ? `the step looked for an element whose "${attr}" attribute is "${attrValue}".`
351
+ : `without a named attribute the step tries "${attrValue}" as an id, a class, a name, a test id, an aria-label, a value, a placeholder and a title.`,
352
+ });
353
+ }
176
354
  const content = await getLocatorText(loc);
177
- if (notCase) {
178
- assert.ok(!content.includes(expectedText), `Element should NOT contain "${expectedText}" but it does.`);
179
- } else {
180
- assert.ok(content.includes(expectedText), `Element should contain "${expectedText}" but it does not.`);
355
+ if (notCase && content.includes(expectedText)) {
356
+ throw failure(this.page, `The element with "${attrValue}" contains "${expectedText}", but it should not.`, {
357
+ found: `"${excerpt(content)}"`,
358
+ });
359
+ }
360
+ if (!notCase && !content.includes(expectedText)) {
361
+ throw failure(this.page, `The element with "${attrValue}" does not contain "${expectedText}".`, {
362
+ found: `"${excerpt(content)}"`,
363
+ hint: 'check the spelling and the letter case; for a field the step reads its value.',
364
+ });
181
365
  }
182
366
  });
183
367
 
@@ -192,14 +376,34 @@ Then(/^(I |we )*should( not)* see "([^"]*)?" in( the)* "([^"]*)?" element by( it
192
376
  *
193
377
  */
194
378
  Then(/^(I |we )*should( not)* see text matching "([^"]*)?" in( the)* "([^"]*)?" element$/, async function (pronounCase, notCase, textPattern, theCase, element) {
379
+ let regex;
380
+ try {
381
+ regex = new RegExp(textPattern);
382
+ } catch (e) {
383
+ throw failure(this.page, `"${textPattern}" is not a valid regular expression: ${e.message}`, {
384
+ hint: 'escape the characters that have a meaning in a regular expression, such as ( ) [ ] ? + * and .',
385
+ });
386
+ }
195
387
  const loc = this.page.locator(element).first();
196
- await loc.waitFor({ timeout: 5000 });
388
+ try {
389
+ await loc.waitFor({ timeout: 5000 });
390
+ } catch (e) {
391
+ if (!isTimeout(e)) throw e;
392
+ throw failure(this.page, `No visible element matches "${element}" after 5 seconds, so its text could not be read.`, {
393
+ hint: `"${element}" is a CSS selector here.`,
394
+ });
395
+ }
197
396
  const text = await getLocatorText(loc);
198
- const regex = new RegExp(textPattern);
199
- if (notCase) {
200
- assert.ok(!regex.test(text), `Element "${element}" text should NOT match "${textPattern}" but it does.`);
201
- } else {
202
- assert.ok(regex.test(text), `Element "${element}" text should match "${textPattern}" but it does not.`);
397
+ if (notCase && regex.test(text)) {
398
+ throw failure(this.page, `The text of the element "${element}" matches "${textPattern}", but it should not.`, {
399
+ found: `"${excerpt(text)}"`,
400
+ });
401
+ }
402
+ if (!notCase && !regex.test(text)) {
403
+ throw failure(this.page, `The text of the element "${element}" does not match "${textPattern}".`, {
404
+ found: `"${excerpt(text)}"`,
405
+ hint: 'the pattern is a regular expression; for a field the step reads its value.',
406
+ });
203
407
  }
204
408
  });
205
409
 
@@ -210,6 +414,7 @@ Then(/^(I |we )*should( not)* see text matching "([^"]*)?" in( the)* "([^"]*)?"
210
414
  * Example #2: Then the "body" element should not contain "color:white;"
211
415
  * Example #3: Then the "#uname" element should not contain "border:solid 5px red;"
212
416
  * Example #4: Then the "pword" element should not contain "font-size: 26px;"
417
+ * Example #5: Then the "h1" element should contain "font-weight: 700"
213
418
  *
214
419
  */
215
420
  Then(/^(the )*"([^"]*)?" element should( not)* contain "([^"]*)?"$/, async function (theCase, selectorRaw, notCase, elementCss) {
@@ -219,8 +424,15 @@ Then(/^(the )*"([^"]*)?" element should( not)* contain "([^"]*)?"$/, async funct
219
424
  const expectedValue = cssClean.substring(colonIdx + 1).trim();
220
425
 
221
426
  const loc = this.page.locator(buildSelector(selectorRaw)).first();
222
- await loc.waitFor({ timeout: 10000 });
223
- const matches = await loc.evaluate((el, { prop, expectedVal }) => {
427
+ try {
428
+ await loc.waitFor({ timeout: 10000 });
429
+ } catch (e) {
430
+ if (!isTimeout(e)) throw e;
431
+ throw failure(this.page, `No visible element with "${selectorRaw}" was found after 10 seconds, so its CSS could not be read.`, {
432
+ hint: `the step tries "${selectorRaw}" as an id, a class, a name, a test id, an aria-label, a value, a placeholder and a title.`,
433
+ });
434
+ }
435
+ const { matches, computed } = await loc.evaluate((el, { prop, expectedVal }) => {
224
436
  function colorToRgb(color) {
225
437
  const canvas = document.createElement('canvas');
226
438
  canvas.width = canvas.height = 1;
@@ -243,14 +455,23 @@ Then(/^(the )*"([^"]*)?" element should( not)* contain "([^"]*)?"$/, async funct
243
455
  return tokens;
244
456
  }
245
457
  const computed = window.getComputedStyle(el).getPropertyValue(prop).trim();
246
- return tokenize(normalizeColorTokens(expectedVal.toLowerCase()))
247
- .every(token => normalizeColorTokens(computed.toLowerCase()).includes(token));
458
+ return {
459
+ computed,
460
+ matches: tokenize(normalizeColorTokens(expectedVal.toLowerCase()))
461
+ .every(token => normalizeColorTokens(computed.toLowerCase()).includes(token)),
462
+ };
248
463
  }, { prop: cssProperty, expectedVal: expectedValue });
249
464
 
250
- if (notCase) {
251
- assert.ok(!matches, `Element should NOT have CSS "${cssProperty}: ${expectedValue}" but it does.`);
252
- } else {
253
- assert.ok(matches, `Element should have CSS "${cssProperty}: ${expectedValue}".`);
465
+ if (notCase && matches) {
466
+ throw failure(this.page, `The element "${selectorRaw}" has the CSS "${cssProperty}: ${expectedValue}", but it should not.`, {
467
+ found: `${cssProperty}: ${computed}`,
468
+ });
469
+ }
470
+ if (!notCase && !matches) {
471
+ throw failure(this.page, `The element "${selectorRaw}" does not have the CSS "${cssProperty}: ${expectedValue}".`, {
472
+ found: `${cssProperty}: ${computed || '(no value)'}`,
473
+ hint: 'the step compares with the computed style, where a colour is written as rgb(…) and a length in pixels.',
474
+ });
254
475
  }
255
476
  });
256
477
 
@@ -272,7 +493,9 @@ Then(/^(I |we )*should see (\d+) "([^"]*)" elements?$/, async function (pronounC
272
493
  const expected = parseInt(num, 10);
273
494
  const actual = await this.page.locator(selector).count();
274
495
  if (actual !== expected) {
275
- throw friendly(`Expected ${expected} "${selector}" element(s), got ${actual}.`);
496
+ throw failure(this.page, `Expected ${expected} "${selector}" element(s), got ${actual}.`, {
497
+ hint: `"${selector}" is a CSS selector; hidden elements count too.`,
498
+ });
276
499
  }
277
500
  });
278
501
 
@@ -286,13 +509,27 @@ Then(/^(I |we )*should see (\d+) "([^"]*)" elements?$/, async function (pronounC
286
509
  * Example #1: Then the "Login" link should contain "/log-in"
287
510
  * Example #2: And the "About Us" link should contain "/about"
288
511
  * Example #3: Then "Home" link should contain "/"
512
+ * Example #4: Then the "Contact Us" link should contain "/contact"
513
+ * Example #5: And "Privacy policy" link should contain "privacy"
289
514
  *
290
515
  */
291
516
  Then(/^(the )*"([^"]*)?" link should contain "([^"]*)?"$/, async function (theCase, element, url) {
292
517
  const loc = this.page.getByText(element, { exact: true }).first();
293
- await loc.waitFor({ timeout: 5000 });
518
+ try {
519
+ await loc.waitFor({ timeout: 5000 });
520
+ } catch (e) {
521
+ if (!isTimeout(e)) throw e;
522
+ throw failure(this.page, `No visible link with the text "${element}" was found after 5 seconds.`, {
523
+ hint: `the step finds the link by its exact text. To find it by its id, class, title or another attribute, add "by attr" to the step.`,
524
+ });
525
+ }
294
526
  const href = await loc.evaluate(el => el.href || el.getAttribute('href') || '');
295
- assert.ok(href.includes(url), `Expected link "${element}" href to contain "${url}" but got "${href}"`);
527
+ if (!href.includes(url)) {
528
+ throw failure(this.page, `The address of the link "${element}" does not contain "${url}".`, {
529
+ found: href ? `"${href}"` : 'the element has no address (no href)',
530
+ hint: 'the step reads the full address the link leads to, with the domain.',
531
+ });
532
+ }
296
533
  });
297
534
 
298
535
  /**
@@ -301,13 +538,29 @@ Then(/^(the )*"([^"]*)?" link should contain "([^"]*)?"$/, async function (theCa
301
538
  * Example #1: Then the "#about-us-id" link should contain "about" by attr
302
539
  * Example #2: And the "aboutUs" link should contain "about" by its "class" attribute
303
540
  * Example #3: And the ".contactUs" link should contain "/contact-" by attr
541
+ * Example #4: Then the "nav-home" link should contain "/" by its "id" attribute
542
+ * Example #5: And the "footer-link" link should contain "https://" by attr
304
543
  *
305
544
  */
306
545
  Then(/^(the )*"([^"]*)?" link should contain "([^"]*)?" by( its)*(?: "([^"]*)?")* (attribute|attr)$/, async function (theCase, attrValue, url, itsCase, attr, attrWord) {
307
546
  const loc = this.page.locator(buildSelector(attrValue, attr)).first();
308
- await loc.waitFor({ timeout: 5000 });
547
+ try {
548
+ await loc.waitFor({ timeout: 5000 });
549
+ } catch (e) {
550
+ if (!isTimeout(e)) throw e;
551
+ throw failure(this.page, `No visible link with "${attrValue}" was found after 5 seconds.`, {
552
+ hint: attr
553
+ ? `the step looked for an element whose "${attr}" attribute is "${attrValue}".`
554
+ : `without a named attribute the step tries "${attrValue}" as an id, a class, a name, a test id, an aria-label, a value, a placeholder and a title.`,
555
+ });
556
+ }
309
557
  const href = await loc.evaluate(el => el.href || el.getAttribute('href') || '');
310
- assert.ok(href.includes(url), `Expected element href to contain "${url}" but got "${href}"`);
558
+ if (!href.includes(url)) {
559
+ throw failure(this.page, `The address of the link with "${attrValue}" does not contain "${url}".`, {
560
+ found: href ? `"${href}"` : 'the element has no address (no href)',
561
+ hint: 'the step reads the full address the link leads to, with the domain.',
562
+ });
563
+ }
311
564
  });
312
565
 
313
566
  // ---------------------------------------------------------------------------
@@ -331,10 +584,16 @@ Then(/^(the )*"([^"]*)?" link should contain "([^"]*)?" by( its)*(?: "([^"]*)?")
331
584
  */
332
585
  Then(/^(the )*response should( not)* contain "([^"]*)?"$/, async function (theCase, notCase, expectedText) {
333
586
  const text = await this.page.locator('html').textContent() || '';
334
- if (notCase) {
335
- assert.ok(!text.includes(expectedText), `Response should NOT contain "${expectedText}" but it does.`);
336
- } else {
337
- assert.ok(text.includes(expectedText), `Response should contain "${expectedText}" but it does not.`);
587
+ if (notCase && text.includes(expectedText)) {
588
+ throw failure(this.page, `The response contains "${expectedText}", but it should not.`, {
589
+ hint: 'this step reads all the text of the document, the text that is hidden included.',
590
+ });
591
+ }
592
+ if (!notCase && !text.includes(expectedText)) {
593
+ throw failure(this.page, `The response does not contain "${expectedText}".`, {
594
+ found: `"${excerpt(text)}"`,
595
+ hint: 'this step reads the text of the document the browser shows, not its HTML source.',
596
+ });
338
597
  }
339
598
  });
340
599
 
@@ -355,9 +614,14 @@ Then(/^(the )*response should( not)* contain "([^"]*)?"$/, async function (theCa
355
614
  Then(/^(the )*response status code should( not)* be (\d+)$/, async function (theCase, notCase, expectedStatusCode) {
356
615
  const expected = parseInt(expectedStatusCode, 10);
357
616
  const { status } = await getLastResponse(this);
358
- if (notCase) {
359
- assert.notStrictEqual(status, expected, `Status code should NOT be ${expected}`);
360
- } else {
361
- assert.strictEqual(status, expected, `Expected status ${expected} but got ${status}`);
617
+ if (notCase && status === expected) {
618
+ throw failure(this.page, `The response status code is ${expected}, but it should not be.`, {
619
+ hint: 'the step reads the status of the document the browser shows now.',
620
+ });
621
+ }
622
+ if (!notCase && status !== expected) {
623
+ throw failure(this.page, `Expected the response status code ${expected}, got ${status}.`, {
624
+ hint: 'the step reads the status of the document the browser shows now.',
625
+ });
362
626
  }
363
627
  });
@@ -57,9 +57,12 @@ When(/^(I |we )*save the auth state to "([^"]*)"$/, async function (pronoun, tar
57
57
  * Restore cookies + localStorage from a previously saved JSON file.
58
58
  *
59
59
  * The current browser context is closed and a fresh one is opened with the
60
- * saved state. The webship-js init script (AJAX/timer/mutation tracker) is
61
- * re-installed automatically so smart waits keep working. Subsequent steps
62
- * proceed against the restored, authenticated session.
60
+ * saved state, through the same path as the first one of the scenario: the
61
+ * smart waits (the AJAX / timer / mutation tracker), the viewport of an
62
+ * @mobile / @desktop tag, video recording while it is on, JavaScript-error
63
+ * capture, the response tracker and a running request log all go on with
64
+ * the new page. The page starts blank: open the page you need next. Routes
65
+ * stubbed before this step belong to the closed context: stub them after it.
63
66
  *
64
67
  * Example #1: Given I restore the auth state from "tests/auth/admin.json"
65
68
  * Example #2: Given I restore the auth state from "tests/auth/editor.json"
@@ -77,21 +80,15 @@ Given(/^(I |we )*restore the auth state from "([^"]*)"$/, async function (pronou
77
80
  if (!fs.existsSync(file)) {
78
81
  throw friendly(`Auth state file not found: ${file}`);
79
82
  }
80
- const playwrightConfig = require(path.join(process.cwd(), 'playwright.config'));
81
- const newContext = await this.playwrightBrowser.newContext({
82
- ...playwrightConfig.contextOptions,
83
- storageState: file,
84
- });
85
- await newContext.addInitScript(() => {
86
- if (window.__webshipAjaxInstalled) return;
87
- window.__webshipAjaxInstalled = true;
88
- window.__webshipAjaxCount = 0;
89
- window.__webshipPendingTimers = 0;
90
- window.__webshipLastMutation = Date.now();
91
- });
92
- if (this.context) await this.context.close();
93
- this.context = newContext;
94
- this.page = await this.context.newPage();
83
+ try {
84
+ await this.replaceContext({ storageState: file });
85
+ } catch (e) {
86
+ throw friendly({
87
+ action: `restore the auth state from "${source}"`,
88
+ cause: e,
89
+ hint: 'the file must be one written by "I save the auth state to", and the browser must still be open.',
90
+ });
91
+ }
95
92
  });
96
93
 
97
94
  /**