webship-js 2.0.2 → 2.0.3

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 (162) hide show
  1. package/AGENTS.md +109 -0
  2. package/CLAUDE.md +317 -0
  3. package/bin/generate-reports.js +181 -9
  4. package/cucumber.js +10 -4
  5. package/docs/00-quick-start.md +102 -0
  6. package/docs/01-getting-started.md +102 -0
  7. package/docs/02-bbr-smart-waits.md +77 -0
  8. package/docs/03-selector-registry.md +95 -0
  9. package/docs/04-step-reference.md +728 -0
  10. package/docs/05-web-first-assertions.md +91 -0
  11. package/docs/06-network-and-dialogs.md +83 -0
  12. package/docs/07-auth-state.md +75 -0
  13. package/docs/08-clock-mocking.md +59 -0
  14. package/docs/09-api-testing.md +114 -0
  15. package/docs/10-accessibility.md +167 -0
  16. package/docs/11-debugging.md +129 -0
  17. package/docs/12-ai-agent-guide.md +338 -0
  18. package/docs/13-faq.md +236 -0
  19. package/docs/14-recipes-cookbook.md +255 -0
  20. package/docs/15-tag-conventions.md +76 -0
  21. package/docs/advanced-screenshots/then-i-save-fullscreen-screenshot.md +36 -0
  22. package/docs/advanced-screenshots/then-i-save-width-x-height-screenshot.md +34 -0
  23. package/docs/advanced-screenshots/when-i-save-screenshot-name-filename.md +45 -0
  24. package/docs/advanced-screenshots.md +52 -0
  25. package/docs/advanced-selectors.md +18 -0
  26. package/docs/api-step-definitions.md +45 -0
  27. package/docs/diffy-step-definitions/then-compare-diffy-env1-env2.md +30 -0
  28. package/docs/diffy-step-definitions/then-create-diffy-comparison-name-value.md +21 -0
  29. package/docs/diffy-step-definitions/then-create-diffy-comparison.md +25 -0
  30. package/docs/diffy-step-definitions/then-create-diffy-screenshot-environment-name.md +35 -0
  31. package/docs/diffy-step-definitions/then-i-take-screenshot.md +21 -0
  32. package/docs/diffy-step-definitions/then-i-take-screenshots-all-breakpoints.md +27 -0
  33. package/docs/diffy-step-definitions/then-send-screenshots-diffy-name-value.md +27 -0
  34. package/docs/diffy-step-definitions/then-upload-folder-url-diffy-snapshotname.md +28 -0
  35. package/docs/diffy-step-definitions/then-wait-diffy-comparison-complete.md +21 -0
  36. package/docs/diffy-step-definitions/when-i-resize-window-number.md +29 -0
  37. package/docs/diffy-step-definitions.md +21 -0
  38. package/docs/global-settings.md +244 -0
  39. package/docs/index.md +104 -0
  40. package/docs/install-webship-js/ddev-webship-js.md +52 -0
  41. package/docs/install-webship-js.md +35 -0
  42. package/docs/overview.md +41 -0
  43. package/docs/step-definitions/given-i-am-anonymous-user.md +67 -0
  44. package/docs/step-definitions/given-i-am-homepage.md +68 -0
  45. package/docs/step-definitions/given-i-am-specific-page.md +72 -0
  46. package/docs/step-definitions/then-i-should-be.md +56 -0
  47. package/docs/step-definitions/then-i-should-see.md +62 -0
  48. package/docs/step-definitions/then-item-checkbox.md +54 -0
  49. package/docs/step-definitions/then-item-link-should-contain-url.md +84 -0
  50. package/docs/step-definitions/then-item-should-contain.md +67 -0
  51. package/docs/step-definitions/then-radio-button-value-should-be-selected.md +68 -0
  52. package/docs/step-definitions/then-response-status-code-should-be-number.md +69 -0
  53. package/docs/step-definitions/then-value-radio-button-selected.md +62 -0
  54. package/docs/step-definitions/when-i-attach-file-file-name-element.md +71 -0
  55. package/docs/step-definitions/when-i-check-checkbox.md +60 -0
  56. package/docs/step-definitions/when-i-click-link.md +51 -0
  57. package/docs/step-definitions/when-i-click-operation-text-row.md +71 -0
  58. package/docs/step-definitions/when-i-fill.md +59 -0
  59. package/docs/step-definitions/when-i-go-homepage.md +60 -0
  60. package/docs/step-definitions/when-i-go-specific-page.md +67 -0
  61. package/docs/step-definitions/when-i-move-backward-one-page.md +49 -0
  62. package/docs/step-definitions/when-i-move-forward-one-page.md +58 -0
  63. package/docs/step-definitions/when-i-press-button.md +58 -0
  64. package/docs/step-definitions/when-i-reload-page.md +51 -0
  65. package/docs/step-definitions/when-i-scroll.md +73 -0
  66. package/docs/step-definitions/when-i-select-option-select-list.md +53 -0
  67. package/docs/step-definitions/when-i-select-radio-button-value.md +62 -0
  68. package/docs/step-definitions/when-i-uncheck-checkbox.md +57 -0
  69. package/docs/step-definitions/when-i-wait-ajax-finish.md +64 -0
  70. package/docs/step-definitions/when-i-wait.md +62 -0
  71. package/docs/step-definitions.md +50 -0
  72. package/examples/a11y.html +31 -0
  73. package/examples/cookies.html +10 -0
  74. package/examples/date.html +12 -0
  75. package/examples/element.html +11 -0
  76. package/examples/field.html +24 -0
  77. package/examples/keyboard.html +11 -0
  78. package/examples/links.html +9 -0
  79. package/examples/modal.html +14 -0
  80. package/examples/path.html +3 -0
  81. package/examples/table.html +13 -0
  82. package/package.json +10 -3
  83. package/playwright.config.ts +3 -2
  84. package/tests/features/a11y.feature +39 -0
  85. package/tests/features/cookie.feature +13 -0
  86. package/tests/features/date.feature +11 -0
  87. package/tests/features/element.feature +16 -0
  88. package/tests/features/field.feature +25 -0
  89. package/tests/features/keyboard.feature +10 -0
  90. package/tests/features/link.feature +11 -0
  91. package/tests/features/modal-advanced-example.feature +1 -1
  92. package/tests/features/modal.feature +11 -0
  93. package/tests/features/path.feature +16 -0
  94. package/tests/features/response.feature +8 -0
  95. package/tests/features/responsive.feature +10 -0
  96. package/tests/features/table.feature +18 -0
  97. package/tests/features/wait.feature +7 -0
  98. package/tests/features/yaml.feature +102 -0
  99. package/tests/reports/README.md +55 -0
  100. package/tests/selectors/_canonical-keys.json +113 -0
  101. package/tests/selectors/back-end-selectors.json +7 -1
  102. package/tests/selectors/cms-contentful-admin.json +35 -0
  103. package/tests/selectors/cms-craft-admin.json +39 -0
  104. package/tests/selectors/cms-drupal-cms-gin.json +56 -0
  105. package/tests/selectors/cms-drupal-core-claro.json +50 -0
  106. package/tests/selectors/cms-generic-admin.json +34 -0
  107. package/tests/selectors/cms-ghost-admin.json +34 -0
  108. package/tests/selectors/cms-joomla-admin.json +41 -0
  109. package/tests/selectors/cms-magento2-admin.json +32 -0
  110. package/tests/selectors/cms-prestashop-admin.json +38 -0
  111. package/tests/selectors/cms-shopify-admin.json +25 -0
  112. package/tests/selectors/cms-strapi-admin.json +42 -0
  113. package/tests/selectors/cms-typo3-admin.json +41 -0
  114. package/tests/selectors/cms-woocommerce-front.json +50 -0
  115. package/tests/selectors/cms-wordpress-admin.json +31 -0
  116. package/tests/selectors/framework-ant-design.json +80 -0
  117. package/tests/selectors/framework-bootstrap.json +86 -0
  118. package/tests/selectors/framework-bulma.json +74 -0
  119. package/tests/selectors/framework-chakra.json +58 -0
  120. package/tests/selectors/framework-foundation.json +51 -0
  121. package/tests/selectors/framework-material-ui.json +72 -0
  122. package/tests/selectors/framework-shadcn.json +51 -0
  123. package/tests/selectors/framework-tailwind.json +40 -0
  124. package/tests/selectors/framework-vuetify.json +61 -0
  125. package/tests/step-definitions/a11y.steps.js +798 -0
  126. package/tests/step-definitions/action.steps.js +167 -0
  127. package/tests/step-definitions/{webship-api.js → api.steps.js} +24 -7
  128. package/tests/step-definitions/assertion.steps.js +352 -0
  129. package/tests/step-definitions/auth.steps.js +124 -0
  130. package/tests/step-definitions/clock.steps.js +128 -0
  131. package/tests/step-definitions/cookie.steps.js +216 -0
  132. package/tests/step-definitions/debug.steps.js +31 -0
  133. package/tests/step-definitions/dialog.steps.js +193 -0
  134. package/tests/step-definitions/element.steps.js +314 -0
  135. package/tests/step-definitions/field.steps.js +653 -0
  136. package/tests/step-definitions/file-download.steps.js +193 -0
  137. package/tests/step-definitions/form.steps.js +333 -0
  138. package/tests/step-definitions/iframe.steps.js +178 -0
  139. package/tests/step-definitions/input.steps.js +163 -0
  140. package/tests/step-definitions/javascript.steps.js +71 -0
  141. package/tests/step-definitions/keyboard.steps.js +78 -0
  142. package/tests/step-definitions/link.steps.js +142 -0
  143. package/tests/step-definitions/metatag.steps.js +91 -0
  144. package/tests/step-definitions/modal.steps.js +219 -0
  145. package/tests/step-definitions/navigation.steps.js +218 -0
  146. package/tests/step-definitions/network.steps.js +238 -0
  147. package/tests/step-definitions/path.steps.js +141 -0
  148. package/tests/step-definitions/response.steps.js +98 -0
  149. package/tests/step-definitions/responsive.steps.js +123 -0
  150. package/tests/step-definitions/rest.steps.js +111 -0
  151. package/tests/step-definitions/{webship-screenshot.js → screenshot.steps.js} +1 -5
  152. package/tests/step-definitions/scroll.steps.js +189 -0
  153. package/tests/step-definitions/{webship-selectors.js → selectors.steps.js} +46 -11
  154. package/tests/step-definitions/storage.steps.js +194 -0
  155. package/tests/step-definitions/table.steps.js +181 -0
  156. package/tests/step-definitions/wait.steps.js +400 -0
  157. package/tests/step-definitions/web-first.steps.js +296 -0
  158. package/tests/step-definitions/webship.js +552 -1507
  159. package/tests/step-definitions/xml.steps.js +409 -0
  160. package/tests/step-definitions/yaml.steps.js +911 -0
  161. package/tests/step-definitions-diffy/webship-diffy.js +0 -13
  162. package/tsconfig.json +19 -3
@@ -0,0 +1,167 @@
1
+ 'use strict';
2
+
3
+ // All "do an action" step definitions live here:
4
+ // press, click (text / attr / row / link follow), and file attach.
5
+
6
+ const { When } = require('@cucumber/cucumber');
7
+ const path = require('path');
8
+ const { buildSelector } = require('./webship');
9
+
10
+ // Wrap a Playwright action with a friendlier error pointing at the
11
+ // failing locator + Gherkin step. Pass `label` describing the step
12
+ // ("press button", "click link", ...) and the user-supplied target.
13
+ async function actOrExplain(label, target, fn) {
14
+ try {
15
+ await fn();
16
+ } catch (e) {
17
+ const msg = (e.message || '').split('\n')[0];
18
+ throw new Error(
19
+ `Failed to ${label} "${target}".\n` +
20
+ ` ${msg}\n` +
21
+ ` Hints:\n` +
22
+ ` - Check the visible text matches exactly (case-sensitive).\n` +
23
+ ` - Use the "by attr" variant if the element has no readable text.\n` +
24
+ ` - Use "wait for ... to appear" if the element renders late.`
25
+ );
26
+ }
27
+ }
28
+
29
+ // ---------------------------------------------------------------------------
30
+ // Press / click — by visible text
31
+ // ---------------------------------------------------------------------------
32
+
33
+ /**
34
+ * Press a button, submit input, or link by its visible text.
35
+ *
36
+ * Example #1: When I press "Log In"
37
+ * Example #2: And I press the "Log In" button
38
+ * Example #3: And I press the "Save as" button
39
+ * Example #4: When we press "Submit"
40
+ * Example #5: And press "Cancel"
41
+ *
42
+ */
43
+ When(/^(I |we )*press( the)* "([^"]*)?"( button)*$/, async function (pronounCase, theCase, element, buttonCase) {
44
+ const esc = element.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
45
+ const page = this.page;
46
+ await actOrExplain('press button', element, async () => {
47
+ await page.locator('button, input[type="button"], input[type="submit"], [role="button"], a')
48
+ .filter({ hasText: new RegExp('^' + esc + '$') })
49
+ .first()
50
+ .click();
51
+ });
52
+ });
53
+
54
+ /**
55
+ * Press a button by its attribute (id, class, name, placeholder, data-*).
56
+ *
57
+ * Example #1: When I press "btn-pressid" by attr
58
+ * Example #2: When I press "btn-pressid" by attribute
59
+ * Example #3: And I press "Your full name" by "placeholder" attribute
60
+ * Example #4: And I press "Your full name" by its "placeholder" attribute
61
+ * Example #5: And I press "save-name" by "data-selector" attr
62
+ *
63
+ */
64
+ When(/^(I |we )*press "([^"]*)?" by( its)*(?: "([^"]*)?")* (attribute|attr)$/, async function (pronounCase, attrValue, itsCase, attr, attrWord) {
65
+ await this.page.locator(buildSelector(attrValue, attr)).first().click();
66
+ });
67
+
68
+ /**
69
+ * Click a link or button by its visible text.
70
+ *
71
+ * Example #1: When I click "Contact Us"
72
+ * Example #2: And I click "aboutUs"
73
+ * Example #3: When we click "Read more"
74
+ * Example #4: And click "Home"
75
+ *
76
+ */
77
+ When(/^(I |we )*click "([^"]*)?"$/, async function (pronounCase, item) {
78
+ const esc = item.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
79
+ const page = this.page;
80
+ await actOrExplain('click', item, async () => {
81
+ await page.locator('a, button, [role="button"], input[type="button"], input[type="submit"]')
82
+ .filter({ hasText: new RegExp('^' + esc + '$') })
83
+ .first()
84
+ .click();
85
+ });
86
+ });
87
+
88
+ /**
89
+ * Click a link or button by its attribute (id, class, name, data-*).
90
+ *
91
+ * Example #1: When I click "#about-us-id" by attr
92
+ * Example #2: When I click "data-selector-about" by attribute
93
+ * Example #3: And I click "about-us-css" by "class" attr
94
+ * Example #4: And I click "about-us-id" by its "id" attribute
95
+ *
96
+ */
97
+ When(/^(I |we )*click "([^"]*)?" by( its)*(?: "([^"]*)?")* (attribute|attr)$/, async function (pronounCase, attrValue, itsCase, attr, attrWord) {
98
+ await this.page.locator(buildSelector(attrValue, attr)).first().click();
99
+ });
100
+
101
+ /**
102
+ * Click a clickable element inside a table row identified by text.
103
+ *
104
+ * Example #1: When I click "Edit" in the "John Smith" row
105
+ * Example #2: When I click "Delete" in the "Product A" row
106
+ * Example #3: When we click "View Details" in the "Order #12345" row
107
+ * Example #4: And I click "Download" in the "Report 2024" row
108
+ *
109
+ */
110
+ When(/^(I |we )*click "([^"]*)?" in( the)* "([^"]*)?" row$/, async function (pronounCase, clickText, theCase, rowIdentifier) {
111
+ const esc = clickText.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
112
+ const row = this.page.locator('tr').filter({ hasText: rowIdentifier }).first();
113
+ const clickable = row.locator('a, button, [role="button"], input[type="submit"], input[type="button"]')
114
+ .filter({ hasText: new RegExp('^' + esc + '$') });
115
+ if (await clickable.count() > 0) {
116
+ await clickable.first().click();
117
+ } else {
118
+ await row.getByText(clickText, { exact: true }).first().click();
119
+ }
120
+ });
121
+
122
+ /**
123
+ * Follow a link by its visible text.
124
+ * Uses Playwright's accessibility-first `getByRole('link', { name })` with a
125
+ * text-match fallback.
126
+ *
127
+ * Example #1: When I follow "Contact Us"
128
+ * Example #2: When I follow "About"
129
+ * Example #3: When we follow "Home"
130
+ * Example #4: And follow "Read more"
131
+ * Example #5: When I follow "Documentation"
132
+ * Example #6: When we follow "Sign in"
133
+ * Example #7: When I follow "Log out"
134
+ * Example #8: When I follow "Download report"
135
+ * Example #9: And I follow "Previous"
136
+ * Example #10: When I follow "Next"
137
+ */
138
+ When(/^(I |we )*follow "([^"]*)"$/, async function (pronounCase, link) {
139
+ const esc = link.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
140
+ const page = this.page;
141
+ 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();
146
+ });
147
+ });
148
+
149
+ /**
150
+ * Attach a file from tests/assets/ to a file input.
151
+ *
152
+ * The file path is resolved against `this.assetsFolder` (default
153
+ * `tests/assets/`). The target selector must address an `<input type="file">`.
154
+ *
155
+ * Example #1: When I attach the file "profile-icon.jpg" to "#profile-icon-upload"
156
+ * Example #2: When we attach file "resume.pdf" to "#resume"
157
+ * Example #3: And I attach the file "logo.svg" to "input[name=logo]"
158
+ * Example #4: When I attach file "report-2026-q1.csv" to "[data-testid=csv-upload]"
159
+ * Example #5: Given I am on "/upload"
160
+ * When I attach the file "video.mp4" to "#video-input"
161
+ * And I press "Upload"
162
+ * Then I should see "Upload complete"
163
+ *
164
+ */
165
+ 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));
167
+ });
@@ -49,7 +49,7 @@ function getNestedProperty(obj, path) {
49
49
  * Adds Basic Authentication header to the next request.
50
50
  *
51
51
  * Example #1: Given I am authenticating as "admin" with "password123" password
52
- * Example #2: Given We are authenticating as "user@example.com" with "secret" password
52
+ * Example #2: Given we are authenticating as "user@example.com" with "secret" password
53
53
  * Example #3: Given I am authenticating as "api-user" with "pass!word" password
54
54
  * Example #4: Given we are authenticating as "reader" with "readonly" password
55
55
  *
@@ -68,7 +68,7 @@ Given(/^(?:I am|we are) authenticating as "([^"]*)" with "([^"]*)" password$/, f
68
68
  * Example #3: Given I set header "Accept" with value "application/xml"
69
69
  * Example #4: Given I set header "Accept" with value "application/json"
70
70
  * Example #5: Given we set header "X-Api-Key" with value "abcd-1234"
71
- * Example #6: Given I set header "User-Agent" with value "webship-js"
71
+ * Example #6: Given I set header "User-Agent" with value "test-runner"
72
72
  * Example #7: Given we set header "Accept-Language" with value "en-US"
73
73
  * Example #8: Given I set header "If-None-Match" with value "etag-xyz"
74
74
  *
@@ -109,7 +109,7 @@ Given(/^(?:the API base URL is|I set the API base URL to|the base URL is) "([^"]
109
109
  * Example #3: Given the header "Accept" is "application/json"
110
110
  * Example #4: Given we set the header "X-Api-Key" to "abcd-1234"
111
111
  * Example #5: Given I set the header "If-Match" to "etag-123"
112
- * Example #6: Given the header "User-Agent" is "webship-js"
112
+ * Example #6: Given the header "User-Agent" is "test-runner"
113
113
  * Example #7: Given we set the header "Accept-Language" to "en-US"
114
114
  * Example #8: Given I set the header "Cache-Control" to "no-cache"
115
115
  *
@@ -132,7 +132,7 @@ Given(/^(?:I set the header|we set the header|the header) "([^"]*)" (?:to|is) "(
132
132
  * | Accept-Language | en-US |
133
133
  *
134
134
  * Example #3: Given I set the following headers:
135
- * | User-Agent | webship-js |
135
+ * | User-Agent | test-runner |
136
136
  * | Cache-Control | no-cache |
137
137
  * | If-None-Match | etag-xyz |
138
138
  *
@@ -647,8 +647,15 @@ Then(/^(?:the JSON response should not have property|the API response should not
647
647
  /**
648
648
  * Verify the response is valid JSON.
649
649
  *
650
+ * Two equivalent phrasings.
651
+ *
650
652
  * Example #1: Then the response should be valid JSON
651
653
  * Example #2: Then the API response should be valid JSON
654
+ * Example #3: And the response should be valid JSON
655
+ * Example #4: When I send a GET request to "/api/users"
656
+ * Then the API response should be valid JSON
657
+ * Example #5: When I send a POST request to "/api/orders"
658
+ * Then the response should be valid JSON
652
659
  */
653
660
  Then(/^(?:the response should be valid JSON|the API response should be valid JSON)$/, function () {
654
661
  if (!apiResponse) {
@@ -683,9 +690,19 @@ Then(/^(?:the response header|the header) "([^"]*)" should (?:be|contain) "([^"]
683
690
  });
684
691
 
685
692
  /**
686
- * Prints last API response body for debugging.
687
- *
688
- * Example: Then print API response
693
+ * Prints the most recent API response body to stdout for debugging.
694
+ *
695
+ * Strip before merging — this is a developer aid only.
696
+ *
697
+ * Example #1: Then print API response
698
+ * Example #2: When I send a GET request to "/api/users"
699
+ * Then print API response
700
+ * Example #3: And print API response
701
+ * Example #4: When I send a POST request to "/api/login"
702
+ * Then the API response code should be 200
703
+ * And print API response
704
+ * Example #5: When I send a DELETE request to "/api/orders/1"
705
+ * Then print API response
689
706
  */
690
707
  Then(/^print API response$/, function () {
691
708
  if (!apiResponse) {
@@ -0,0 +1,352 @@
1
+ 'use strict';
2
+
3
+ // All page-level assertion step definitions live here:
4
+ // see / not see text, in element, in row, link href, response body, response
5
+ // status code, element existence, CSS property, regex matching, count.
6
+ //
7
+ // Field-level (checkbox/radio/field-contains) assertions live in field.steps.js.
8
+ // URL/path assertions live in navigation.steps.js.
9
+ // Modal assertions live in modal.steps.js.
10
+
11
+ const { Then } = require('@cucumber/cucumber');
12
+ const assert = require('assert');
13
+ const axios = require('axios');
14
+ const { buildSelector, getLocatorText } = require('./webship');
15
+
16
+ // ---------------------------------------------------------------------------
17
+ // Plain page-text
18
+ // ---------------------------------------------------------------------------
19
+
20
+ /**
21
+ * Assert that text is or is not present on the page.
22
+ *
23
+ * Example #1: Then I should see "Welcome"
24
+ * Example #2: Then we should see "Your accounts for the group is public"
25
+ * Example #3: Then I should not see "Access denied"
26
+ * Example #4: Then we should not see "Edit layout"
27
+ *
28
+ */
29
+ Then(/^(I |we )*should( not)* see "([^"]*)?"$/, async function (pronounCase, notCase, expectedText) {
30
+ 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.`);
33
+ } else {
34
+ await this.page.locator('body').filter({ hasText: expectedText }).waitFor({ timeout: 5000 });
35
+ }
36
+ });
37
+
38
+ /**
39
+ * Assert that page contains or does not contain text matching a regex pattern.
40
+ *
41
+ * Example #1: Then I should see text matching "^T\w+"
42
+ * Example #2: Then I should not see text matching "^O\w+"
43
+ * Example #3: And we should see text matching "\d{4}"
44
+ *
45
+ */
46
+ Then(/^(I |we )*should( not)* see text matching "([^"]*)?"$/, async function (pronounCase, notCase, textPattern) {
47
+ 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.`);
53
+ }
54
+ });
55
+
56
+ // ---------------------------------------------------------------------------
57
+ // Table-row text
58
+ // ---------------------------------------------------------------------------
59
+
60
+ /**
61
+ * Assert text is or is not visible inside a table row identified by text.
62
+ *
63
+ * Example #1: Then I should see "Active" in the "John Smith" row
64
+ * Example #2: Then I should see "In Stock" in the "Product A" row
65
+ * Example #3: Then we should see "Processing" in the "Order #12345" row
66
+ * Example #4: And I should see "Admin" in the "john.smith@example.com" row
67
+ * Example #5: Then I should not see "Admin" in the "Jane Doe" row
68
+ * Example #6: Then I should not see "Out of Stock" in the "Product A" row
69
+ * Example #7: And I should not see "Inactive" in the "john.smith@example.com" row
70
+ *
71
+ */
72
+ Then(/^(I |we )*should( not)* see "([^"]*)?" in( the)* "([^"]*)?" row$/, async function (pronounCase, notCase, expectedText, theCase, rowIdentifier) {
73
+ const found = await this.page.evaluate(({ id, text }) => {
74
+ const rows = Array.from(document.querySelectorAll('tr'));
75
+ return rows.filter(r => r.textContent.includes(id)).some(r => r.textContent.includes(text));
76
+ }, { 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.`);
81
+ }
82
+ });
83
+
84
+ // ---------------------------------------------------------------------------
85
+ // Element existence + content
86
+ // ---------------------------------------------------------------------------
87
+
88
+ /**
89
+ * Assert that an element with a given label exists (or does not) on the page.
90
+ *
91
+ * Example #1: Then I should see a "Username" element
92
+ * Example #2: Then I should not see a "Username" element
93
+ * Example #3: And we should see an "Email" element
94
+ *
95
+ */
96
+ Then(/^(I |we )*should( not)* see (a|an) "([^"]*)?" element$/, async function (pronounCase, notCase, aAnCase, element) {
97
+ if (notCase) {
98
+ const text = await this.page.locator('body').textContent() || '';
99
+ assert.ok(!text.includes(element), `Page should NOT contain element text "${element}" but it does.`);
100
+ } else {
101
+ const loc = this.page.getByText(element, { exact: true }).first();
102
+ const forAttr = await loc.getAttribute('for').catch(() => null);
103
+ if (forAttr) {
104
+ await this.page.locator('#' + forAttr).waitFor({ state: 'visible', timeout: 3000 });
105
+ } else {
106
+ await loc.waitFor({ state: 'visible', timeout: 3000 });
107
+ }
108
+ }
109
+ });
110
+
111
+ /**
112
+ * Assert that an element, identified by attribute, exists (or does not) on the page.
113
+ *
114
+ * Example #1: Then I should see a "uname" element by its "id" attr
115
+ * Example #2: Then I should see a "pwordcss" element by attr
116
+ * Example #3: Then I should not see an "emailId" element by its "id" attr
117
+ * Example #4: And I should not see a "countryCss" element by attr
118
+ *
119
+ */
120
+ Then(/^(I |we )*should( not)* see (a|an) "([^"]*)?" element by( its)*(?: "([^"]*)?")* (attribute|attr)$/, async function (pronounCase, notCase, aAnCase, attrValue, itsCase, attr, attrWord) {
121
+ const loc = this.page.locator(buildSelector(attrValue, attr));
122
+ if (notCase) {
123
+ assert.strictEqual(await loc.count(), 0, `Element should NOT be present but it is.`);
124
+ } else {
125
+ await loc.first().waitFor({ state: 'visible', timeout: 3000 });
126
+ }
127
+ });
128
+
129
+ /**
130
+ * Assert that an element (found by its label) contains or does not contain text.
131
+ *
132
+ * Example #1: Then I should see "John Smith" in the "Username" element
133
+ * Example #2: Then I should not see "Joe Smith" in the "Username" element
134
+ * Example #3: And we should see "1234" in the "Password" element
135
+ *
136
+ */
137
+ Then(/^(I |we )*should( not)* see "([^"]*)?" in( the)* "([^"]*)?" element$/, async function (pronounCase, notCase, expectedText, theCase, element) {
138
+ const forAttr = await this.page.getByText(element, { exact: true }).getAttribute('for').catch(() => null);
139
+ const loc = this.page.locator(forAttr ? '#' + forAttr : element).first();
140
+ await loc.waitFor({ timeout: 5000 });
141
+ const content = await getLocatorText(loc);
142
+ if (notCase) {
143
+ assert.ok(!content.includes(expectedText), `Element should NOT contain "${expectedText}" but it does.`);
144
+ } else {
145
+ assert.ok(content.includes(expectedText), `Element should contain "${expectedText}" but it does not.`);
146
+ }
147
+ });
148
+
149
+ /**
150
+ * Assert that an element (found by its attribute) contains or does not contain text.
151
+ *
152
+ * Example #1: Then I should see "John Smith" in the "uname" element by its "id" attr
153
+ * Example #2: Then I should see "1234" in the "pwordcss" element by attr
154
+ * Example #3: Then I should not see "John Smith" in the "uname" element by its "id" attr
155
+ * Example #4: Then I should not see "1234" in the "pwordcss" element by attr
156
+ *
157
+ */
158
+ Then(/^(I |we )*should( not)* see "([^"]*)?" in( the)* "([^"]*)?" element by( its)*(?: "([^"]*)?")* (attribute|attr)$/, async function (pronounCase, notCase, expectedText, theCase, attrValue, itsCase, attr, attrWord) {
159
+ const loc = this.page.locator(buildSelector(attrValue, attr)).first();
160
+ await loc.waitFor({ timeout: 10000 });
161
+ const content = await getLocatorText(loc);
162
+ if (notCase) {
163
+ assert.ok(!content.includes(expectedText), `Element should NOT contain "${expectedText}" but it does.`);
164
+ } else {
165
+ assert.ok(content.includes(expectedText), `Element should contain "${expectedText}" but it does not.`);
166
+ }
167
+ });
168
+
169
+ /**
170
+ * Assert that an element's text content does or does not match a regex.
171
+ *
172
+ * Example #1: Then I should see text matching "\d{4}" in the "#year" element
173
+ * Example #2: Then I should see text matching "\$\d+\.\d{2}" in the "#price" element
174
+ * Example #3: Then I should not see text matching "Error" in the "#status" element
175
+ * Example #4: Then we should see text matching "^[A-Z][a-z]+ [A-Z][a-z]+$" in the "#full-name" element
176
+ * Example #5: Then I should see text matching "(0?[1-9]|[12][0-9]|3[01])[\/\-](0?[1-9]|1[012])[\/\-]\d{4}" in the "#date" element
177
+ *
178
+ */
179
+ Then(/^(I |we )*should( not)* see text matching "([^"]*)?" in( the)* "([^"]*)?" element$/, async function (pronounCase, notCase, textPattern, theCase, element) {
180
+ const loc = this.page.locator(element).first();
181
+ await loc.waitFor({ timeout: 5000 });
182
+ const text = await getLocatorText(loc);
183
+ const regex = new RegExp(textPattern);
184
+ if (notCase) {
185
+ assert.ok(!regex.test(text), `Element "${element}" text should NOT match "${textPattern}" but it does.`);
186
+ } else {
187
+ assert.ok(regex.test(text), `Element "${element}" text should match "${textPattern}" but it does not.`);
188
+ }
189
+ });
190
+
191
+ /**
192
+ * Assert that an element has or does not have a specific CSS property.
193
+ *
194
+ * Example #1: Then the "body" element should contain "color:white;"
195
+ * Example #2: Then the "body" element should not contain "color:white;"
196
+ * Example #3: Then the "#uname" element should not contain "border:solid 5px red;"
197
+ * Example #4: Then the "pword" element should not contain "font-size: 26px;"
198
+ *
199
+ */
200
+ Then(/^(the )*"([^"]*)?" element should( not)* contain "([^"]*)?"$/, async function (theCase, selectorRaw, notCase, elementCss) {
201
+ const cssClean = elementCss.replace(/;$/, '');
202
+ const colonIdx = cssClean.indexOf(':');
203
+ const cssProperty = cssClean.substring(0, colonIdx).trim();
204
+ const expectedValue = cssClean.substring(colonIdx + 1).trim();
205
+
206
+ const loc = this.page.locator(buildSelector(selectorRaw)).first();
207
+ await loc.waitFor({ timeout: 10000 });
208
+ const matches = await loc.evaluate((el, { prop, expectedVal }) => {
209
+ function colorToRgb(color) {
210
+ const canvas = document.createElement('canvas');
211
+ canvas.width = canvas.height = 1;
212
+ const ctx = canvas.getContext('2d');
213
+ ctx.fillStyle = 'rgb(1, 2, 3)';
214
+ ctx.fillStyle = color.trim();
215
+ ctx.fillRect(0, 0, 1, 1);
216
+ const d = ctx.getImageData(0, 0, 1, 1).data;
217
+ return 'rgb(' + d[0] + ', ' + d[1] + ', ' + d[2] + ')';
218
+ }
219
+ function isValidColor(value) { return colorToRgb(value) !== 'rgb(1, 2, 3)'; }
220
+ function normalizeColorTokens(value) {
221
+ return value.replace(/rgb\([^)]+\)|rgba\([^)]+\)|#[0-9a-fA-F]+|\b[a-zA-Z]+\b/g,
222
+ (token) => isValidColor(token) ? colorToRgb(token) : token);
223
+ }
224
+ function tokenize(value) {
225
+ const tokens = [], regex = /rgb\([^)]+\)|rgba\([^)]+\)|[^\s]+/g;
226
+ let m;
227
+ while ((m = regex.exec(value)) !== null) tokens.push(m[0]);
228
+ return tokens;
229
+ }
230
+ const computed = window.getComputedStyle(el).getPropertyValue(prop).trim();
231
+ return tokenize(normalizeColorTokens(expectedVal.toLowerCase()))
232
+ .every(token => normalizeColorTokens(computed.toLowerCase()).includes(token));
233
+ }, { prop: cssProperty, expectedVal: expectedValue });
234
+
235
+ if (notCase) {
236
+ assert.ok(!matches, `Element should NOT have CSS "${cssProperty}: ${expectedValue}" but it does.`);
237
+ } else {
238
+ assert.ok(matches, `Element should have CSS "${cssProperty}: ${expectedValue}".`);
239
+ }
240
+ });
241
+
242
+ /**
243
+ * Assert the exact number of elements matching a CSS selector.
244
+ *
245
+ * Example #1: Then I should see 3 "li" elements
246
+ * Example #2: Then I should see 1 "h1" element
247
+ * Example #3: Then we should see 5 ".card" elements
248
+ * Example #4: Then I should see 0 ".error" elements
249
+ * Example #5: And I should see 10 "table tr" elements
250
+ * Example #6: Then I should see 2 "nav a" elements
251
+ * Example #7: Then we should see 4 "ul li" elements
252
+ * Example #8: Then I should see 1 "form" element
253
+ * Example #9: And should see 6 ".product" elements
254
+ * Example #10: Then I should see 8 "[data-testid='row']" elements
255
+ */
256
+ Then(/^(I |we )*should see (\d+) "([^"]*)" elements?$/, async function (pronounCase, num, selector) {
257
+ const expected = parseInt(num, 10);
258
+ const actual = await this.page.locator(selector).count();
259
+ if (actual !== expected) {
260
+ throw new Error(`Expected ${expected} "${selector}" element(s), got ${actual}.`);
261
+ }
262
+ });
263
+
264
+ // ---------------------------------------------------------------------------
265
+ // Link href
266
+ // ---------------------------------------------------------------------------
267
+
268
+ /**
269
+ * Assert that a link (located by its visible text) contains the given URL.
270
+ *
271
+ * Example #1: Then the "Login" link should contain "/log-in"
272
+ * Example #2: And the "About Us" link should contain "/about"
273
+ * Example #3: Then "Home" link should contain "/"
274
+ *
275
+ */
276
+ Then(/^(the )*"([^"]*)?" link should contain "([^"]*)?"$/, async function (theCase, element, url) {
277
+ const loc = this.page.getByText(element, { exact: true }).first();
278
+ await loc.waitFor({ timeout: 5000 });
279
+ const href = await loc.evaluate(el => el.href || el.getAttribute('href') || '');
280
+ assert.ok(href.includes(url), `Expected link "${element}" href to contain "${url}" but got "${href}"`);
281
+ });
282
+
283
+ /**
284
+ * Assert that a link located by its attribute contains the given URL.
285
+ *
286
+ * Example #1: Then the "#about-us-id" link should contain "about" by attr
287
+ * Example #2: And the "aboutUs" link should contain "about" by its "class" attribute
288
+ * Example #3: And the ".contactUs" link should contain "/contact-" by attr
289
+ *
290
+ */
291
+ Then(/^(the )*"([^"]*)?" link should contain "([^"]*)?" by( its)*(?: "([^"]*)?")* (attribute|attr)$/, async function (theCase, attrValue, url, itsCase, attr, attrWord) {
292
+ const loc = this.page.locator(buildSelector(attrValue, attr)).first();
293
+ await loc.waitFor({ timeout: 5000 });
294
+ const href = await loc.evaluate(el => el.href || el.getAttribute('href') || '');
295
+ assert.ok(href.includes(url), `Expected element href to contain "${url}" but got "${href}"`);
296
+ });
297
+
298
+ // ---------------------------------------------------------------------------
299
+ // Response body / status
300
+ // ---------------------------------------------------------------------------
301
+
302
+ /**
303
+ * Assert that the rendered HTML response contains or does not contain text.
304
+ *
305
+ * Reads the entire `<html>` text — useful for checking text that lives in
306
+ * `<head>` (meta descriptions, JSON-LD), `<noscript>`, or hidden regions.
307
+ *
308
+ * Example #1: Then the response should contain "Welcome visitor"
309
+ * Example #2: Then the response should not contain "Access denied"
310
+ * Example #3: And the response should contain "<title>Home</title>"
311
+ * Example #4: Then the response should contain "<html"
312
+ * Example #5: When I am on "/about"
313
+ * Then the response should contain "Our mission"
314
+ * And the response should not contain "TODO"
315
+ *
316
+ */
317
+ Then(/^(the )*response should( not)* contain "([^"]*)?"$/, async function (theCase, notCase, expectedText) {
318
+ const text = await this.page.locator('html').textContent() || '';
319
+ if (notCase) {
320
+ assert.ok(!text.includes(expectedText), `Response should NOT contain "${expectedText}" but it does.`);
321
+ } else {
322
+ assert.ok(text.includes(expectedText), `Response should contain "${expectedText}" but it does not.`);
323
+ }
324
+ });
325
+
326
+ /**
327
+ * Assert that the current page's response status is or is not a given code.
328
+ *
329
+ * Example #1: Then the response status code should be 200
330
+ * Example #2: And the response status code should not be 404
331
+ * Example #3: Then the response status code should be 301
332
+ *
333
+ */
334
+ Then(/^(the )*response status code should( not)* be (\d+)$/, async function (theCase, notCase, expectedStatusCode) {
335
+ const currentURL = this.page.url();
336
+ try {
337
+ const response = await axios.get(currentURL);
338
+ const status = response.status;
339
+ if (notCase) {
340
+ assert.notStrictEqual(status, parseInt(expectedStatusCode), `Status code should NOT be ${expectedStatusCode}`);
341
+ } else {
342
+ assert.strictEqual(status, parseInt(expectedStatusCode), `Expected status ${expectedStatusCode} but got ${status}`);
343
+ }
344
+ } catch (error) {
345
+ const status = error.response ? error.response.status : null;
346
+ if (notCase) {
347
+ if (status !== null) assert.notStrictEqual(status, parseInt(expectedStatusCode));
348
+ } else {
349
+ assert.strictEqual(status, parseInt(expectedStatusCode), `Expected status ${expectedStatusCode} but got ${status}`);
350
+ }
351
+ }
352
+ });