webship-js 2.0.3 → 2.0.5

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 (213) hide show
  1. package/.circleci/config.yml +7 -31
  2. package/.drone.yml +68 -0
  3. package/.harness/webship-js-pipeline.yml +101 -0
  4. package/.semaphore/semaphore.yml +58 -0
  5. package/.teamcity/pom.xml +52 -0
  6. package/.teamcity/settings.kts +92 -0
  7. package/.travis.yml +24 -3
  8. package/AGENTS.md +53 -17
  9. package/CLAUDE.md +327 -105
  10. package/Jenkinsfile +54 -0
  11. package/azure-pipelines.yml +82 -0
  12. package/bamboo-specs/bamboo.yml +131 -0
  13. package/bin/init-webship.js +0 -13
  14. package/bin/postinstall.js +0 -0
  15. package/buildspec.yml +56 -0
  16. package/cloudbuild.yaml +49 -0
  17. package/codefresh.yml +77 -0
  18. package/cucumber.js +39 -14
  19. package/docs/00-quick-start.md +0 -0
  20. package/docs/01-getting-started.md +0 -0
  21. package/docs/02-bbr-smart-waits.md +0 -0
  22. package/docs/03-selector-registry.md +0 -0
  23. package/docs/04-step-reference.md +74 -3
  24. package/docs/05-web-first-assertions.md +0 -0
  25. package/docs/06-network-and-dialogs.md +0 -0
  26. package/docs/07-auth-state.md +0 -0
  27. package/docs/08-clock-mocking.md +0 -0
  28. package/docs/09-api-testing.md +0 -0
  29. package/docs/10-accessibility.md +0 -0
  30. package/docs/11-debugging.md +0 -0
  31. package/docs/12-ai-agent-guide.md +0 -0
  32. package/docs/13-faq.md +0 -0
  33. package/docs/14-recipes-cookbook.md +0 -0
  34. package/docs/15-tag-conventions.md +0 -0
  35. package/docs/16-ci-cd.md +879 -0
  36. package/docs/README.md +116 -0
  37. package/docs/advanced-screenshots/then-i-save-fullscreen-screenshot.md +0 -0
  38. package/docs/advanced-screenshots/then-i-save-width-x-height-screenshot.md +0 -0
  39. package/docs/advanced-screenshots/when-i-save-screenshot-name-filename.md +0 -0
  40. package/docs/advanced-screenshots.md +0 -0
  41. package/docs/advanced-selectors.md +0 -0
  42. package/docs/api-step-definitions.md +0 -0
  43. package/docs/global-settings.md +45 -22
  44. package/docs/install-webship-js/ddev-webship-js.md +0 -0
  45. package/docs/install-webship-js.md +0 -1
  46. package/docs/overview.md +0 -1
  47. package/docs/step-definitions/given-i-am-anonymous-user.md +0 -0
  48. package/docs/step-definitions/given-i-am-homepage.md +0 -0
  49. package/docs/step-definitions/given-i-am-specific-page.md +0 -0
  50. package/docs/step-definitions/then-i-should-be.md +0 -0
  51. package/docs/step-definitions/then-i-should-see.md +0 -0
  52. package/docs/step-definitions/then-item-checkbox.md +0 -0
  53. package/docs/step-definitions/then-item-link-should-contain-url.md +0 -0
  54. package/docs/step-definitions/then-item-should-contain.md +0 -0
  55. package/docs/step-definitions/then-radio-button-value-should-be-selected.md +0 -0
  56. package/docs/step-definitions/then-response-status-code-should-be-number.md +0 -0
  57. package/docs/step-definitions/then-value-radio-button-selected.md +0 -0
  58. package/docs/step-definitions/when-i-attach-file-file-name-element.md +0 -0
  59. package/docs/step-definitions/when-i-check-checkbox.md +0 -0
  60. package/docs/step-definitions/when-i-click-link.md +0 -0
  61. package/docs/step-definitions/when-i-click-operation-text-row.md +0 -0
  62. package/docs/step-definitions/when-i-fill.md +0 -0
  63. package/docs/step-definitions/when-i-go-homepage.md +0 -0
  64. package/docs/step-definitions/when-i-go-specific-page.md +0 -0
  65. package/docs/step-definitions/when-i-move-backward-one-page.md +0 -0
  66. package/docs/step-definitions/when-i-move-forward-one-page.md +0 -0
  67. package/docs/step-definitions/when-i-press-button.md +0 -0
  68. package/docs/step-definitions/when-i-reload-page.md +0 -0
  69. package/docs/step-definitions/when-i-scroll.md +0 -0
  70. package/docs/step-definitions/when-i-select-option-select-list.md +0 -0
  71. package/docs/step-definitions/when-i-select-radio-button-value.md +0 -0
  72. package/docs/step-definitions/when-i-uncheck-checkbox.md +0 -0
  73. package/docs/step-definitions/when-i-wait-ajax-finish.md +0 -0
  74. package/docs/step-definitions/when-i-wait.md +0 -0
  75. package/docs/step-definitions.md +0 -0
  76. package/examples/a11y.html +0 -0
  77. package/examples/account.html +0 -0
  78. package/examples/ajax-wait-examples.html +0 -0
  79. package/examples/cookies.html +0 -0
  80. package/examples/date.html +0 -0
  81. package/examples/dynamic-examples.html +0 -0
  82. package/examples/element.html +0 -0
  83. package/examples/field.html +0 -0
  84. package/examples/keyboard.html +0 -0
  85. package/examples/links.html +0 -0
  86. package/examples/modal.html +0 -0
  87. package/examples/path.html +0 -0
  88. package/examples/table.html +0 -0
  89. package/examples/test--modal-dialogs.html +0 -0
  90. package/examples/test--when--i-additionally-select.html +0 -0
  91. package/examples/test--when--i-select-radio-button.html +0 -0
  92. package/examples/video-demo.html +43 -0
  93. package/package.json +1 -1
  94. package/playwright.config.ts +0 -0
  95. package/tests/assets/test-document.pdf +0 -0
  96. package/tests/features/a11y.feature +0 -0
  97. package/tests/features/ajax-wait-examples.feature +0 -0
  98. package/tests/features/cookie.feature +0 -0
  99. package/tests/features/date.feature +0 -0
  100. package/tests/features/dynamic-content-examples.feature +0 -0
  101. package/tests/features/element.feature +0 -0
  102. package/tests/features/field.feature +0 -0
  103. package/tests/features/keyboard.feature +0 -0
  104. package/tests/features/link.feature +0 -0
  105. package/tests/features/modal-advanced-example.feature +0 -0
  106. package/tests/features/modal-basic-example.feature +0 -0
  107. package/tests/features/modal-error-handling-example.feature +0 -0
  108. package/tests/features/modal.feature +0 -0
  109. package/tests/features/path.feature +0 -0
  110. package/tests/features/response.feature +0 -0
  111. package/tests/features/responsive.feature +0 -0
  112. package/tests/features/table.feature +0 -0
  113. package/tests/features/test--given--i-am-an-anonymous-user.feature +0 -0
  114. package/tests/features/test--then--i-save-screenshot.feature +0 -0
  115. package/tests/features/test--then--i-see-locator.feature +0 -0
  116. package/tests/features/test--then--i-should-see-n-elements.feature +0 -0
  117. package/tests/features/test--then--print-current-url-and-response.feature +0 -0
  118. package/tests/features/test--when--i-additionally-select.feature +0 -0
  119. package/tests/features/test--when--i-follow.feature +0 -0
  120. package/tests/features/test--when--i-select-radio-button.feature +0 -0
  121. package/tests/features/video.feature +18 -0
  122. package/tests/features/wait.feature +0 -0
  123. package/tests/features/yaml.feature +0 -0
  124. package/tests/reports/README.md +0 -0
  125. package/tests/selectors/_canonical-keys.json +0 -0
  126. package/tests/selectors/back-end-selectors.json +0 -0
  127. package/tests/selectors/cms-contentful-admin.json +0 -0
  128. package/tests/selectors/cms-craft-admin.json +0 -0
  129. package/tests/selectors/cms-drupal-cms-gin.json +0 -0
  130. package/tests/selectors/cms-drupal-core-claro.json +0 -0
  131. package/tests/selectors/cms-generic-admin.json +0 -0
  132. package/tests/selectors/cms-ghost-admin.json +0 -0
  133. package/tests/selectors/cms-joomla-admin.json +0 -0
  134. package/tests/selectors/cms-magento2-admin.json +0 -0
  135. package/tests/selectors/cms-prestashop-admin.json +0 -0
  136. package/tests/selectors/cms-shopify-admin.json +0 -0
  137. package/tests/selectors/cms-strapi-admin.json +0 -0
  138. package/tests/selectors/cms-typo3-admin.json +0 -0
  139. package/tests/selectors/cms-woocommerce-front.json +0 -0
  140. package/tests/selectors/cms-wordpress-admin.json +0 -0
  141. package/tests/selectors/framework-ant-design.json +0 -0
  142. package/tests/selectors/framework-bootstrap.json +0 -0
  143. package/tests/selectors/framework-bulma.json +0 -0
  144. package/tests/selectors/framework-chakra.json +0 -0
  145. package/tests/selectors/framework-foundation.json +0 -0
  146. package/tests/selectors/framework-material-ui.json +0 -0
  147. package/tests/selectors/framework-shadcn.json +0 -0
  148. package/tests/selectors/framework-tailwind.json +0 -0
  149. package/tests/selectors/framework-vuetify.json +0 -0
  150. package/tests/selectors/front-end-selectors.json +0 -0
  151. package/tests/selectors/homepage-selectors.json +0 -0
  152. package/tests/step-definitions/a11y.steps.js +3 -1
  153. package/tests/step-definitions/action.steps.js +2 -2
  154. package/tests/step-definitions/api.steps.js +17 -16
  155. package/tests/step-definitions/assertion.steps.js +2 -2
  156. package/tests/step-definitions/auth.steps.js +3 -1
  157. package/tests/step-definitions/clock.steps.js +38 -38
  158. package/tests/step-definitions/cookie.steps.js +0 -0
  159. package/tests/step-definitions/debug.steps.js +13 -5
  160. package/tests/step-definitions/dialog.steps.js +0 -0
  161. package/tests/step-definitions/element.steps.js +47 -5
  162. package/tests/step-definitions/field.steps.js +0 -0
  163. package/tests/step-definitions/file-download.steps.js +38 -20
  164. package/tests/step-definitions/form.steps.js +6 -6
  165. package/tests/step-definitions/iframe.steps.js +65 -15
  166. package/tests/step-definitions/input.steps.js +47 -8
  167. package/tests/step-definitions/javascript.steps.js +195 -34
  168. package/tests/step-definitions/keyboard.steps.js +38 -4
  169. package/tests/step-definitions/link.steps.js +0 -0
  170. package/tests/step-definitions/metatag.steps.js +0 -0
  171. package/tests/step-definitions/modal.steps.js +39 -14
  172. package/tests/step-definitions/navigation.steps.js +0 -0
  173. package/tests/step-definitions/network.steps.js +61 -19
  174. package/tests/step-definitions/path.steps.js +0 -0
  175. package/tests/step-definitions/response.steps.js +0 -0
  176. package/tests/step-definitions/responsive.steps.js +3 -1
  177. package/tests/step-definitions/rest.steps.js +0 -0
  178. package/tests/step-definitions/screenshot.steps.js +0 -0
  179. package/tests/step-definitions/scroll.steps.js +0 -0
  180. package/tests/step-definitions/selectors.steps.js +19 -17
  181. package/tests/step-definitions/storage.steps.js +0 -0
  182. package/tests/step-definitions/table.steps.js +0 -0
  183. package/tests/step-definitions/video.steps.js +178 -0
  184. package/tests/step-definitions/wait.steps.js +0 -0
  185. package/tests/step-definitions/web-first.steps.js +3 -1
  186. package/tests/step-definitions/webship.js +234 -15
  187. package/tests/step-definitions/xml.steps.js +4 -2
  188. package/tests/step-definitions/yaml.steps.js +13 -11
  189. package/tsconfig.json +0 -0
  190. package/videos/README.md +32 -0
  191. package/.travis-ci.yml +0 -16
  192. package/docs/diffy-step-definitions/then-compare-diffy-env1-env2.md +0 -30
  193. package/docs/diffy-step-definitions/then-create-diffy-comparison-name-value.md +0 -21
  194. package/docs/diffy-step-definitions/then-create-diffy-comparison.md +0 -25
  195. package/docs/diffy-step-definitions/then-create-diffy-screenshot-environment-name.md +0 -35
  196. package/docs/diffy-step-definitions/then-i-take-screenshot.md +0 -21
  197. package/docs/diffy-step-definitions/then-i-take-screenshots-all-breakpoints.md +0 -27
  198. package/docs/diffy-step-definitions/then-send-screenshots-diffy-name-value.md +0 -27
  199. package/docs/diffy-step-definitions/then-upload-folder-url-diffy-snapshotname.md +0 -28
  200. package/docs/diffy-step-definitions/then-wait-diffy-comparison-complete.md +0 -21
  201. package/docs/diffy-step-definitions/when-i-resize-window-number.md +0 -29
  202. package/docs/diffy-step-definitions.md +0 -21
  203. package/docs/index.md +0 -104
  204. package/examples/diffy/baseline.html +0 -54
  205. package/examples/diffy/changed.html +0 -63
  206. package/examples/diffy/index.html +0 -52
  207. package/tests/features/diffy/test--diffy-01-example-demo.feature +0 -22
  208. package/tests/features/diffy/test--diffy-02-all-steps.feature +0 -52
  209. package/tests/features/diffy/test--diffy-03-real-api.feature +0 -21
  210. package/tests/step-definitions-diffy/README.md +0 -329
  211. package/tests/step-definitions-diffy/mock-diffy-api/server.js +0 -84
  212. package/tests/step-definitions-diffy/webship-diffy-mock.js +0 -31
  213. package/tests/step-definitions-diffy/webship-diffy.js +0 -459
@@ -1,5 +1,7 @@
1
1
  'use strict';
2
2
 
3
+ const { friendly } = require('./webship');
4
+
3
5
  // Iframe / frame steps backed by Playwright's `frameLocator` API.
4
6
  //
5
7
  // Frames are addressed by CSS selector. Once switched, frame-scoped
@@ -13,6 +15,14 @@ function frameRoot(world) {
13
15
  return world.frame || world.page;
14
16
  }
15
17
 
18
+ function explain(action, detail, e) {
19
+ return friendly({
20
+ action,
21
+ cause: e,
22
+ hint: `wait for the iframe to load first ("When I wait for \\"iframe\\" to appear"). Detail: ${detail}.`,
23
+ });
24
+ }
25
+
16
26
  /**
17
27
  * Switch the active scope to an iframe addressed by CSS selector.
18
28
  *
@@ -24,8 +34,12 @@ function frameRoot(world) {
24
34
  *
25
35
  */
26
36
  When(/^(I |we )*switch to (the )?iframe "([^"]*)"$/, async function (pronoun, theCase, sel) {
27
- if (!this._rootPage) this._rootPage = this.page;
28
- this.frame = this.page.frameLocator(sel);
37
+ try {
38
+ if (!this._rootPage) this._rootPage = this.page;
39
+ this.frame = this.page.frameLocator(sel);
40
+ } catch (e) {
41
+ throw explain(`switch to iframe "${sel}"`, `selector tried: ${sel}`, e);
42
+ }
29
43
  });
30
44
 
31
45
  /**
@@ -39,8 +53,12 @@ When(/^(I |we )*switch to (the )?iframe "([^"]*)"$/, async function (pronoun, th
39
53
  *
40
54
  */
41
55
  When(/^(I |we )*switch to iframe with locator "([^"]*)"$/, async function (pronoun, sel) {
42
- if (!this._rootPage) this._rootPage = this.page;
43
- this.frame = this.page.frameLocator(sel);
56
+ try {
57
+ if (!this._rootPage) this._rootPage = this.page;
58
+ this.frame = this.page.frameLocator(sel);
59
+ } catch (e) {
60
+ throw explain(`switch to iframe with locator "${sel}"`, `locator: ${sel}`, e);
61
+ }
44
62
  });
45
63
 
46
64
  /**
@@ -74,8 +92,12 @@ When(/^(I |we )*switch to the root document$/, async function () {
74
92
  *
75
93
  */
76
94
  When(/^(I |we )*switch to the iframe with title "([^"]*)"$/, async function (pronoun, title) {
77
- if (!this._rootPage) this._rootPage = this.page;
78
- this.frame = this.page.frameLocator(`iframe[title="${title}"]`);
95
+ try {
96
+ if (!this._rootPage) this._rootPage = this.page;
97
+ this.frame = this.page.frameLocator(`iframe[title="${title}"]`);
98
+ } catch (e) {
99
+ throw explain(`switch to iframe by title "${title}"`, `selector: iframe[title="${title}"]`, e);
100
+ }
79
101
  });
80
102
 
81
103
  /**
@@ -89,8 +111,12 @@ When(/^(I |we )*switch to the iframe with title "([^"]*)"$/, async function (pro
89
111
  *
90
112
  */
91
113
  When(/^(I |we )*switch to the iframe with name "([^"]*)"$/, async function (pronoun, name) {
92
- if (!this._rootPage) this._rootPage = this.page;
93
- this.frame = this.page.frameLocator(`iframe[name="${name}"]`);
114
+ try {
115
+ if (!this._rootPage) this._rootPage = this.page;
116
+ this.frame = this.page.frameLocator(`iframe[name="${name}"]`);
117
+ } catch (e) {
118
+ throw explain(`switch to iframe by name "${name}"`, `selector: iframe[name="${name}"]`, e);
119
+ }
94
120
  });
95
121
 
96
122
  // ---------------------------------------------------------------------------
@@ -108,9 +134,17 @@ When(/^(I |we )*switch to the iframe with name "([^"]*)"$/, async function (pron
108
134
  *
109
135
  */
110
136
  When(/^(I |we )*click "([^"]*)" inside the iframe$/, async function (pronoun, text) {
111
- const root = frameRoot(this);
112
- if (!root.locator) throw new Error('No active iframe. Switch first.');
113
- await root.locator(`text="${text}"`).first().click();
137
+ try {
138
+ const root = frameRoot(this);
139
+ if (!root.locator) throw friendly('No active iframe. Switch first.');
140
+ await root.locator(`text="${text}"`).first().click();
141
+ } catch (e) {
142
+ throw friendly({
143
+ action: `click "${text}" inside the iframe`,
144
+ cause: e,
145
+ hint: `switch to the iframe first ("When I switch to iframe '<selector>'"), then check the visible text matches exactly.`,
146
+ });
147
+ }
114
148
  });
115
149
 
116
150
  /**
@@ -126,8 +160,16 @@ When(/^(I |we )*click "([^"]*)" inside the iframe$/, async function (pronoun, te
126
160
  *
127
161
  */
128
162
  When(/^(I |we )*click "([^"]*)" by attr inside the iframe$/, async function (pronoun, attrValue) {
129
- const root = frameRoot(this);
130
- await root.locator(`#${attrValue}, .${attrValue}, [name="${attrValue}"], [data-testid="${attrValue}"]`).first().click();
163
+ try {
164
+ const root = frameRoot(this);
165
+ await root.locator(`#${attrValue}, .${attrValue}, [name="${attrValue}"], [data-testid="${attrValue}"]`).first().click();
166
+ } catch (e) {
167
+ throw friendly({
168
+ action: `click "${attrValue}" by attribute inside the iframe`,
169
+ cause: e,
170
+ hint: `switch to the iframe first; checked id, class, [name], [data-testid] — none matched.`,
171
+ });
172
+ }
131
173
  });
132
174
 
133
175
  /**
@@ -141,8 +183,16 @@ When(/^(I |we )*click "([^"]*)" by attr inside the iframe$/, async function (pro
141
183
  *
142
184
  */
143
185
  When(/^(I |we )*fill in "([^"]*)" with "([^"]*)" inside the iframe$/, async function (pronoun, field, value) {
144
- const root = frameRoot(this);
145
- await root.locator(`[name="${field}"], #${field}`).first().fill(value);
186
+ try {
187
+ const root = frameRoot(this);
188
+ await root.locator(`[name="${field}"], #${field}`).first().fill(value);
189
+ } 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.`,
194
+ });
195
+ }
146
196
  });
147
197
 
148
198
  /**
@@ -1,10 +1,20 @@
1
1
  'use strict';
2
2
 
3
+ const { friendly } = require('./webship');
4
+
3
5
  // Pointer input steps not covered by the core element/click steps:
4
6
  // hover variants, drag-and-drop, double-click, right-click, viewport size.
5
7
 
6
8
  const { When } = require('@cucumber/cucumber');
7
9
 
10
+ function explainPtr(action, sel, e) {
11
+ return friendly({
12
+ action: `${action} "${sel}"`,
13
+ cause: e,
14
+ hint: `check the element exists on the page, is visible, and is not covered by an overlay.`,
15
+ });
16
+ }
17
+
8
18
  // ---------------------------------------------------------------------------
9
19
  // Hover (variants)
10
20
  // ---------------------------------------------------------------------------
@@ -20,7 +30,8 @@ const { When } = require('@cucumber/cucumber');
20
30
  *
21
31
  */
22
32
  When(/^(I |we )*hover over "([^"]*)"$/, async function (pronoun, sel) {
23
- await this.page.locator(sel).first().hover();
33
+ try { await this.page.locator(sel).first().hover(); }
34
+ catch (e) { throw explainPtr('hover over', sel, e); }
24
35
  });
25
36
 
26
37
  /**
@@ -34,7 +45,8 @@ When(/^(I |we )*hover over "([^"]*)"$/, async function (pronoun, sel) {
34
45
  *
35
46
  */
36
47
  When(/^(I |we )*move the pointer to "([^"]*)"$/, async function (pronoun, sel) {
37
- await this.page.locator(sel).first().hover();
48
+ try { await this.page.locator(sel).first().hover(); }
49
+ catch (e) { throw explainPtr('move pointer to', sel, e); }
38
50
  });
39
51
 
40
52
  // ---------------------------------------------------------------------------
@@ -52,7 +64,8 @@ When(/^(I |we )*move the pointer to "([^"]*)"$/, async function (pronoun, sel) {
52
64
  *
53
65
  */
54
66
  When(/^(I |we )*double[- ]click on "([^"]*)"$/, async function (pronoun, sel) {
55
- await this.page.locator(sel).first().dblclick();
67
+ try { await this.page.locator(sel).first().dblclick(); }
68
+ catch (e) { throw explainPtr('double-click', sel, e); }
56
69
  });
57
70
 
58
71
  /**
@@ -66,7 +79,8 @@ When(/^(I |we )*double[- ]click on "([^"]*)"$/, async function (pronoun, sel) {
66
79
  *
67
80
  */
68
81
  When(/^(I |we )*right[- ]click on "([^"]*)"$/, async function (pronoun, sel) {
69
- await this.page.locator(sel).first().click({ button: 'right' });
82
+ try { await this.page.locator(sel).first().click({ button: 'right' }); }
83
+ catch (e) { throw explainPtr('right-click', sel, e); }
70
84
  });
71
85
 
72
86
  /**
@@ -80,7 +94,8 @@ When(/^(I |we )*right[- ]click on "([^"]*)"$/, async function (pronoun, sel) {
80
94
  *
81
95
  */
82
96
  When(/^(I |we )*middle[- ]click on "([^"]*)"$/, async function (pronoun, sel) {
83
- await this.page.locator(sel).first().click({ button: 'middle' });
97
+ try { await this.page.locator(sel).first().click({ button: 'middle' }); }
98
+ catch (e) { throw explainPtr('middle-click', sel, e); }
84
99
  });
85
100
 
86
101
  /**
@@ -96,7 +111,15 @@ When(/^(I |we )*middle[- ]click on "([^"]*)"$/, async function (pronoun, sel) {
96
111
  *
97
112
  */
98
113
  When(/^(I |we )*click on "([^"]*)" while holding "([^"]*)"$/, async function (pronoun, sel, key) {
99
- await this.page.locator(sel).first().click({ modifiers: [key] });
114
+ try {
115
+ await this.page.locator(sel).first().click({ modifiers: [key] });
116
+ } catch (e) {
117
+ throw friendly({
118
+ action: `click "${sel}" while holding "${key}"`,
119
+ cause: e,
120
+ hint: `modifier must be one of: Shift, Control, Alt, Meta.`,
121
+ });
122
+ }
100
123
  });
101
124
 
102
125
  // ---------------------------------------------------------------------------
@@ -114,7 +137,15 @@ When(/^(I |we )*click on "([^"]*)" while holding "([^"]*)"$/, async function (pr
114
137
  *
115
138
  */
116
139
  When(/^(I |we )*drag "([^"]*)" to "([^"]*)"$/, async function (pronoun, source, target) {
117
- await this.page.locator(source).first().dragTo(this.page.locator(target).first());
140
+ try {
141
+ await this.page.locator(source).first().dragTo(this.page.locator(target).first());
142
+ } catch (e) {
143
+ throw friendly({
144
+ action: `drag "${source}" to "${target}"`,
145
+ cause: e,
146
+ hint: `both items must exist on the page; the target must accept drops.`,
147
+ });
148
+ }
118
149
  });
119
150
 
120
151
  // ---------------------------------------------------------------------------
@@ -132,7 +163,15 @@ When(/^(I |we )*drag "([^"]*)" to "([^"]*)"$/, async function (pronoun, source,
132
163
  *
133
164
  */
134
165
  When(/^(I |we )*set the viewport size to (\d+)x(\d+)$/, async function (pronoun, w, h) {
135
- await this.page.setViewportSize({ width: parseInt(w, 10), height: parseInt(h, 10) });
166
+ try {
167
+ await this.page.setViewportSize({ width: parseInt(w, 10), height: parseInt(h, 10) });
168
+ } catch (e) {
169
+ throw friendly({
170
+ action: `set viewport size to ${w}x${h}`,
171
+ cause: e,
172
+ hint: `the browser was opened in fluid-viewport mode; set a fixed viewport in playwright.config.ts contextOptions.viewport.`,
173
+ });
174
+ }
136
175
  });
137
176
 
138
177
  // ---------------------------------------------------------------------------
@@ -2,70 +2,231 @@
2
2
 
3
3
  // Auto-detect JavaScript errors during test execution.
4
4
  //
5
- // Errors collected from page.on('pageerror') and page.on('console') (level=error).
6
- // Always tracked once a page is opened. Final assertion runs only when:
7
- // - the scenario is tagged @javascript (asserts no errors at scenario end), OR
8
- // - the test explicitly calls "Then there should be no JavaScript errors".
9
- // Use the @js-errors tag to suppress the @javascript assertion when errors
10
- // are intentionally expected.
5
+ // Listeners are attached on Before (order 200) once a page is open:
6
+ // page.on('pageerror') → uncaught errors
7
+ // page.on('console', level) → console messages (filtered by config)
8
+ //
9
+ // After every scenario the collector reports per the active "mode":
10
+ // - 'warn' (default) → log a yellow warning, scenario still passes
11
+ // - 'fail' → assert.fail with the error list
12
+ // - 'off' → silent
13
+ //
14
+ // Mode resolution priority (first match wins):
15
+ // 1. scenario tag @js-fail / @js-warn / @js-off / @javascript / @js-errors
16
+ // 2. env var WEBSHIP_JS_ERROR_MODE = warn | fail | off
17
+ // 3. worldParameters parameters.javascript.mode
18
+ // 4. default 'warn'
19
+ //
20
+ // Back-compat: @javascript → fail (legacy "always fail" tag). @js-errors → off.
11
21
 
12
22
  const { Before, After, Then } = require('@cucumber/cucumber');
13
23
  const assert = require('assert');
14
24
 
15
- function hasTag(scenario, name) {
16
- if (!scenario || !Array.isArray(scenario.pickle && scenario.pickle.tags)) return false;
17
- return scenario.pickle.tags.some((t) => t.name === name);
25
+ const VALID_MODES = new Set(['warn', 'fail', 'off']);
26
+ const DEFAULT_CONSOLE_LEVELS = ['error'];
27
+
28
+ /**
29
+ * Resolve effective settings for the current scenario.
30
+ *
31
+ * @returns {{ mode: 'warn'|'fail'|'off', levels: string[], ignore: RegExp|null,
32
+ * beforeScenario: boolean, afterScenario: boolean }}
33
+ */
34
+ function resolveSettings(world, scope) {
35
+ const cfg = (world.parameters && world.parameters.javascript) || {};
36
+ const tag = (name) => hasTag(scope, name);
37
+
38
+ let mode;
39
+ if (tag('@js-fail') || tag('@javascript')) mode = 'fail';
40
+ else if (tag('@js-warn')) mode = 'warn';
41
+ else if (tag('@js-off') || tag('@js-errors')) mode = 'off';
42
+ else if (process.env.WEBSHIP_JS_ERROR_MODE) mode = process.env.WEBSHIP_JS_ERROR_MODE;
43
+ else if (cfg.mode) mode = cfg.mode;
44
+ else mode = 'warn';
45
+ if (!VALID_MODES.has(mode)) mode = 'warn';
46
+
47
+ const levelsRaw =
48
+ process.env.WEBSHIP_JS_ERROR_LEVELS ||
49
+ (Array.isArray(cfg.levels) ? cfg.levels.join(',') : cfg.levels) ||
50
+ DEFAULT_CONSOLE_LEVELS.join(',');
51
+ const levels = String(levelsRaw).split(',').map((s) => s.trim()).filter(Boolean);
52
+
53
+ const ignoreSrc = process.env.WEBSHIP_JS_ERROR_IGNORE || cfg.ignore || null;
54
+ let ignore = null;
55
+ if (ignoreSrc) {
56
+ try { ignore = new RegExp(ignoreSrc); }
57
+ catch { ignore = null; }
58
+ }
59
+
60
+ const beforeScenario =
61
+ process.env.WEBSHIP_JS_ERROR_BEFORE === '1'
62
+ ? true
63
+ : cfg.beforeScenario === true;
64
+ const afterScenario =
65
+ process.env.WEBSHIP_JS_ERROR_AFTER === '0'
66
+ ? false
67
+ : cfg.afterScenario !== false; // default true
68
+
69
+ return { mode, levels, ignore, beforeScenario, afterScenario };
70
+ }
71
+
72
+ function hasTag(scope, name) {
73
+ if (!scope || !Array.isArray(scope.pickle && scope.pickle.tags)) return false;
74
+ return scope.pickle.tags.some((t) => t.name === name);
75
+ }
76
+
77
+ function formatErrors(errs) {
78
+ return errs.map((e, i) => ` ${i + 1}. [${e.type}] ${e.message}`).join('\n');
79
+ }
80
+
81
+ function filterErrors(errs, ignore) {
82
+ if (!ignore) return errs;
83
+ return errs.filter((e) => !ignore.test(e.message));
84
+ }
85
+
86
+ function reportWarning(scope, errs) {
87
+ const name = (scope && scope.pickle && scope.pickle.name) || 'scenario';
88
+ // Yellow ANSI when FORCE_COLOR is on, plain otherwise — let the runtime
89
+ // decide. cucumber-js sets FORCE_COLOR=1 by default in interactive shells.
90
+ const head = `[webship-js] JavaScript errors during "${name}" (mode=warn):`;
91
+ process.stderr.write(`\n\x1b[33m${head}\n${formatErrors(errs)}\x1b[0m\n`);
18
92
  }
19
93
 
94
+ // ---------------------------------------------------------------------------
95
+ // Before — attach listeners + (optional) pre-snapshot.
96
+ // ---------------------------------------------------------------------------
97
+
20
98
  Before({ order: 200 }, function (scope) {
21
99
  this._jsErrors = [];
22
100
  this._jsErrorsAsserted = false;
23
- this._jsErrorsAutoAssert = hasTag(scope, '@javascript');
101
+ this._jsSettings = resolveSettings(this, scope);
102
+ if (this._jsSettings.mode === 'off') return;
24
103
  if (!this.page) return;
104
+
105
+ const levels = new Set(this._jsSettings.levels);
25
106
  this.page.on('pageerror', (err) => {
26
107
  this._jsErrors.push({ type: 'pageerror', message: String(err && err.message || err) });
27
108
  });
28
109
  this.page.on('console', (msg) => {
29
- if (msg.type() === 'error') {
30
- this._jsErrors.push({ type: 'console.error', message: msg.text() });
110
+ if (levels.has(msg.type())) {
111
+ this._jsErrors.push({ type: `console.${msg.type()}`, message: msg.text() });
31
112
  }
32
113
  });
114
+
115
+ if (this._jsSettings.beforeScenario) {
116
+ // Pre-scenario snapshot — typically empty unless the same page is reused.
117
+ const errs = filterErrors(this._jsErrors, this._jsSettings.ignore);
118
+ if (errs.length > 0) {
119
+ process.stderr.write(
120
+ `\n\x1b[33m[webship-js] Pre-scenario JavaScript errors:\n${formatErrors(errs)}\x1b[0m\n`
121
+ );
122
+ }
123
+ }
33
124
  });
34
125
 
126
+ // ---------------------------------------------------------------------------
127
+ // Steps
128
+ // ---------------------------------------------------------------------------
129
+
35
130
  /**
36
131
  * Assert that no JavaScript errors have been collected so far.
37
132
  *
38
- * Errors are tracked from page open (page errors + console.error). Calling
39
- * this step asserts the error log is empty and prevents the auto-assert at
40
- * scenario end (so it does not double-fire).
133
+ * Always fails on error (ignoring the active mode) — this is the explicit
134
+ * "hard check" step. Calling it also prevents the auto-report at scenario
135
+ * end so a single error is not reported twice.
41
136
  *
42
137
  * Example #1: Then there should be no JavaScript errors
43
- * Example #2: Given I am on the homepage
44
- * Then there should be no JavaScript errors
45
- * Example #3: When I follow "Pricing"
46
- * And I wait until the network is idle
47
- * Then there should be no JavaScript errors
48
- * Example #4: When I press "Add to cart"
49
- * Then there should be no JavaScript errors
50
- * Example #5: Given I am on "/dashboard"
51
- * And I scroll to the bottom
52
- * Then there should be no JavaScript errors
138
+ * Example #2: And there should be no JavaScript errors
139
+ * Example #3: But there should be no JavaScript errors
140
+ * Example #4: Then there should be no JavaScript errors
141
+ * Example #5: Then there should be no JavaScript errors
53
142
  *
54
143
  */
55
144
  Then(/^there should be no JavaScript errors$/, function () {
56
145
  this._jsErrorsAsserted = true;
57
- const errs = this._jsErrors || [];
146
+ const errs = filterErrors(this._jsErrors || [], this._jsSettings && this._jsSettings.ignore);
58
147
  if (errs.length === 0) return;
59
- const summary = errs.map((e, i) => ` ${i + 1}. [${e.type}] ${e.message}`).join('\n');
60
- assert.fail(`JavaScript errors detected:\n${summary}`);
148
+ assert.fail(`JavaScript errors detected:\n${formatErrors(errs)}`);
61
149
  });
62
150
 
63
- After({ order: 200 }, function (scope) {
64
- if (!this._jsErrorsAutoAssert) return;
65
- if (hasTag(scope, '@js-errors')) return;
66
- if (this._jsErrorsAsserted) return;
151
+ /**
152
+ * Assert that no JavaScript console warnings were collected. Requires
153
+ * 'warning' to be in the captured console levels (see worldParameters or
154
+ * WEBSHIP_JS_ERROR_LEVELS).
155
+ *
156
+ * Example #1: Then there should be no JavaScript warnings
157
+ * Example #2: And there should be no JavaScript warnings
158
+ * Example #3: But there should be no JavaScript warnings
159
+ * Example #4: Then there should be no JavaScript warnings
160
+ * Example #5: Then there should be no JavaScript warnings
161
+ *
162
+ */
163
+ Then(/^there should be no JavaScript warnings$/, function () {
164
+ this._jsErrorsAsserted = true;
165
+ const errs = (this._jsErrors || []).filter((e) => e.type === 'console.warning');
166
+ if (errs.length === 0) return;
167
+ assert.fail(`JavaScript warnings detected:\n${formatErrors(errs)}`);
168
+ });
169
+
170
+ /**
171
+ * Assert that no collected JavaScript error message matches a regular
172
+ * expression. Useful when some noise is unavoidable but a specific bug
173
+ * pattern must never appear.
174
+ *
175
+ * Example #1: Then JavaScript errors should not match "TypeError"
176
+ * Example #2: Then JavaScript errors should not match "is not a function"
177
+ * Example #3: And JavaScript errors should not match "Cannot read property"
178
+ * Example #4: Then JavaScript errors should not match "ReferenceError: .* is not defined"
179
+ * Example #5: Then JavaScript errors should not match "Uncaught"
180
+ *
181
+ */
182
+ Then(/^JavaScript errors should not match "([^"]*)"$/, function (pattern) {
183
+ let re;
184
+ try { re = new RegExp(pattern); }
185
+ catch (e) {
186
+ assert.fail(`Invalid regular expression: "${pattern}" — ${e.message}`);
187
+ }
188
+ const errs = (this._jsErrors || []).filter((e) => re.test(e.message));
189
+ if (errs.length === 0) return;
190
+ assert.fail(`JavaScript errors matched /${pattern}/:\n${formatErrors(errs)}`);
191
+ });
192
+
193
+ /**
194
+ * Print the JavaScript errors collected so far. Diagnostic only — never
195
+ * asserts, never fails. Useful inside a scenario being debugged.
196
+ *
197
+ * Example #1: Then print JavaScript errors
198
+ * Example #2: And print JavaScript errors
199
+ * Example #3: But print JavaScript errors
200
+ * Example #4: Then print JavaScript errors
201
+ * Example #5: Then print JavaScript errors
202
+ *
203
+ */
204
+ Then(/^print JavaScript errors$/, function () {
67
205
  const errs = this._jsErrors || [];
206
+ if (errs.length === 0) {
207
+ console.log('\n--- JavaScript errors: none ---');
208
+ return;
209
+ }
210
+ console.log('\n--- JavaScript errors ---');
211
+ console.log(formatErrors(errs));
212
+ });
213
+
214
+ // ---------------------------------------------------------------------------
215
+ // After — report per mode.
216
+ // ---------------------------------------------------------------------------
217
+
218
+ After({ order: 200 }, function (scope) {
219
+ const s = this._jsSettings || resolveSettings(this, scope);
220
+ if (s.mode === 'off') return;
221
+ if (!s.afterScenario) return;
222
+ if (this._jsErrorsAsserted) return; // already handled by explicit step
223
+
224
+ const errs = filterErrors(this._jsErrors || [], s.ignore);
68
225
  if (errs.length === 0) return;
69
- const summary = errs.map((e, i) => ` ${i + 1}. [${e.type}] ${e.message}`).join('\n');
70
- assert.fail(`JavaScript errors detected during scenario:\n${summary}`);
226
+
227
+ if (s.mode === 'fail') {
228
+ assert.fail(`JavaScript errors detected during scenario:\n${formatErrors(errs)}`);
229
+ } else {
230
+ reportWarning(scope, errs);
231
+ }
71
232
  });
@@ -1,5 +1,7 @@
1
1
  'use strict';
2
2
 
3
+ const { friendly } = require('./webship');
4
+
3
5
  // Simulate keyboard interactions on the page or on a specific element.
4
6
 
5
7
  const { When } = require('@cucumber/cucumber');
@@ -31,7 +33,15 @@ function normalizeKey(key) {
31
33
  *
32
34
  */
33
35
  When(/^(I |we )*press the key "([^"]*)"$/, async function (pronoun, key) {
34
- await this.page.keyboard.press(normalizeKey(key));
36
+ try {
37
+ await this.page.keyboard.press(normalizeKey(key));
38
+ } catch (e) {
39
+ throw friendly({
40
+ action: `press the key "${key}"`,
41
+ cause: e,
42
+ hint: `use a real key name like Enter, Escape, Tab, ArrowDown, or a short alias (enter, esc, tab, up, down, left, right, space).`,
43
+ });
44
+ }
35
45
  });
36
46
 
37
47
  /**
@@ -45,7 +55,15 @@ When(/^(I |we )*press the key "([^"]*)"$/, async function (pronoun, key) {
45
55
  *
46
56
  */
47
57
  When(/^(I |we )*press the key "([^"]*)" on the element "([^"]*)"$/, async function (pronoun, key, sel) {
48
- await this.page.locator(sel).first().press(normalizeKey(key));
58
+ try {
59
+ await this.page.locator(sel).first().press(normalizeKey(key));
60
+ } catch (e) {
61
+ throw friendly({
62
+ action: `press the key "${key}" on "${sel}"`,
63
+ cause: e,
64
+ hint: `check that "${sel}" matches an element on the page that can be focused (input, button, link).`,
65
+ });
66
+ }
49
67
  });
50
68
 
51
69
  /**
@@ -60,7 +78,15 @@ When(/^(I |we )*press the key "([^"]*)" on the element "([^"]*)"$/, async functi
60
78
  *
61
79
  */
62
80
  When(/^(I |we )*press the keys "([^"]*)"$/, async function (pronoun, keys) {
63
- await this.page.keyboard.press(keys);
81
+ try {
82
+ await this.page.keyboard.press(keys);
83
+ } catch (e) {
84
+ throw friendly({
85
+ action: `press the keys "${keys}"`,
86
+ cause: e,
87
+ hint: `use a "+" between modifier and key, e.g. "Control+a", "Meta+s", or "Shift+Tab".`,
88
+ });
89
+ }
64
90
  });
65
91
 
66
92
  /**
@@ -74,5 +100,13 @@ When(/^(I |we )*press the keys "([^"]*)"$/, async function (pronoun, keys) {
74
100
  *
75
101
  */
76
102
  When(/^(I |we )*press the keys "([^"]*)" on the element "([^"]*)"$/, async function (pronoun, keys, sel) {
77
- await this.page.locator(sel).first().press(keys);
103
+ try {
104
+ await this.page.locator(sel).first().press(keys);
105
+ } catch (e) {
106
+ throw friendly({
107
+ action: `press "${keys}" on "${sel}"`,
108
+ cause: e,
109
+ hint: `check the element exists and use "+" between modifier and key, e.g. "Control+s".`,
110
+ });
111
+ }
78
112
  });
File without changes
File without changes