webship-js 2.0.11 → 2.0.13

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 (175) hide show
  1. package/.circleci/config.yml +10 -1
  2. package/.drone.yml +7 -7
  3. package/.github/workflows/github-actions.yml +48 -0
  4. package/.gitlab-ci.yml +9 -4
  5. package/.harness/webship-js-pipeline.yml +5 -6
  6. package/.semaphore/semaphore.yml +6 -9
  7. package/.teamcity/settings.kts +7 -6
  8. package/.travis.yml +6 -1
  9. package/AGENTS.md +1 -1
  10. package/CLAUDE.md +65 -23
  11. package/Jenkinsfile +5 -3
  12. package/azure-pipelines.yml +17 -8
  13. package/bamboo-specs/bamboo.yml +9 -15
  14. package/bin/init-webship.js +53 -10
  15. package/bitbucket-pipelines.yml +5 -1
  16. package/buildspec.yml +6 -7
  17. package/cloudbuild.yaml +28 -12
  18. package/codefresh.yml +6 -6
  19. package/cucumber.js +17 -10
  20. package/docs/00-quick-start.md +8 -0
  21. package/docs/02-bbr-smart-waits.md +15 -10
  22. package/docs/03-selector-registry.md +24 -0
  23. package/docs/04-step-reference.md +51 -25
  24. package/docs/05-web-first-assertions.md +6 -0
  25. package/docs/07-auth-state.md +1 -1
  26. package/docs/08-clock-mocking.md +21 -2
  27. package/docs/09-api-testing.md +40 -2
  28. package/docs/10-accessibility.md +2 -0
  29. package/docs/11-debugging.md +3 -1
  30. package/docs/12-ai-agent-guide.md +5 -0
  31. package/docs/13-faq.md +72 -1
  32. package/docs/14-recipes-cookbook.md +2 -0
  33. package/docs/15-tag-conventions.md +2 -1
  34. package/docs/16-ci-cd.md +140 -119
  35. package/docs/README.md +5 -5
  36. package/docs/advanced-screenshots.md +3 -1
  37. package/docs/api-step-definitions.md +16 -2
  38. package/docs/global-settings.md +69 -17
  39. package/docs/install-webship-js.md +2 -0
  40. package/docs/step-definitions/then-i-should-see.md +14 -1
  41. package/docs/step-definitions/then-item-checkbox.md +2 -0
  42. package/docs/step-definitions/when-i-fill.md +4 -0
  43. package/docs/step-definitions/when-i-select-option-select-list.md +2 -0
  44. package/examples/check-switch.html +37 -0
  45. package/examples/choice-controls.html +29 -0
  46. package/examples/click-whitespace.html +37 -0
  47. package/examples/datetime-fields.html +52 -0
  48. package/examples/element-selector-hint.html +16 -0
  49. package/examples/field-states.html +27 -0
  50. package/examples/fill-in-empty.html +26 -0
  51. package/examples/fill-unreachable.html +27 -0
  52. package/examples/follow-hidden-first.html +29 -0
  53. package/examples/iframe-inner.html +20 -0
  54. package/examples/iframe-nested.html +16 -0
  55. package/examples/iframe-outer.html +15 -0
  56. package/examples/multi-value-fields.html +54 -0
  57. package/examples/registered-names.html +15 -0
  58. package/examples/select-by-label.html +33 -0
  59. package/examples/settle-budget.html +21 -0
  60. package/examples/sorted-tables.html +38 -0
  61. package/examples/text-matching.html +48 -0
  62. package/examples/text-order.html +25 -0
  63. package/examples/touch.html +22 -0
  64. package/examples/viewport-top.html +36 -0
  65. package/package.json +17 -1
  66. package/playwright.config.ts +3 -1
  67. package/tests/check-api-launch-url.js +106 -0
  68. package/tests/check-assets.js +103 -0
  69. package/tests/check-attachments.js +105 -0
  70. package/tests/check-breakpoints.js +117 -0
  71. package/tests/check-clock.js +143 -0
  72. package/tests/check-config.js +90 -0
  73. package/tests/check-context.js +215 -0
  74. package/tests/check-dry-run.js +104 -0
  75. package/tests/check-examples.js +10 -4
  76. package/tests/check-exit-report.js +141 -0
  77. package/tests/check-javascript-errors.js +105 -0
  78. package/tests/check-must-fail.js +5 -4
  79. package/tests/check-network-changed.js +137 -0
  80. package/tests/check-scaffold.js +54 -2
  81. package/tests/check-screenshots.js +117 -0
  82. package/tests/check-settle-verbs.js +137 -0
  83. package/tests/check-time-limit.js +104 -0
  84. package/tests/check-video.js +156 -0
  85. package/tests/check-world.js +167 -0
  86. package/tests/features/api-base-url.feature +25 -0
  87. package/tests/features/api-form-data.feature +18 -0
  88. package/tests/features/api-json-paths.feature +24 -0
  89. package/tests/features/api-response-contains.feature +21 -0
  90. package/tests/features/api-response-header-presence.feature +17 -0
  91. package/tests/features/api-response-header.feature +17 -0
  92. package/tests/features/api-saved-placeholders.feature +37 -0
  93. package/tests/features/api-step-definitions-individual.feature +1 -1
  94. package/tests/features/api-tables.feature +40 -0
  95. package/tests/features/breakpoints.feature +25 -0
  96. package/tests/features/check-switch.feature +28 -0
  97. package/tests/features/choice-controls.feature +35 -0
  98. package/tests/features/click-whitespace.feature +29 -0
  99. package/tests/features/complete-api-testing-examples.feature +1 -1
  100. package/tests/features/datetime-field-lookup.feature +29 -0
  101. package/tests/features/element-selector-hint.feature +14 -0
  102. package/tests/features/field-state.feature +21 -0
  103. package/tests/features/fill-in-empty-value.feature +41 -0
  104. package/tests/features/fill-reachable.feature +13 -0
  105. package/tests/features/follow-hidden-first.feature +9 -0
  106. package/tests/features/iframe-nested.feature +43 -0
  107. package/tests/features/javascript-tolerated-errors.feature +20 -0
  108. package/tests/features/modal-open.feature +13 -0
  109. package/tests/features/multi-value-field-lookup.feature +30 -0
  110. package/tests/features/registered-names.feature +14 -0
  111. package/tests/features/select-by-label.feature +31 -0
  112. package/tests/features/selector-files.feature +14 -0
  113. package/tests/features/selectors-table-header.feature +35 -0
  114. package/tests/features/settle-budget.feature +11 -0
  115. package/tests/features/sorted-tables.feature +19 -0
  116. package/tests/features/storage-quoted-values.feature +26 -0
  117. package/tests/features/text-matching.feature +38 -0
  118. package/tests/features/text-order.feature +14 -0
  119. package/tests/features/touch.feature +21 -0
  120. package/tests/features/viewport-top.feature +13 -0
  121. package/tests/features/xml-namespaces.feature +34 -0
  122. package/tests/must-fail/api-json-paths.feature +21 -0
  123. package/tests/must-fail/api-response-contains.feature +23 -0
  124. package/tests/must-fail/api-response-header-presence.feature +17 -0
  125. package/tests/must-fail/api-response-header.feature +21 -0
  126. package/tests/must-fail/api-without-base-url.feature +11 -0
  127. package/tests/must-fail/breakpoints.feature +15 -0
  128. package/tests/must-fail/choice-controls.feature +25 -0
  129. package/tests/must-fail/clock.feature +11 -0
  130. package/tests/must-fail/datetime-field.feature +10 -0
  131. package/tests/must-fail/element-selector-hint.feature +17 -0
  132. package/tests/must-fail/field-state.feature +20 -0
  133. package/tests/must-fail/fill-field.feature +30 -0
  134. package/tests/must-fail/iframe-text.feature +17 -0
  135. package/tests/must-fail/modal-open.feature +26 -0
  136. package/tests/must-fail/multi-value-field.feature +18 -0
  137. package/tests/must-fail/registered-names.feature +25 -0
  138. package/tests/must-fail/select-list.feature +15 -0
  139. package/tests/must-fail/selector-files.feature +10 -0
  140. package/tests/must-fail/sorted-tables.feature +20 -0
  141. package/tests/must-fail/storage-before-a-page.feature +13 -0
  142. package/tests/must-fail/text-matching.feature +16 -0
  143. package/tests/must-fail/text-order.feature +15 -0
  144. package/tests/must-fail/viewport-top.feature +20 -0
  145. package/tests/must-fail/yaml-numbers.feature +48 -0
  146. package/tests/step-definitions/a11y.steps.js +24 -15
  147. package/tests/step-definitions/action.steps.js +53 -20
  148. package/tests/step-definitions/api.steps.js +349 -67
  149. package/tests/step-definitions/assertion.steps.js +100 -10
  150. package/tests/step-definitions/auth.steps.js +15 -18
  151. package/tests/step-definitions/clock.steps.js +22 -0
  152. package/tests/step-definitions/debug.steps.js +8 -0
  153. package/tests/step-definitions/dialog.steps.js +7 -0
  154. package/tests/step-definitions/element.steps.js +132 -17
  155. package/tests/step-definitions/field.steps.js +412 -96
  156. package/tests/step-definitions/form.steps.js +88 -37
  157. package/tests/step-definitions/iframe.steps.js +89 -29
  158. package/tests/step-definitions/input.steps.js +26 -7
  159. package/tests/step-definitions/javascript.steps.js +64 -22
  160. package/tests/step-definitions/modal.steps.js +79 -13
  161. package/tests/step-definitions/navigation.steps.js +14 -0
  162. package/tests/step-definitions/network.steps.js +15 -5
  163. package/tests/step-definitions/response.steps.js +6 -4
  164. package/tests/step-definitions/responsive.steps.js +26 -33
  165. package/tests/step-definitions/screenshot.steps.js +25 -8
  166. package/tests/step-definitions/scroll.steps.js +20 -0
  167. package/tests/step-definitions/selectors.steps.js +95 -48
  168. package/tests/step-definitions/storage.steps.js +38 -13
  169. package/tests/step-definitions/table.steps.js +81 -6
  170. package/tests/step-definitions/video.steps.js +52 -55
  171. package/tests/step-definitions/wait.steps.js +88 -23
  172. package/tests/step-definitions/web-first.steps.js +69 -35
  173. package/tests/step-definitions/webship.js +741 -145
  174. package/tests/step-definitions/xml.steps.js +49 -15
  175. package/tests/step-definitions/yaml.steps.js +45 -20
@@ -0,0 +1,30 @@
1
+ @must-fail
2
+ Feature: Fill steps that must fail, and what they say
3
+ tests/check-must-fail.js runs these scenarios and checks that each one
4
+ fails at its last step with the message its description announces, the
5
+ address of the page and a hint, within a few seconds.
6
+
7
+ Scenario: A field that is hidden
8
+ Fails with: The field "Hidden note" is on the page but hidden, so it cannot be filled.
9
+ Given I am on "/fill-unreachable.html"
10
+ When I fill in "Hidden note" with "Some words"
11
+
12
+ Scenario: A field that is disabled
13
+ Fails with: The field "Locked code" is disabled, so it cannot be filled.
14
+ Given I am on "/fill-unreachable.html"
15
+ When I fill in "Locked code" with "X2"
16
+
17
+ Scenario: A field that is read-only
18
+ Fails with: The field "Reference" is read-only, so it cannot be filled.
19
+ Given I am on "/fill-unreachable.html"
20
+ When I fill in "R-2" for "Reference"
21
+
22
+ Scenario: A hidden field named by attribute
23
+ Fails with: The field "#note" is on the page but hidden, so it cannot be filled.
24
+ Given I am on "/fill-unreachable.html"
25
+ When I fill in "#note" with "Some words" by attr
26
+
27
+ Scenario: A field named by attribute that is not on the page
28
+ Fails with: No field with "no-such-field" was found after 5 seconds.
29
+ Given I am on "/fill-unreachable.html"
30
+ When I fill in "no-such-field" with "Some words" by attr
@@ -0,0 +1,17 @@
1
+ @must-fail
2
+ Feature: Iframe steps that must fail, and what they say
3
+ tests/check-must-fail.js runs these scenarios and checks that each one
4
+ fails at its last step with the message its description announces, the
5
+ address of the page and a hint.
6
+
7
+ Scenario: A text that is not inside the iframe
8
+ Fails with: The text "Payment received" was not found inside the iframe after 5 seconds.
9
+ Given I am on "/iframe.html"
10
+ When I switch to iframe "#order-frame"
11
+ Then I should see "Payment received" inside the iframe
12
+
13
+ Scenario: A text that is inside the iframe
14
+ Fails with: The text "Order form inside the iframe" is inside the iframe, but it should not be.
15
+ Given I am on "/iframe.html"
16
+ When I switch to iframe "#order-frame"
17
+ Then I should not see "Order form inside the iframe" inside the iframe
@@ -0,0 +1,26 @@
1
+ @must-fail
2
+ Feature: Modal steps that must fail, and what they say
3
+ tests/check-must-fail.js runs these scenarios and checks that each one
4
+ fails at its last step with the message its description announces, the
5
+ address of the page and a hint, within a few seconds.
6
+
7
+ Scenario: A click in the modal when no modal is open
8
+ Fails with: No modal is open: none was visible after 5 seconds.
9
+ Given I am on "/modal.html"
10
+ When I click "OK" in the modal
11
+
12
+ Scenario: A click on an element in the modal when no modal is open
13
+ Fails with: No modal is open: none was visible after 5 seconds.
14
+ Given I am on "/modal.html"
15
+ When I click on "#close-btn" in the modal
16
+
17
+ Scenario: Closing the modal when no modal is open
18
+ Fails with: No modal is open: none was visible after 5 seconds.
19
+ Given I am on "/modal.html"
20
+ When I close the modal
21
+
22
+ Scenario: A button the open modal does not have
23
+ Fails with: The open modal has no button or link "Launch".
24
+ Given I am on "/modal.html"
25
+ When I click on the element "#open"
26
+ And I click "Launch" in the modal
@@ -0,0 +1,18 @@
1
+ @must-fail
2
+ Feature: Multi-value steps that must fail, and what they say
3
+ tests/check-must-fail.js runs these scenarios and checks that each one
4
+ fails at its last step with the message its description announces, the
5
+ address of the page and a hint, within a few seconds.
6
+
7
+ Scenario: A multi-value field that is not on the page
8
+ Fails with: No multi-value field "Hobbies" was found after 5 seconds.
9
+ Given I am on "/multi-value-fields.html"
10
+ When I fill in the multi-value field "Hobbies" with the following values:
11
+ | chess |
12
+
13
+ Scenario: More values than the field has inputs
14
+ Fails with: The multi-value field "Websites" has 1 input for 2 values.
15
+ Given I am on "/multi-value-fields.html"
16
+ When I fill in the multi-value field "Websites" with the following values:
17
+ | https://example.com |
18
+ | https://example.org |
@@ -0,0 +1,25 @@
1
+ @must-fail
2
+ Feature: A name of the selector registry given to a step that does not read it
3
+ A step that takes a text, a label or a CSS selector in quotes does not read
4
+ the selector registry. tests/check-must-fail.js runs these scenarios and
5
+ checks that each one fails at its last step with the message its
6
+ description announces (here: the hint that names the registry), the address
7
+ of the page and a hint.
8
+
9
+ Scenario: A registered name given to a web-first step
10
+ Fails with: "premium-banner" is a name of the selector registry (.promo-banner), but this step does not read the registry. Use: I see visible premium-banner, or: ".promo-banner" should be visible
11
+ Given I am on "/registered-names.html"
12
+ When I add "premium-banner" selector for ".promo-banner" css selector
13
+ Then "premium-banner" should be visible
14
+
15
+ Scenario: A registered name given to an element step
16
+ Fails with: "premium-banner" is a name of the selector registry (.promo-banner), but this step does not read the registry. Use: the element ".promo-banner" should be at the top of the viewport
17
+ Given I am on "/registered-names.html"
18
+ When I add "premium-banner" selector for ".promo-banner" css selector
19
+ Then the element "premium-banner" should be at the top of the viewport
20
+
21
+ Scenario: A registered name given to the fill step
22
+ Fails with: "search box" is a name of the selector registry (.search-box input), but this step does not read the registry. Use: I fill in the field ".search-box input" with "laptops"
23
+ Given I am on "/registered-names.html"
24
+ When I add "search box" selector for ".search-box input" css selector
25
+ And I fill in "search box" with "laptops"
@@ -0,0 +1,15 @@
1
+ @must-fail
2
+ Feature: Select steps that must fail, and what they say
3
+ tests/check-must-fail.js runs these scenarios and checks that each one
4
+ fails at its last step with the message its description announces, the
5
+ address of the page and a hint, within a few seconds.
6
+
7
+ Scenario: A select list that is not on the page
8
+ Fails with: No select list with the label, the name or the id "Bikes" was found after 5 seconds.
9
+ Given I am on "/select-by-label.html"
10
+ When I select "Saab" from "Bikes"
11
+
12
+ Scenario: An option that is not in the select list
13
+ Fails with: The select list "Cars" has no option "Tesla".
14
+ Given I am on "/select-by-label.html"
15
+ When I select "Tesla" from "Cars"
@@ -0,0 +1,10 @@
1
+ @must-fail
2
+ Feature: Selector files that must fail, and what they say
3
+ tests/check-must-fail.js runs these scenarios and checks that each one fails
4
+ at its last step with the message its description announces, the address of
5
+ the page and a hint.
6
+
7
+ Scenario: A selector file that is not there
8
+ Fails with: The selector file "no-such-selectors.json" was not found.
9
+ Given I am on homepage
10
+ When I add selectors from "no-such-selectors.json" file
@@ -0,0 +1,20 @@
1
+ @must-fail
2
+ Feature: Sorted-table assertions that must fail, and what they say
3
+ tests/check-must-fail.js runs these scenarios and checks that each one
4
+ fails at its last step with the message its description announces, the
5
+ address of the page and a hint.
6
+
7
+ Scenario: A price column out of order
8
+ Fails with: The table "#unsorted" is not sorted by "Price" in ascending order: row 1 ("$49.99") comes before row 2 ("$9.99").
9
+ Given I am on "/sorted-tables.html"
10
+ Then the table "#unsorted" should be sorted by "Price" in "ascending" order
11
+
12
+ Scenario: A column that is not in the table
13
+ Fails with: The table "#prices" has no "Colour" column.
14
+ Given I am on "/sorted-tables.html"
15
+ Then the table "#prices" should be sorted by "Colour" in "ascending" order
16
+
17
+ Scenario: A table that is not on the page
18
+ Fails with: No table matches "#no-such-table".
19
+ Given I am on "/sorted-tables.html"
20
+ Then the table "#no-such-table" should be sorted by "Price" in "ascending" order
@@ -0,0 +1,13 @@
1
+ @must-fail
2
+ Feature: Storage steps before the first page, and what they say
3
+ tests/check-must-fail.js runs these scenarios and checks that each one fails
4
+ at its last step with the message its description announces, the address of
5
+ the page and a hint.
6
+
7
+ Scenario: Local storage set before a page of the site is open
8
+ Fails with: Could not set the local storage "theme": the page has no site yet.
9
+ Given the local storage "theme" is set to "dark"
10
+
11
+ Scenario: Session storage cleared before a page of the site is open
12
+ Fails with: Could not clear the session storage: the page has no site yet.
13
+ Given session storage is cleared
@@ -0,0 +1,16 @@
1
+ @must-fail
2
+ Feature: Page-text assertions that must fail, whatever the letter case
3
+ `I should not see` reads the page the way `I should see` does: letter case
4
+ ignored, hidden text included. tests/check-must-fail.js runs these
5
+ scenarios and checks that each one fails at its last step with the message
6
+ its description announces, the address of the page and a hint.
7
+
8
+ Scenario: A text that is on the page in another letter case
9
+ Fails with: The text "next page" is on the page, but it should not be.
10
+ Given I am on "/text-matching.html"
11
+ Then I should not see "next page"
12
+
13
+ Scenario: A hidden text that is on the page
14
+ Fails with: The text "members save 10 percent" is on the page, but it should not be.
15
+ Given I am on "/text-matching.html"
16
+ Then I should not see "members save 10 percent"
@@ -0,0 +1,15 @@
1
+ @must-fail
2
+ Feature: Text-order assertions that must fail, and what they say
3
+ tests/check-must-fail.js runs these scenarios and checks that each one
4
+ fails at its last step with the message its description announces, the
5
+ address of the page and a hint.
6
+
7
+ Scenario: The first places on the whole page are in the other order
8
+ Fails with: The text "Products" does not appear after the text "Home" on the page.
9
+ Given I am on "/text-order.html"
10
+ Then the text "Products" should appear after the text "Home"
11
+
12
+ Scenario: A text that is not on the page
13
+ Fails with: The text "Desktops" is not on the page.
14
+ Given I am on "/text-order.html"
15
+ Then the text "Desktops" should appear after the text "Home"
@@ -0,0 +1,20 @@
1
+ @must-fail
2
+ Feature: Top-of-the-viewport assertions that must fail, and what they say
3
+ tests/check-must-fail.js runs these scenarios and checks that each one
4
+ fails at its last step with the message its description announces, the
5
+ address of the page and a hint.
6
+
7
+ Scenario: An element far below the top
8
+ Fails with: The element "#section-5" is not at the top of the viewport after 5 seconds.
9
+ Given I am on "/viewport-top.html"
10
+ Then the element "#section-5" should be at the top of the viewport
11
+
12
+ Scenario: An element that is hidden
13
+ Fails with: The element "#hidden-section" is on the page but not visible after 5 seconds.
14
+ Given I am on "/viewport-top.html"
15
+ Then the element "#hidden-section" should be at the top of the viewport
16
+
17
+ Scenario: An element that is not on the page
18
+ Fails with: No element matches "#no-such-section" after 5 seconds.
19
+ Given I am on "/viewport-top.html"
20
+ Then the element "#no-such-section" should be at the top of the viewport
@@ -0,0 +1,48 @@
1
+ @must-fail
2
+ Feature: YAML numbers that must fail, and what they say
3
+ tests/check-must-fail.js runs these scenarios and checks that each one fails
4
+ at its last step with the message its description announces, the address of
5
+ the page and a hint.
6
+
7
+ Scenario: A quoted number is a string, not a number
8
+ Fails with: The YAML value at "/spec/replicas" is the string "3", not a number.
9
+ Given the YAML response content is the following:
10
+ """
11
+ spec:
12
+ replicas: "3"
13
+ """
14
+ Then the YAML value at "/spec/replicas" should be between 1 and 5
15
+
16
+ Scenario: A null is not zero
17
+ Fails with: The YAML value at "/timeout" is null, not a number.
18
+ Given the YAML response content is the following:
19
+ """
20
+ timeout: ~
21
+ """
22
+ Then the YAML value at "/timeout" should be greater than or equal to 0
23
+
24
+ Scenario: A boolean is not one
25
+ Fails with: The YAML value at "/retries" is the boolean true, not a number.
26
+ Given the YAML response content is the following:
27
+ """
28
+ retries: true
29
+ """
30
+ Then the YAML value at "/retries" should be less than or equal to 3
31
+
32
+ Scenario: A number that is not greater
33
+ Fails with: The YAML value at "/spec/replicas" is 3, not greater than 5.
34
+ Given the YAML response content is the following:
35
+ """
36
+ spec:
37
+ replicas: 3
38
+ """
39
+ Then the YAML value at "/spec/replicas" should be greater than 5
40
+
41
+ Scenario: A number out of the range
42
+ Fails with: The YAML value at "/spec/replicas" is 7, not between 1 and 5.
43
+ Given the YAML response content is the following:
44
+ """
45
+ spec:
46
+ replicas: 7
47
+ """
48
+ Then the YAML value at "/spec/replicas" should be between 1 and 5
@@ -881,7 +881,8 @@ Then(/^the page should not violate the accessibility rule "([^"]*)"$/, async fun
881
881
  });
882
882
 
883
883
  /**
884
- * Print every axe violation to stdout (debug aid). Strip from CI runs.
884
+ * Print every axe violation to stdout (debug aid), and attach the same text
885
+ * to the step, so the JSON report and the HTML report show it too.
885
886
  *
886
887
  * Example #1: Then I print accessibility violations
887
888
  * Example #2: When I am on "/checkout"
@@ -895,20 +896,24 @@ Then(/^the page should not violate the accessibility rule "([^"]*)"$/, async fun
895
896
  */
896
897
  Then(/^(I |we )*print accessibility violations$/, async function (pronounCase) {
897
898
  const result = await runAxe(this);
899
+ const lines = [];
898
900
  if (result.violations.length === 0) {
899
- console.log('\n--- Accessibility violations: none ---');
900
- return;
901
- }
902
- console.log('\n--- Accessibility violations ---');
903
- for (const v of result.violations) {
904
- console.log(`[${v.impact}] ${v.id} — ${v.help}`);
905
- console.log(` ${v.helpUrl}`);
906
- for (const n of v.nodes.slice(0, 3)) {
907
- console.log(` ${n.target.join(' ')}`);
908
- if (n.failureSummary) console.log(` ${n.failureSummary.split('\n')[0]}`);
901
+ lines.push('--- Accessibility violations: none ---');
902
+ } else {
903
+ lines.push('--- Accessibility violations ---');
904
+ for (const v of result.violations) {
905
+ lines.push(`[${v.impact}] ${v.id} — ${v.help}`);
906
+ lines.push(` ${v.helpUrl}`);
907
+ for (const n of v.nodes.slice(0, 3)) {
908
+ lines.push(` ${n.target.join(' ')}`);
909
+ if (n.failureSummary) lines.push(` ${n.failureSummary.split('\n')[0]}`);
910
+ }
911
+ if (v.nodes.length > 3) lines.push(` ... and ${v.nodes.length - 3} more node(s)`);
909
912
  }
910
- if (v.nodes.length > 3) console.log(` ... and ${v.nodes.length - 3} more node(s)`);
911
913
  }
914
+ const text = lines.join('\n');
915
+ console.log('\n' + text);
916
+ await this.attach(text, 'text/plain');
912
917
  });
913
918
 
914
919
  /**
@@ -1009,7 +1014,9 @@ Then(/^the page should pass the full accessibility check(?: at level "(A|AA|AAA)
1009
1014
 
1010
1015
  /**
1011
1016
  * The same whole-page check, reported rather than asserted. Use it to see
1012
- * where a page stands before deciding what to gate on.
1017
+ * where a page stands before deciding what to gate on. The report goes to
1018
+ * stdout and is attached to the step, so the JSON report and the HTML report
1019
+ * show it too.
1013
1020
  *
1014
1021
  * Example #1: Then I print the full accessibility check
1015
1022
  * Example #2: When I go to "/about-us"
@@ -1025,6 +1032,8 @@ Then(/^(?:I |we )*print the full accessibility check$/, async function () {
1025
1032
  const result = await runAxe(this, { tags: WCAG_TAGS.AA });
1026
1033
  const found = await structuralAudit(this.page);
1027
1034
  const lines = fullCheckReport(result.violations, found);
1028
- console.log(`\n--- Full accessibility check: ${this.page.url()} ---`);
1029
- console.log(lines.length ? lines.join('\n\n') : ' nothing to report');
1035
+ const text = `--- Full accessibility check: ${this.page.url()} ---\n` +
1036
+ (lines.length ? lines.join('\n\n') : ' nothing to report');
1037
+ console.log('\n' + text);
1038
+ await this.attach(text, 'text/plain');
1030
1039
  });
@@ -4,13 +4,12 @@
4
4
  // press, click (text / attr / row / link follow), and file attach.
5
5
 
6
6
  const { When } = require('@cucumber/cucumber');
7
- const path = require('path');
8
- const { buildSelector, friendly } = require('./webship');
7
+ const { buildSelector, friendly, resolveAssetFile, registeredNameHint } = require('./webship');
9
8
 
10
9
  // Wrap a Playwright action with a friendlier error pointing at the
11
10
  // failing locator + Gherkin step. Pass `label` describing the step
12
11
  // ("press button", "click link", ...) and the user-supplied target.
13
- async function actOrExplain(label, target, fn) {
12
+ async function actOrExplain(label, target, fn, registryHint) {
14
13
  try {
15
14
  await fn();
16
15
  } catch (e) {
@@ -19,6 +18,7 @@ async function actOrExplain(label, target, fn) {
19
18
  `Failed to ${label} "${target}".\n` +
20
19
  ` ${msg}\n` +
21
20
  ` Hints:\n` +
21
+ (registryHint ? ` - ${registryHint}\n` : '') +
22
22
  ` - Check the visible text matches exactly (case-sensitive).\n` +
23
23
  ` - Use the "by attr" variant if the element has no readable text.\n` +
24
24
  ` - Use "wait for ... to appear" if the element renders late.`
@@ -26,6 +26,25 @@ async function actOrExplain(label, target, fn) {
26
26
  }
27
27
  }
28
28
 
29
+ // What a press or a click step says when it was given a name of the selector
30
+ // registry: the bare-name click and the element click read a selector.
31
+ function clickRegistryHint(world, name) {
32
+ return registeredNameHint(world, name, {
33
+ bare: 'I click {name}',
34
+ withSelector: (selector) => `I click on the element "${selector}"`,
35
+ });
36
+ }
37
+
38
+ // The whole text of a link or a button as a person reads it. A template that
39
+ // prints the text on its own line (`<a>\n <span>Products</span>\n</a>`, the
40
+ // way Drupal's menus do) gives the element white space around its text, and
41
+ // a long label can break across lines: both still match, the text itself is
42
+ // matched whole and literally.
43
+ function wholeText(text) {
44
+ const words = String(text).trim().replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/\s+/g, '\\s+');
45
+ return new RegExp('^\\s*' + words + '\\s*$');
46
+ }
47
+
29
48
  // ---------------------------------------------------------------------------
30
49
  // Press / click — by visible text
31
50
  // ---------------------------------------------------------------------------
@@ -41,14 +60,13 @@ async function actOrExplain(label, target, fn) {
41
60
  *
42
61
  */
43
62
  When(/^(I |we )*press( the)* "([^"]*)?"( button)*$/, async function (pronounCase, theCase, element, buttonCase) {
44
- const esc = element.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
45
63
  const page = this.page;
46
64
  await actOrExplain('press button', element, async () => {
47
65
  await page.locator('button, input[type="button"], input[type="submit"], [role="button"], a')
48
- .filter({ hasText: new RegExp('^' + esc + '$') })
66
+ .filter({ hasText: wholeText(element) })
49
67
  .first()
50
68
  .click();
51
- });
69
+ }, clickRegistryHint(this, element));
52
70
  });
53
71
 
54
72
  /**
@@ -72,17 +90,17 @@ When(/^(I |we )*press "([^"]*)?" by( its)*(?: "([^"]*)?")* (attribute|attr)$/, a
72
90
  * Example #2: And I click "aboutUs"
73
91
  * Example #3: When we click "Read more"
74
92
  * Example #4: And click "Home"
93
+ * Example #5: When we click "Sign up"
75
94
  *
76
95
  */
77
96
  When(/^(I |we )*click "([^"]*)?"$/, async function (pronounCase, item) {
78
- const esc = item.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
79
97
  const page = this.page;
80
98
  await actOrExplain('click', item, async () => {
81
99
  await page.locator('a, button, [role="button"], input[type="button"], input[type="submit"]')
82
- .filter({ hasText: new RegExp('^' + esc + '$') })
100
+ .filter({ hasText: wholeText(item) })
83
101
  .first()
84
102
  .click();
85
- });
103
+ }, clickRegistryHint(this, item));
86
104
  });
87
105
 
88
106
  /**
@@ -92,6 +110,7 @@ When(/^(I |we )*click "([^"]*)?"$/, async function (pronounCase, item) {
92
110
  * Example #2: When I click "data-selector-about" by attribute
93
111
  * Example #3: And I click "about-us-css" by "class" attr
94
112
  * Example #4: And I click "about-us-id" by its "id" attribute
113
+ * Example #5: When we click "submit-button" by its "data-testid" attribute
95
114
  *
96
115
  */
97
116
  When(/^(I |we )*click "([^"]*)?" by( its)*(?: "([^"]*)?")* (attribute|attr)$/, async function (pronounCase, attrValue, itsCase, attr, attrWord) {
@@ -105,13 +124,13 @@ When(/^(I |we )*click "([^"]*)?" by( its)*(?: "([^"]*)?")* (attribute|attr)$/, a
105
124
  * Example #2: When I click "Delete" in the "Product A" row
106
125
  * Example #3: When we click "View Details" in the "Order #12345" row
107
126
  * Example #4: And I click "Download" in the "Report 2024" row
127
+ * Example #5: When we click "Archive" in the "Invoice 1042" row
108
128
  *
109
129
  */
110
130
  When(/^(I |we )*click "([^"]*)?" in( the)* "([^"]*)?" row$/, async function (pronounCase, clickText, theCase, rowIdentifier) {
111
- const esc = clickText.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
112
131
  const row = this.page.locator('tr').filter({ hasText: rowIdentifier }).first();
113
132
  const clickable = row.locator('a, button, [role="button"], input[type="submit"], input[type="button"]')
114
- .filter({ hasText: new RegExp('^' + esc + '$') });
133
+ .filter({ hasText: wholeText(clickText) });
115
134
  if (await clickable.count() > 0) {
116
135
  await clickable.first().click();
117
136
  } else {
@@ -122,7 +141,8 @@ When(/^(I |we )*click "([^"]*)?" in( the)* "([^"]*)?" row$/, async function (pro
122
141
  /**
123
142
  * Follow a link by its visible text.
124
143
  * Uses Playwright's accessibility-first `getByRole('link', { name })` with a
125
- * text-match fallback.
144
+ * text-match fallback, and follows the first link of that name a person can
145
+ * see: a hidden copy in a collapsed menu is passed over.
126
146
  *
127
147
  * Example #1: When I follow "Contact Us"
128
148
  * Example #2: When I follow "About"
@@ -136,21 +156,34 @@ When(/^(I |we )*click "([^"]*)?" in( the)* "([^"]*)?" row$/, async function (pro
136
156
  * Example #10: When I follow "Next"
137
157
  */
138
158
  When(/^(I |we )*follow "([^"]*)"$/, async function (pronounCase, link) {
139
- const esc = link.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
140
159
  const page = this.page;
141
160
  await actOrExplain('follow link', link, async () => {
142
- const loc = page.getByRole('link', { name: link, exact: true }).or(
143
- page.locator('a').filter({ hasText: new RegExp('^' + esc + '$') })
144
- ).first();
145
- await loc.click();
161
+ const matches = page.getByRole('link', { name: link, exact: true }).or(
162
+ page.locator('a').filter({ hasText: wholeText(link) })
163
+ );
164
+ // A site that repeats its links in a collapsed menu (a dropdown, a mobile
165
+ // menu kept in the page) puts a hidden copy first: the link a person sees
166
+ // and follows is the first visible one.
167
+ const visible = matches.filter({ visible: true }).first();
168
+ if (await visible.waitFor({ state: 'visible', timeout: 5000 }).then(() => true, () => false)) {
169
+ await visible.click();
170
+ return;
171
+ }
172
+ const found = await matches.count();
173
+ if (found > 0) {
174
+ throw new Error(`the page has ${found === 1 ? 'a link' : `${found} links`} named "${link}", but none is visible (a closed menu, a hidden section).`);
175
+ }
176
+ await matches.first().click();
146
177
  });
147
178
  });
148
179
 
149
180
  /**
150
181
  * Attach a file from tests/assets/ to a file input.
151
182
  *
152
- * The file path is resolved against `this.assetsFolder` (default
153
- * `tests/assets/`). The target selector must address an `<input type="file">`.
183
+ * A file name is looked for in the project's `tests/assets/`
184
+ * (`this.assetsFolder`), then as written from the project root; a file that
185
+ * is in neither fails with the paths tried. The target selector must address
186
+ * an `<input type="file">`.
154
187
  *
155
188
  * Example #1: When I attach the file "profile-icon.jpg" to "#profile-icon-upload"
156
189
  * Example #2: When we attach file "resume.pdf" to "#resume"
@@ -163,5 +196,5 @@ When(/^(I |we )*follow "([^"]*)"$/, async function (pronounCase, link) {
163
196
  *
164
197
  */
165
198
  When(/^(I |we )*attach( the)* file "([^"]*)?" to "([^"]*)?"$/, async function (pronounCase, theCase, fileName, element) {
166
- await this.page.locator(element).setInputFiles(path.resolve(this.assetsFolder, fileName));
199
+ await this.page.locator(element).setInputFiles(resolveAssetFile(this, fileName));
167
200
  });