webship-js 2.0.1 → 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 (194) hide show
  1. package/AGENTS.md +109 -0
  2. package/CLAUDE.md +317 -0
  3. package/bin/generate-reports.js +363 -0
  4. package/bin/init-webship.js +343 -0
  5. package/bin/postinstall.js +8 -74
  6. package/cucumber.js +66 -2
  7. package/docs/00-quick-start.md +102 -0
  8. package/docs/01-getting-started.md +102 -0
  9. package/docs/02-bbr-smart-waits.md +77 -0
  10. package/docs/03-selector-registry.md +95 -0
  11. package/docs/04-step-reference.md +728 -0
  12. package/docs/05-web-first-assertions.md +91 -0
  13. package/docs/06-network-and-dialogs.md +83 -0
  14. package/docs/07-auth-state.md +75 -0
  15. package/docs/08-clock-mocking.md +59 -0
  16. package/docs/09-api-testing.md +114 -0
  17. package/docs/10-accessibility.md +167 -0
  18. package/docs/11-debugging.md +129 -0
  19. package/docs/12-ai-agent-guide.md +338 -0
  20. package/docs/13-faq.md +236 -0
  21. package/docs/14-recipes-cookbook.md +255 -0
  22. package/docs/15-tag-conventions.md +76 -0
  23. package/docs/advanced-screenshots/then-i-save-fullscreen-screenshot.md +36 -0
  24. package/docs/advanced-screenshots/then-i-save-width-x-height-screenshot.md +34 -0
  25. package/docs/advanced-screenshots/when-i-save-screenshot-name-filename.md +45 -0
  26. package/docs/advanced-screenshots.md +52 -0
  27. package/docs/advanced-selectors.md +18 -0
  28. package/docs/api-step-definitions.md +45 -0
  29. package/docs/diffy-step-definitions/then-compare-diffy-env1-env2.md +30 -0
  30. package/docs/diffy-step-definitions/then-create-diffy-comparison-name-value.md +21 -0
  31. package/docs/diffy-step-definitions/then-create-diffy-comparison.md +25 -0
  32. package/docs/diffy-step-definitions/then-create-diffy-screenshot-environment-name.md +35 -0
  33. package/docs/diffy-step-definitions/then-i-take-screenshot.md +21 -0
  34. package/docs/diffy-step-definitions/then-i-take-screenshots-all-breakpoints.md +27 -0
  35. package/docs/diffy-step-definitions/then-send-screenshots-diffy-name-value.md +27 -0
  36. package/docs/diffy-step-definitions/then-upload-folder-url-diffy-snapshotname.md +28 -0
  37. package/docs/diffy-step-definitions/then-wait-diffy-comparison-complete.md +21 -0
  38. package/docs/diffy-step-definitions/when-i-resize-window-number.md +29 -0
  39. package/docs/diffy-step-definitions.md +21 -0
  40. package/docs/global-settings.md +244 -0
  41. package/docs/index.md +104 -0
  42. package/docs/install-webship-js/ddev-webship-js.md +52 -0
  43. package/docs/install-webship-js.md +35 -0
  44. package/docs/overview.md +41 -0
  45. package/docs/step-definitions/given-i-am-anonymous-user.md +67 -0
  46. package/docs/step-definitions/given-i-am-homepage.md +68 -0
  47. package/docs/step-definitions/given-i-am-specific-page.md +72 -0
  48. package/docs/step-definitions/then-i-should-be.md +56 -0
  49. package/docs/step-definitions/then-i-should-see.md +62 -0
  50. package/docs/step-definitions/then-item-checkbox.md +54 -0
  51. package/docs/step-definitions/then-item-link-should-contain-url.md +84 -0
  52. package/docs/step-definitions/then-item-should-contain.md +67 -0
  53. package/docs/step-definitions/then-radio-button-value-should-be-selected.md +68 -0
  54. package/docs/step-definitions/then-response-status-code-should-be-number.md +69 -0
  55. package/docs/step-definitions/then-value-radio-button-selected.md +62 -0
  56. package/docs/step-definitions/when-i-attach-file-file-name-element.md +71 -0
  57. package/docs/step-definitions/when-i-check-checkbox.md +60 -0
  58. package/docs/step-definitions/when-i-click-link.md +51 -0
  59. package/docs/step-definitions/when-i-click-operation-text-row.md +71 -0
  60. package/docs/step-definitions/when-i-fill.md +59 -0
  61. package/docs/step-definitions/when-i-go-homepage.md +60 -0
  62. package/docs/step-definitions/when-i-go-specific-page.md +67 -0
  63. package/docs/step-definitions/when-i-move-backward-one-page.md +49 -0
  64. package/docs/step-definitions/when-i-move-forward-one-page.md +58 -0
  65. package/docs/step-definitions/when-i-press-button.md +58 -0
  66. package/docs/step-definitions/when-i-reload-page.md +51 -0
  67. package/docs/step-definitions/when-i-scroll.md +73 -0
  68. package/docs/step-definitions/when-i-select-option-select-list.md +53 -0
  69. package/docs/step-definitions/when-i-select-radio-button-value.md +62 -0
  70. package/docs/step-definitions/when-i-uncheck-checkbox.md +57 -0
  71. package/docs/step-definitions/when-i-wait-ajax-finish.md +64 -0
  72. package/docs/step-definitions/when-i-wait.md +62 -0
  73. package/docs/step-definitions.md +50 -0
  74. package/examples/a11y.html +31 -0
  75. package/examples/cookies.html +10 -0
  76. package/examples/date.html +12 -0
  77. package/examples/diffy/baseline.html +54 -0
  78. package/examples/diffy/changed.html +63 -0
  79. package/examples/diffy/index.html +52 -0
  80. package/examples/element.html +11 -0
  81. package/examples/field.html +24 -0
  82. package/examples/index.html +6 -0
  83. package/examples/keyboard.html +11 -0
  84. package/examples/links.html +9 -0
  85. package/examples/modal.html +14 -0
  86. package/examples/path.html +3 -0
  87. package/examples/table.html +13 -0
  88. package/examples/test--when--i-additionally-select.html +27 -0
  89. package/package.json +19 -6
  90. package/playwright.config.ts +3 -2
  91. package/tests/features/a11y.feature +39 -0
  92. package/tests/features/cookie.feature +13 -0
  93. package/tests/features/date.feature +11 -0
  94. package/tests/features/diffy/test--diffy-01-example-demo.feature +22 -0
  95. package/tests/features/diffy/test--diffy-02-all-steps.feature +52 -0
  96. package/tests/features/diffy/test--diffy-03-real-api.feature +21 -0
  97. package/tests/features/element.feature +16 -0
  98. package/tests/features/field.feature +25 -0
  99. package/tests/features/keyboard.feature +10 -0
  100. package/tests/features/link.feature +11 -0
  101. package/tests/features/modal-advanced-example.feature +1 -1
  102. package/tests/features/modal.feature +11 -0
  103. package/tests/features/path.feature +16 -0
  104. package/tests/features/response.feature +8 -0
  105. package/tests/features/responsive.feature +10 -0
  106. package/tests/features/table.feature +18 -0
  107. package/tests/features/test--then--i-save-screenshot.feature +33 -0
  108. package/tests/features/test--then--i-see-locator.feature +320 -0
  109. package/tests/features/test--then--i-should-see-n-elements.feature +24 -0
  110. package/tests/features/test--then--print-current-url-and-response.feature +21 -0
  111. package/tests/features/test--when--i-additionally-select.feature +30 -0
  112. package/tests/features/test--when--i-follow.feature +22 -0
  113. package/tests/features/wait.feature +7 -0
  114. package/tests/features/yaml.feature +102 -0
  115. package/tests/reports/README.md +55 -0
  116. package/tests/selectors/_canonical-keys.json +113 -0
  117. package/tests/selectors/back-end-selectors.json +19 -0
  118. package/tests/selectors/cms-contentful-admin.json +35 -0
  119. package/tests/selectors/cms-craft-admin.json +39 -0
  120. package/tests/selectors/cms-drupal-cms-gin.json +56 -0
  121. package/tests/selectors/cms-drupal-core-claro.json +50 -0
  122. package/tests/selectors/cms-generic-admin.json +34 -0
  123. package/tests/selectors/cms-ghost-admin.json +34 -0
  124. package/tests/selectors/cms-joomla-admin.json +41 -0
  125. package/tests/selectors/cms-magento2-admin.json +32 -0
  126. package/tests/selectors/cms-prestashop-admin.json +38 -0
  127. package/tests/selectors/cms-shopify-admin.json +25 -0
  128. package/tests/selectors/cms-strapi-admin.json +42 -0
  129. package/tests/selectors/cms-typo3-admin.json +41 -0
  130. package/tests/selectors/cms-woocommerce-front.json +50 -0
  131. package/tests/selectors/cms-wordpress-admin.json +31 -0
  132. package/tests/selectors/framework-ant-design.json +80 -0
  133. package/tests/selectors/framework-bootstrap.json +86 -0
  134. package/tests/selectors/framework-bulma.json +74 -0
  135. package/tests/selectors/framework-chakra.json +58 -0
  136. package/tests/selectors/framework-foundation.json +51 -0
  137. package/tests/selectors/framework-material-ui.json +72 -0
  138. package/tests/selectors/framework-shadcn.json +51 -0
  139. package/tests/selectors/framework-tailwind.json +40 -0
  140. package/tests/selectors/framework-vuetify.json +61 -0
  141. package/tests/selectors/front-end-selectors.json +16 -0
  142. package/tests/selectors/homepage-selectors.json +13 -0
  143. package/tests/step-definitions/a11y.steps.js +798 -0
  144. package/tests/step-definitions/action.steps.js +167 -0
  145. package/tests/step-definitions/{webship-api.js → api.steps.js} +254 -44
  146. package/tests/step-definitions/assertion.steps.js +352 -0
  147. package/tests/step-definitions/auth.steps.js +124 -0
  148. package/tests/step-definitions/clock.steps.js +128 -0
  149. package/tests/step-definitions/cookie.steps.js +216 -0
  150. package/tests/step-definitions/debug.steps.js +31 -0
  151. package/tests/step-definitions/dialog.steps.js +193 -0
  152. package/tests/step-definitions/element.steps.js +314 -0
  153. package/tests/step-definitions/field.steps.js +653 -0
  154. package/tests/step-definitions/file-download.steps.js +193 -0
  155. package/tests/step-definitions/form.steps.js +333 -0
  156. package/tests/step-definitions/iframe.steps.js +178 -0
  157. package/tests/step-definitions/input.steps.js +163 -0
  158. package/tests/step-definitions/javascript.steps.js +71 -0
  159. package/tests/step-definitions/keyboard.steps.js +78 -0
  160. package/tests/step-definitions/link.steps.js +142 -0
  161. package/tests/step-definitions/metatag.steps.js +91 -0
  162. package/tests/step-definitions/modal.steps.js +219 -0
  163. package/tests/step-definitions/navigation.steps.js +218 -0
  164. package/tests/step-definitions/network.steps.js +238 -0
  165. package/tests/step-definitions/path.steps.js +141 -0
  166. package/tests/step-definitions/response.steps.js +98 -0
  167. package/tests/step-definitions/responsive.steps.js +123 -0
  168. package/tests/step-definitions/rest.steps.js +111 -0
  169. package/tests/step-definitions/screenshot.steps.js +423 -0
  170. package/tests/step-definitions/scroll.steps.js +189 -0
  171. package/tests/step-definitions/selectors.steps.js +996 -0
  172. package/tests/step-definitions/storage.steps.js +194 -0
  173. package/tests/step-definitions/table.steps.js +181 -0
  174. package/tests/step-definitions/wait.steps.js +400 -0
  175. package/tests/step-definitions/web-first.steps.js +296 -0
  176. package/tests/step-definitions/webship.js +567 -923
  177. package/tests/step-definitions/xml.steps.js +409 -0
  178. package/tests/step-definitions/yaml.steps.js +911 -0
  179. package/tests/step-definitions-diffy/README.md +329 -0
  180. package/tests/step-definitions-diffy/mock-diffy-api/server.js +84 -0
  181. package/tests/step-definitions-diffy/webship-diffy-mock.js +31 -0
  182. package/tests/step-definitions-diffy/webship-diffy.js +459 -0
  183. package/tsconfig.json +19 -3
  184. package/generate-reports.js +0 -22
  185. package/required/cucumber.js +0 -37
  186. package/required/generate-reports.js +0 -22
  187. package/required/package.json +0 -18
  188. package/required/playwright.config.ts +0 -37
  189. package/required/tests/features/README.md +0 -1
  190. package/required/tests/features/check-homepage.feature +0 -8
  191. package/required/tests/reports/README.md +0 -1
  192. package/required/tests/step-definitions/README.md +0 -1
  193. package/required/tests/step-definitions/custom.js +0 -4
  194. package/required/tsconfig.json +0 -12
@@ -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
+ });
@@ -46,10 +46,13 @@ function getNestedProperty(obj, path) {
46
46
  }
47
47
 
48
48
  /**
49
- * Adds Basic Authentication header to next request.
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
+ * Example #3: Given I am authenticating as "api-user" with "pass!word" password
54
+ * Example #4: Given we are authenticating as "reader" with "readonly" password
55
+ *
53
56
  */
54
57
  Given(/^(?:I am|we are) authenticating as "([^"]*)" with "([^"]*)" password$/, function (username, password) {
55
58
  delete apiHeaders['Authorization'];
@@ -58,22 +61,33 @@ Given(/^(?:I am|we are) authenticating as "([^"]*)" with "([^"]*)" password$/, f
58
61
  });
59
62
 
60
63
  /**
61
- * Sets a HTTP Header with value.
64
+ * Sets a single HTTP request header.
62
65
  *
63
66
  * Example #1: Given I set header "Content-Type" with value "application/json"
64
67
  * Example #2: Given I set header "Authorization" with value "Bearer token123"
65
68
  * Example #3: Given I set header "Accept" with value "application/xml"
69
+ * Example #4: Given I set header "Accept" with value "application/json"
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 "test-runner"
72
+ * Example #7: Given we set header "Accept-Language" with value "en-US"
73
+ * Example #8: Given I set header "If-None-Match" with value "etag-xyz"
74
+ *
66
75
  */
67
76
  Given(/^(?:I |we )?set header "([^"]*)" with value "([^"]*)"$/, function (name, value) {
68
77
  apiHeaders[name] = replacePlaceHolder(value);
69
78
  });
70
79
 
71
80
  /**
72
- * Set the base URL for API calls (alternative syntax).
81
+ * Set the base URL for API calls. Accepts full URLs or paths relative to LAUNCH_URL.
73
82
  *
74
83
  * Example #1: Given the API base URL is "https://jsonplaceholder.typicode.com"
75
84
  * Example #2: Given I set the API base URL to "https://api.example.com/v1"
76
85
  * Example #3: Given the base URL is "http://localhost:3000/api"
86
+ * Example #4: Given the API base URL is "https://un.org/api"
87
+ * Example #5: Given I set the API base URL to "/api/v2"
88
+ * Example #6: Given the base URL is "/webship.co/api"
89
+ * Example #7: Given the API base URL is "http://127.0.0.1:8080"
90
+ *
77
91
  */
78
92
  Given(/^(?:the API base URL is|I set the API base URL to|the base URL is) "([^"]*)"$/, function (url) {
79
93
  // Check if the input is a full URL (contains protocol)
@@ -88,11 +102,17 @@ Given(/^(?:the API base URL is|I set the API base URL to|the base URL is) "([^"]
88
102
  });
89
103
 
90
104
  /**
91
- * Set request headers for API calls (alternative syntax).
105
+ * Set a request header. Alternative syntax.
92
106
  *
93
107
  * Example #1: Given I set the header "Content-Type" to "application/json"
94
108
  * Example #2: Given I set the header "Authorization" to "Bearer token123"
95
109
  * Example #3: Given the header "Accept" is "application/json"
110
+ * Example #4: Given we set the header "X-Api-Key" to "abcd-1234"
111
+ * Example #5: Given I set the header "If-Match" to "etag-123"
112
+ * Example #6: Given the header "User-Agent" is "test-runner"
113
+ * Example #7: Given we set the header "Accept-Language" to "en-US"
114
+ * Example #8: Given I set the header "Cache-Control" to "no-cache"
115
+ *
96
116
  */
97
117
  Given(/^(?:I set the header|we set the header|the header) "([^"]*)" (?:to|is) "([^"]*)"$/, function (headerName, headerValue) {
98
118
  apiHeaders[headerName] = replacePlaceHolder(headerValue);
@@ -101,10 +121,25 @@ Given(/^(?:I set the header|we set the header|the header) "([^"]*)" (?:to|is) "(
101
121
  /**
102
122
  * Set multiple headers using a table.
103
123
  *
104
- * Example: Given I set the following headers:
105
- * | Content-Type | application/json |
106
- * | Authorization | Bearer token123 |
107
- * | Accept | application/json |
124
+ * Example #1: Given I set the following headers:
125
+ * | Content-Type | application/json |
126
+ * | Authorization | Bearer token123 |
127
+ * | Accept | application/json |
128
+ *
129
+ * Example #2: Given we set the following headers:
130
+ * | Content-Type | application/json |
131
+ * | X-Api-Key | abcd-1234 |
132
+ * | Accept-Language | en-US |
133
+ *
134
+ * Example #3: Given I set the following headers:
135
+ * | User-Agent | test-runner |
136
+ * | Cache-Control | no-cache |
137
+ * | If-None-Match | etag-xyz |
138
+ *
139
+ * Example #4: Given we set the following headers:
140
+ * | Authorization | Bearer {{token}} |
141
+ * | Accept | application/json |
142
+ * | X-Request-ID | req-001 |
108
143
  */
109
144
  Given(/^(?:I|we) set the following headers:$/, function (table) {
110
145
  table.rows().forEach(row => {
@@ -117,6 +152,11 @@ Given(/^(?:I|we) set the following headers:$/, function (table) {
117
152
  *
118
153
  * Example #1: Given I set the request body to '{"name": "John", "email": "john@example.com"}'
119
154
  * Example #2: Given the request body is '{"title": "Test Post", "body": "This is a test"}'
155
+ * Example #3: Given we set the request body to '{"org": "Webship.co", "active": true}'
156
+ * Example #4: Given I set the request body to '{"id": 1, "tags": ["qa","api"]}'
157
+ * Example #5: Given the request body is '{"username": "admin", "password": "secret"}'
158
+ * Example #6: Given we set the request body to '{"email": "hello@un.org"}'
159
+ * Example #7: Given I set the request body to '{"status": "published"}'
120
160
  */
121
161
  Given(/^(?:I set the request body to|we set the request body to|the request body is) '([^']*)'$/, function (jsonData) {
122
162
  try {
@@ -130,10 +170,25 @@ Given(/^(?:I set the request body to|we set the request body to|the request body
130
170
  /**
131
171
  * Set request body using a table.
132
172
  *
133
- * Example: Given I set the request body with:
134
- * | name | John Doe |
135
- * | email | john@example.com |
136
- * | age | 30 |
173
+ * Example #1: Given I set the request body with:
174
+ * | name | John Doe |
175
+ * | email | john@example.com |
176
+ * | age | 30 |
177
+ *
178
+ * Example #2: Given we set the request body with:
179
+ * | org | Webship.co |
180
+ * | country | UN |
181
+ * | active | true |
182
+ *
183
+ * Example #3: Given I set the request body with:
184
+ * | title | Hello World |
185
+ * | body | First post |
186
+ * | userId | 1 |
187
+ *
188
+ * Example #4: Given we set the request body with:
189
+ * | status | published |
190
+ * | priority | 5 |
191
+ * | featured | false |
137
192
  */
138
193
  Given(/^(?:I|we) set the request body with:$/, function (table) {
139
194
  apiRequestData = {};
@@ -156,6 +211,12 @@ Given(/^(?:I|we) set the request body with:$/, function (table) {
156
211
  * Example #2: When we send a POST request to "/posts"
157
212
  * Example #3: When I send a PUT request to "/users/1"
158
213
  * Example #4: When we send a DELETE request to "/posts/1"
214
+ * Example #5: When I send a GET request to "/posts?userId=1"
215
+ * Example #6: When we send a PATCH request to "/users/42"
216
+ * Example #7: When I send a GET request to "/health"
217
+ * Example #8: When we send a HEAD request to "/users"
218
+ * Example #9: When I send a OPTIONS request to "/api"
219
+ * Example #10: When we send a GET request to "/posts/{{postId}}"
159
220
  */
160
221
  When(/^(?:I |we )?send a ([A-Z]+) request to "([^"]+)"$/, async function (method, endpoint) {
161
222
  const url = baseURL + '/' + prepareUrl(endpoint);
@@ -178,11 +239,24 @@ When(/^(?:I |we )?send a ([A-Z]+) request to "([^"]+)"$/, async function (method
178
239
  /**
179
240
  * Sends HTTP request to specific URL with field values from Table.
180
241
  *
181
- * Example: When I send a POST request to "/users" with values:
182
- * When we send a POST request to "/users" with values:
183
- * | name | John Doe |
184
- * | email | john@example.com |
185
- * | age | 30 |
242
+ * Example #1: When I send a POST request to "/users" with values:
243
+ * | name | John Doe |
244
+ * | email | john@example.com |
245
+ * | age | 30 |
246
+ *
247
+ * Example #2: When we send a POST request to "/users" with values:
248
+ * | name | Alice |
249
+ * | email | alice@un.org |
250
+ * | role | editor |
251
+ *
252
+ * Example #3: When I send a PUT request to "/users/1" with values:
253
+ * | name | Updated Name |
254
+ * | active | true |
255
+ *
256
+ * Example #4: When we send a POST request to "/posts" with values:
257
+ * | title | Welcome |
258
+ * | body | Hello Webship.co|
259
+ * | userId | 1 |
186
260
  */
187
261
  When(/^(?:I |we )?send a ([A-Z]+) request to "([^"]+)" with values:$/, async function (method, endpoint, table) {
188
262
  const url = baseURL + '/' + prepareUrl(endpoint);
@@ -211,14 +285,38 @@ When(/^(?:I |we )?send a ([A-Z]+) request to "([^"]+)" with values:$/, async fun
211
285
  /**
212
286
  * Sends HTTP request to specific URL with raw body from PyString.
213
287
  *
214
- * Example: When I send a POST request to "/users" with body:
215
- * When we send a POST request to "/users" with body:
216
- * """
217
- * {
218
- * "name": "John Doe",
219
- * "email": "john@example.com"
220
- * }
221
- * """
288
+ * Example #1: When I send a POST request to "/users" with body:
289
+ * """
290
+ * {
291
+ * "name": "John Doe",
292
+ * "email": "john@example.com"
293
+ * }
294
+ * """
295
+ *
296
+ * Example #2: When we send a POST request to "/posts" with body:
297
+ * """
298
+ * {
299
+ * "title": "Hello",
300
+ * "body": "World",
301
+ * "userId": 1
302
+ * }
303
+ * """
304
+ *
305
+ * Example #3: When I send a PUT request to "/users/1" with body:
306
+ * """
307
+ * {
308
+ * "name": "Updated",
309
+ * "org": "Webship.co"
310
+ * }
311
+ * """
312
+ *
313
+ * Example #4: When we send a POST request to "/contacts" with body:
314
+ * """
315
+ * {
316
+ * "email": "info@un.org",
317
+ * "subscribe": true
318
+ * }
319
+ * """
222
320
  */
223
321
  When(/^(?:I |we )?send a ([A-Z]+) request to "([^"]+)" with body:$/, async function (method, endpoint, docString) {
224
322
  const url = baseURL + '/' + prepareUrl(endpoint);
@@ -260,13 +358,31 @@ When(/^(?:I |we )?send a ([A-Z]+) request to "([^"]+)" with body:$/, async funct
260
358
  /**
261
359
  * Sends HTTP request to specific URL with form data.
262
360
  *
263
- * Example: When I send a POST request to "/login" with form data:
264
- * When we send a POST request to "/login" with form data:
265
- * """
266
- * username=admin
267
- * password=secret
268
- * remember=true
269
- * """
361
+ * Example #1: When I send a POST request to "/login" with form data:
362
+ * """
363
+ * username=admin
364
+ * password=secret
365
+ * remember=true
366
+ * """
367
+ *
368
+ * Example #2: When we send a POST request to "/subscribe" with form data:
369
+ * """
370
+ * email=hello@un.org
371
+ * list=newsletter
372
+ * """
373
+ *
374
+ * Example #3: When I send a POST request to "/contact" with form data:
375
+ * """
376
+ * name=Alice
377
+ * org=Webship.co
378
+ * message=Hello
379
+ * """
380
+ *
381
+ * Example #4: When we send a PUT request to "/profile" with form data:
382
+ * """
383
+ * name=Updated
384
+ * country=UN
385
+ * """
270
386
  */
271
387
  When(/^(?:I |we )?send a ([A-Z]+) request to "([^"]+)" with form data:$/, async function (method, endpoint, docString) {
272
388
  const url = baseURL + '/' + prepareUrl(endpoint);
@@ -309,6 +425,14 @@ When(/^(?:I |we )?send a ([A-Z]+) request to "([^"]+)" with form data:$/, async
309
425
  *
310
426
  * Example #1: Then the API response code should be 200
311
427
  * Example #2: Then API response code should be 404
428
+ * Example #3: Then the API response code should be 201
429
+ * Example #4: Then API response code should be 204
430
+ * Example #5: Then the API response code should be 400
431
+ * Example #6: Then API response code should be 401
432
+ * Example #7: Then the API response code should be 403
433
+ * Example #8: Then API response code should be 500
434
+ * Example #9: Then the API response code should be 301
435
+ * Example #10: Then API response code should be 302
312
436
  */
313
437
  Then(/^(?:the )?API response code should be (\d+)$/, function (expectedCode) {
314
438
  if (!apiResponse) {
@@ -326,6 +450,12 @@ Then(/^(?:the )?API response code should be (\d+)$/, function (expectedCode) {
326
450
  *
327
451
  * Example #1: Then the API response should contain "success"
328
452
  * Example #2: Then API response should contain "John Doe"
453
+ * Example #3: Then the API response should contain "Webship.co"
454
+ * Example #4: Then API response should contain "UN"
455
+ * Example #5: Then the API response should contain "published"
456
+ * Example #6: Then API response should contain "id"
457
+ * Example #7: Then the API response should contain "email"
458
+ * Example #8: Then API response should contain "hello@un.org"
329
459
  */
330
460
  Then(/^(?:the )?API response should contain "([^"]*)"$/, function (expectedText) {
331
461
  if (!apiResponse) {
@@ -345,6 +475,12 @@ Then(/^(?:the )?API response should contain "([^"]*)"$/, function (expectedText)
345
475
  *
346
476
  * Example #1: Then the API response should not contain "error"
347
477
  * Example #2: Then API response should not contain "failed"
478
+ * Example #3: Then the API response should not contain "forbidden"
479
+ * Example #4: Then API response should not contain "unauthorized"
480
+ * Example #5: Then the API response should not contain "password"
481
+ * Example #6: Then API response should not contain "secret"
482
+ * Example #7: Then the API response should not contain "exception"
483
+ * Example #8: Then API response should not contain "stack trace"
348
484
  */
349
485
  Then(/^(?:the )?API response should not contain "([^"]*)"$/, function (unexpectedText) {
350
486
  if (!apiResponse) {
@@ -362,13 +498,36 @@ Then(/^(?:the )?API response should not contain "([^"]*)"$/, function (unexpecte
362
498
  /**
363
499
  * Checks that API response body contains JSON from PyString.
364
500
  *
365
- * Example: Then the API response should contain json:
366
- * """
367
- * {
368
- * "name": "John Doe",
369
- * "email": "john@example.com"
370
- * }
371
- * """
501
+ * Example #1: Then the API response should contain json:
502
+ * """
503
+ * {
504
+ * "name": "John Doe",
505
+ * "email": "john@example.com"
506
+ * }
507
+ * """
508
+ *
509
+ * Example #2: Then API response should contain json:
510
+ * """
511
+ * {
512
+ * "org": "Webship.co",
513
+ * "active": true
514
+ * }
515
+ * """
516
+ *
517
+ * Example #3: Then the API response should contain json:
518
+ * """
519
+ * {
520
+ * "id": 1,
521
+ * "title": "Hello"
522
+ * }
523
+ * """
524
+ *
525
+ * Example #4: Then API response should contain json:
526
+ * """
527
+ * {
528
+ * "email": "hello@un.org"
529
+ * }
530
+ * """
372
531
  */
373
532
  Then(/^(?:the )?API response should contain json:$/, function (docString) {
374
533
  if (!apiResponse) {
@@ -401,7 +560,16 @@ Then(/^(?:the )?API response should contain json:$/, function (docString) {
401
560
  });
402
561
 
403
562
  /**
404
- * Alternative syntax for JSON property verification
563
+ * Alternative syntax for JSON property verification.
564
+ *
565
+ * Example #1: Then the JSON response should have "name" equal to "John Doe"
566
+ * Example #2: Then the API response should have "id" equal to 1
567
+ * Example #3: Then the JSON property "active" should be true
568
+ * Example #4: Then the JSON response should have "org" equal to "Webship.co"
569
+ * Example #5: Then the API response should have "email" equal to "hello@un.org"
570
+ * Example #6: Then the JSON property "count" should be 42
571
+ * Example #7: Then the JSON response should have "user.role" equal to "admin"
572
+ * Example #8: Then the JSON property "published" should be false
405
573
  */
406
574
  Then(/^(?:the JSON response should have|the API response should have|the JSON property) "([^"]*)" (?:equal to|should be) (.+)$/, function (propertyPath, expectedValue) {
407
575
  if (!apiResponse) {
@@ -435,6 +603,12 @@ Then(/^(?:the JSON response should have|the API response should have|the JSON pr
435
603
  *
436
604
  * Example #1: Then the JSON response should have property "id"
437
605
  * Example #2: Then the API response should contain property "user.email"
606
+ * Example #3: Then the JSON response should have property "title"
607
+ * Example #4: Then the API response should contain property "data"
608
+ * Example #5: Then the JSON response should have property "user.org"
609
+ * Example #6: Then the API response should contain property "meta.total"
610
+ * Example #7: Then the JSON response should have property "createdAt"
611
+ * Example #8: Then the API response should contain property "links.self"
438
612
  */
439
613
  Then(/^(?:the JSON response should have property|the API response should contain property) "([^"]*)"$/, function (propertyPath) {
440
614
  if (!apiResponse) {
@@ -452,6 +626,12 @@ Then(/^(?:the JSON response should have property|the API response should contain
452
626
  *
453
627
  * Example #1: Then the JSON response should not have property "password"
454
628
  * Example #2: Then the API response should not contain property "secret"
629
+ * Example #3: Then the JSON response should not have property "token"
630
+ * Example #4: Then the API response should not contain property "apiKey"
631
+ * Example #5: Then the JSON response should not have property "user.password"
632
+ * Example #6: Then the API response should not contain property "internal"
633
+ * Example #7: Then the JSON response should not have property "debug"
634
+ * Example #8: Then the API response should not contain property "stack"
455
635
  */
456
636
  Then(/^(?:the JSON response should not have property|the API response should not contain property) "([^"]*)"$/, function (propertyPath) {
457
637
  if (!apiResponse) {
@@ -467,8 +647,15 @@ Then(/^(?:the JSON response should not have property|the API response should not
467
647
  /**
468
648
  * Verify the response is valid JSON.
469
649
  *
650
+ * Two equivalent phrasings.
651
+ *
470
652
  * Example #1: Then the response should be valid JSON
471
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
472
659
  */
473
660
  Then(/^(?:the response should be valid JSON|the API response should be valid JSON)$/, function () {
474
661
  if (!apiResponse) {
@@ -484,6 +671,12 @@ Then(/^(?:the response should be valid JSON|the API response should be valid JSO
484
671
  *
485
672
  * Example #1: Then the response header "Content-Type" should be "application/json"
486
673
  * Example #2: Then the header "Cache-Control" should contain "no-cache"
674
+ * Example #3: Then the response header "Content-Type" should contain "charset=utf-8"
675
+ * Example #4: Then the header "X-Powered-By" should be "Webship.co"
676
+ * Example #5: Then the response header "ETag" should contain "etag"
677
+ * Example #6: Then the header "Location" should contain "/users/1"
678
+ * Example #7: Then the response header "Access-Control-Allow-Origin" should be "*"
679
+ * Example #8: Then the header "Content-Length" should contain "0"
487
680
  */
488
681
  Then(/^(?:the response header|the header) "([^"]*)" should (?:be|contain) "([^"]*)"$/, function (headerName, expectedValue) {
489
682
  if (!apiResponse) {
@@ -497,9 +690,19 @@ Then(/^(?:the response header|the header) "([^"]*)" should (?:be|contain) "([^"]
497
690
  });
498
691
 
499
692
  /**
500
- * Prints last API response body for debugging.
693
+ * Prints the most recent API response body to stdout for debugging.
694
+ *
695
+ * Strip before merging — this is a developer aid only.
501
696
  *
502
- * Example: Then print API response
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
503
706
  */
504
707
  Then(/^print API response$/, function () {
505
708
  if (!apiResponse) {
@@ -514,7 +717,14 @@ Then(/^print API response$/, function () {
514
717
  /**
515
718
  * Sets placeholder for replacement in URLs, requests, and responses.
516
719
  *
517
- * Example: Given I set placeholder "{{userId}}" to "123"
720
+ * Example #1: Given I set placeholder "{{userId}}" to "123"
721
+ * Example #2: Given we set placeholder "{{token}}" to "abcd-1234"
722
+ * Example #3: Given I set placeholder "{{postId}}" to "42"
723
+ * Example #4: Given we set placeholder "{{org}}" to "Webship.co"
724
+ * Example #5: Given I set placeholder "{{email}}" to "hello@un.org"
725
+ * Example #6: Given we set placeholder "{{apiKey}}" to "secret-xyz"
726
+ * Example #7: Given I set placeholder "{{version}}" to "v2"
727
+ * Example #8: Given we set placeholder "{{locale}}" to "en-US"
518
728
  */
519
729
  Given(/^(?:I|we) set placeholder "([^"]*)" to "([^"]*)"$/, function (placeholder, value) {
520
730
  placeHolders[placeholder] = value;