webship-js 2.0.2 → 2.0.4

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 (181) hide show
  1. package/.circleci/config.yml +7 -31
  2. package/.drone.yml +68 -0
  3. package/.harness/webship-js-pipeline.yml +101 -0
  4. package/.semaphore/semaphore.yml +58 -0
  5. package/.teamcity/pom.xml +52 -0
  6. package/.teamcity/settings.kts +92 -0
  7. package/.travis.yml +24 -3
  8. package/AGENTS.md +109 -0
  9. package/CLAUDE.md +317 -0
  10. package/Jenkinsfile +54 -0
  11. package/azure-pipelines.yml +82 -0
  12. package/bamboo-specs/bamboo.yml +131 -0
  13. package/bin/generate-reports.js +181 -9
  14. package/buildspec.yml +56 -0
  15. package/cloudbuild.yaml +49 -0
  16. package/codefresh.yml +77 -0
  17. package/cucumber.js +48 -5
  18. package/docs/00-quick-start.md +102 -0
  19. package/docs/01-getting-started.md +102 -0
  20. package/docs/02-bbr-smart-waits.md +77 -0
  21. package/docs/03-selector-registry.md +95 -0
  22. package/docs/04-step-reference.md +799 -0
  23. package/docs/05-web-first-assertions.md +91 -0
  24. package/docs/06-network-and-dialogs.md +83 -0
  25. package/docs/07-auth-state.md +75 -0
  26. package/docs/08-clock-mocking.md +59 -0
  27. package/docs/09-api-testing.md +114 -0
  28. package/docs/10-accessibility.md +167 -0
  29. package/docs/11-debugging.md +129 -0
  30. package/docs/12-ai-agent-guide.md +338 -0
  31. package/docs/13-faq.md +236 -0
  32. package/docs/14-recipes-cookbook.md +255 -0
  33. package/docs/15-tag-conventions.md +76 -0
  34. package/docs/16-ci-cd.md +879 -0
  35. package/docs/README.md +113 -0
  36. package/docs/advanced-screenshots/then-i-save-fullscreen-screenshot.md +36 -0
  37. package/docs/advanced-screenshots/then-i-save-width-x-height-screenshot.md +34 -0
  38. package/docs/advanced-screenshots/when-i-save-screenshot-name-filename.md +45 -0
  39. package/docs/advanced-screenshots.md +52 -0
  40. package/docs/advanced-selectors.md +18 -0
  41. package/docs/api-step-definitions.md +45 -0
  42. package/docs/diffy-step-definitions/then-compare-diffy-env1-env2.md +30 -0
  43. package/docs/diffy-step-definitions/then-create-diffy-comparison-name-value.md +21 -0
  44. package/docs/diffy-step-definitions/then-create-diffy-comparison.md +25 -0
  45. package/docs/diffy-step-definitions/then-create-diffy-screenshot-environment-name.md +35 -0
  46. package/docs/diffy-step-definitions/then-i-take-screenshot.md +21 -0
  47. package/docs/diffy-step-definitions/then-i-take-screenshots-all-breakpoints.md +27 -0
  48. package/docs/diffy-step-definitions/then-send-screenshots-diffy-name-value.md +27 -0
  49. package/docs/diffy-step-definitions/then-upload-folder-url-diffy-snapshotname.md +28 -0
  50. package/docs/diffy-step-definitions/then-wait-diffy-comparison-complete.md +21 -0
  51. package/docs/diffy-step-definitions/when-i-resize-window-number.md +29 -0
  52. package/docs/diffy-step-definitions.md +21 -0
  53. package/docs/global-settings.md +295 -0
  54. package/docs/install-webship-js/ddev-webship-js.md +52 -0
  55. package/docs/install-webship-js.md +35 -0
  56. package/docs/overview.md +41 -0
  57. package/docs/step-definitions/given-i-am-anonymous-user.md +67 -0
  58. package/docs/step-definitions/given-i-am-homepage.md +68 -0
  59. package/docs/step-definitions/given-i-am-specific-page.md +72 -0
  60. package/docs/step-definitions/then-i-should-be.md +56 -0
  61. package/docs/step-definitions/then-i-should-see.md +62 -0
  62. package/docs/step-definitions/then-item-checkbox.md +54 -0
  63. package/docs/step-definitions/then-item-link-should-contain-url.md +84 -0
  64. package/docs/step-definitions/then-item-should-contain.md +67 -0
  65. package/docs/step-definitions/then-radio-button-value-should-be-selected.md +68 -0
  66. package/docs/step-definitions/then-response-status-code-should-be-number.md +69 -0
  67. package/docs/step-definitions/then-value-radio-button-selected.md +62 -0
  68. package/docs/step-definitions/when-i-attach-file-file-name-element.md +71 -0
  69. package/docs/step-definitions/when-i-check-checkbox.md +60 -0
  70. package/docs/step-definitions/when-i-click-link.md +51 -0
  71. package/docs/step-definitions/when-i-click-operation-text-row.md +71 -0
  72. package/docs/step-definitions/when-i-fill.md +59 -0
  73. package/docs/step-definitions/when-i-go-homepage.md +60 -0
  74. package/docs/step-definitions/when-i-go-specific-page.md +67 -0
  75. package/docs/step-definitions/when-i-move-backward-one-page.md +49 -0
  76. package/docs/step-definitions/when-i-move-forward-one-page.md +58 -0
  77. package/docs/step-definitions/when-i-press-button.md +58 -0
  78. package/docs/step-definitions/when-i-reload-page.md +51 -0
  79. package/docs/step-definitions/when-i-scroll.md +73 -0
  80. package/docs/step-definitions/when-i-select-option-select-list.md +53 -0
  81. package/docs/step-definitions/when-i-select-radio-button-value.md +62 -0
  82. package/docs/step-definitions/when-i-uncheck-checkbox.md +57 -0
  83. package/docs/step-definitions/when-i-wait-ajax-finish.md +64 -0
  84. package/docs/step-definitions/when-i-wait.md +62 -0
  85. package/docs/step-definitions.md +50 -0
  86. package/examples/a11y.html +31 -0
  87. package/examples/cookies.html +10 -0
  88. package/examples/date.html +12 -0
  89. package/examples/element.html +11 -0
  90. package/examples/field.html +24 -0
  91. package/examples/keyboard.html +11 -0
  92. package/examples/links.html +9 -0
  93. package/examples/modal.html +14 -0
  94. package/examples/path.html +3 -0
  95. package/examples/table.html +13 -0
  96. package/examples/video-demo.html +43 -0
  97. package/package.json +10 -3
  98. package/playwright.config.ts +3 -2
  99. package/tests/features/a11y.feature +39 -0
  100. package/tests/features/cookie.feature +13 -0
  101. package/tests/features/date.feature +11 -0
  102. package/tests/features/element.feature +16 -0
  103. package/tests/features/field.feature +25 -0
  104. package/tests/features/keyboard.feature +10 -0
  105. package/tests/features/link.feature +11 -0
  106. package/tests/features/modal-advanced-example.feature +1 -1
  107. package/tests/features/modal.feature +11 -0
  108. package/tests/features/path.feature +16 -0
  109. package/tests/features/response.feature +8 -0
  110. package/tests/features/responsive.feature +10 -0
  111. package/tests/features/table.feature +18 -0
  112. package/tests/features/video.feature +18 -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 +7 -1
  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/step-definitions/a11y.steps.js +800 -0
  142. package/tests/step-definitions/action.steps.js +167 -0
  143. package/tests/step-definitions/{webship-api.js → api.steps.js} +41 -23
  144. package/tests/step-definitions/assertion.steps.js +352 -0
  145. package/tests/step-definitions/auth.steps.js +126 -0
  146. package/tests/step-definitions/clock.steps.js +128 -0
  147. package/tests/step-definitions/cookie.steps.js +216 -0
  148. package/tests/step-definitions/debug.steps.js +39 -0
  149. package/tests/step-definitions/dialog.steps.js +193 -0
  150. package/tests/step-definitions/element.steps.js +356 -0
  151. package/tests/step-definitions/field.steps.js +653 -0
  152. package/tests/step-definitions/file-download.steps.js +211 -0
  153. package/tests/step-definitions/form.steps.js +333 -0
  154. package/tests/step-definitions/iframe.steps.js +228 -0
  155. package/tests/step-definitions/input.steps.js +202 -0
  156. package/tests/step-definitions/javascript.steps.js +232 -0
  157. package/tests/step-definitions/keyboard.steps.js +112 -0
  158. package/tests/step-definitions/link.steps.js +142 -0
  159. package/tests/step-definitions/metatag.steps.js +91 -0
  160. package/tests/step-definitions/modal.steps.js +244 -0
  161. package/tests/step-definitions/navigation.steps.js +218 -0
  162. package/tests/step-definitions/network.steps.js +280 -0
  163. package/tests/step-definitions/path.steps.js +141 -0
  164. package/tests/step-definitions/response.steps.js +98 -0
  165. package/tests/step-definitions/responsive.steps.js +125 -0
  166. package/tests/step-definitions/rest.steps.js +111 -0
  167. package/tests/step-definitions/{webship-screenshot.js → screenshot.steps.js} +1 -5
  168. package/tests/step-definitions/scroll.steps.js +189 -0
  169. package/tests/step-definitions/{webship-selectors.js → selectors.steps.js} +64 -27
  170. package/tests/step-definitions/storage.steps.js +194 -0
  171. package/tests/step-definitions/table.steps.js +181 -0
  172. package/tests/step-definitions/video.steps.js +178 -0
  173. package/tests/step-definitions/wait.steps.js +400 -0
  174. package/tests/step-definitions/web-first.steps.js +298 -0
  175. package/tests/step-definitions/webship.js +741 -1477
  176. package/tests/step-definitions/xml.steps.js +411 -0
  177. package/tests/step-definitions/yaml.steps.js +913 -0
  178. package/tests/step-definitions-diffy/webship-diffy.js +0 -13
  179. package/tsconfig.json +19 -3
  180. package/videos/README.md +32 -0
  181. package/.travis-ci.yml +0 -16
@@ -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, friendly } = 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 friendly(
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
+ });
@@ -1,6 +1,7 @@
1
1
  const { Given, When, Then, Before } = require('@cucumber/cucumber');
2
2
  const axios = require('axios');
3
3
  const assert = require('assert');
4
+ const { friendly } = require('./webship');
4
5
 
5
6
  // Global variables to store API response and request data
6
7
  let apiResponse = null;
@@ -49,7 +50,7 @@ function getNestedProperty(obj, path) {
49
50
  * Adds Basic Authentication header to the next request.
50
51
  *
51
52
  * 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
53
+ * Example #2: Given we are authenticating as "user@example.com" with "secret" password
53
54
  * Example #3: Given I am authenticating as "api-user" with "pass!word" password
54
55
  * Example #4: Given we are authenticating as "reader" with "readonly" password
55
56
  *
@@ -68,7 +69,7 @@ Given(/^(?:I am|we are) authenticating as "([^"]*)" with "([^"]*)" password$/, f
68
69
  * Example #3: Given I set header "Accept" with value "application/xml"
69
70
  * Example #4: Given I set header "Accept" with value "application/json"
70
71
  * 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"
72
+ * Example #6: Given I set header "User-Agent" with value "test-runner"
72
73
  * Example #7: Given we set header "Accept-Language" with value "en-US"
73
74
  * Example #8: Given I set header "If-None-Match" with value "etag-xyz"
74
75
  *
@@ -109,7 +110,7 @@ Given(/^(?:the API base URL is|I set the API base URL to|the base URL is) "([^"]
109
110
  * Example #3: Given the header "Accept" is "application/json"
110
111
  * Example #4: Given we set the header "X-Api-Key" to "abcd-1234"
111
112
  * Example #5: Given I set the header "If-Match" to "etag-123"
112
- * Example #6: Given the header "User-Agent" is "webship-js"
113
+ * Example #6: Given the header "User-Agent" is "test-runner"
113
114
  * Example #7: Given we set the header "Accept-Language" to "en-US"
114
115
  * Example #8: Given I set the header "Cache-Control" to "no-cache"
115
116
  *
@@ -132,7 +133,7 @@ Given(/^(?:I set the header|we set the header|the header) "([^"]*)" (?:to|is) "(
132
133
  * | Accept-Language | en-US |
133
134
  *
134
135
  * Example #3: Given I set the following headers:
135
- * | User-Agent | webship-js |
136
+ * | User-Agent | test-runner |
136
137
  * | Cache-Control | no-cache |
137
138
  * | If-None-Match | etag-xyz |
138
139
  *
@@ -163,7 +164,7 @@ Given(/^(?:I set the request body to|we set the request body to|the request body
163
164
  const processedData = replacePlaceHolder(jsonData);
164
165
  apiRequestData = JSON.parse(processedData);
165
166
  } catch (error) {
166
- throw new Error(`Invalid JSON in request body: ${error.message}`);
167
+ throw friendly(`Invalid JSON in request body: ${error.message}`);
167
168
  }
168
169
  });
169
170
 
@@ -232,7 +233,7 @@ When(/^(?:I |we )?send a ([A-Z]+) request to "([^"]+)"$/, async function (method
232
233
  }
233
234
  });
234
235
  } catch (error) {
235
- throw new Error(`${method} request failed: ${error.message}`);
236
+ throw friendly(`${method} request failed: ${error.message}`);
236
237
  }
237
238
  });
238
239
 
@@ -278,7 +279,7 @@ When(/^(?:I |we )?send a ([A-Z]+) request to "([^"]+)" with values:$/, async fun
278
279
  }
279
280
  });
280
281
  } catch (error) {
281
- throw new Error(`${method} request with values failed: ${error.message}`);
282
+ throw friendly(`${method} request with values failed: ${error.message}`);
282
283
  }
283
284
  });
284
285
 
@@ -351,7 +352,7 @@ When(/^(?:I |we )?send a ([A-Z]+) request to "([^"]+)" with body:$/, async funct
351
352
  }
352
353
  });
353
354
  } catch (error) {
354
- throw new Error(`${method} request with body failed: ${error.message}`);
355
+ throw friendly(`${method} request with body failed: ${error.message}`);
355
356
  }
356
357
  });
357
358
 
@@ -416,7 +417,7 @@ When(/^(?:I |we )?send a ([A-Z]+) request to "([^"]+)" with form data:$/, async
416
417
  }
417
418
  });
418
419
  } catch (error) {
419
- throw new Error(`${method} request with form data failed: ${error.message}`);
420
+ throw friendly(`${method} request with form data failed: ${error.message}`);
420
421
  }
421
422
  });
422
423
 
@@ -436,7 +437,7 @@ When(/^(?:I |we )?send a ([A-Z]+) request to "([^"]+)" with form data:$/, async
436
437
  */
437
438
  Then(/^(?:the )?API response code should be (\d+)$/, function (expectedCode) {
438
439
  if (!apiResponse) {
439
- throw new Error('No API response available. Make sure to send a request first.');
440
+ throw friendly('No API response available. Make sure to send a request first.');
440
441
  }
441
442
 
442
443
  const expected = parseInt(expectedCode);
@@ -459,7 +460,7 @@ Then(/^(?:the )?API response code should be (\d+)$/, function (expectedCode) {
459
460
  */
460
461
  Then(/^(?:the )?API response should contain "([^"]*)"$/, function (expectedText) {
461
462
  if (!apiResponse) {
462
- throw new Error('No API response available. Make sure to send a request first.');
463
+ throw friendly('No API response available. Make sure to send a request first.');
463
464
  }
464
465
 
465
466
  const responseBody = typeof apiResponse.data === 'string' ?
@@ -484,7 +485,7 @@ Then(/^(?:the )?API response should contain "([^"]*)"$/, function (expectedText)
484
485
  */
485
486
  Then(/^(?:the )?API response should not contain "([^"]*)"$/, function (unexpectedText) {
486
487
  if (!apiResponse) {
487
- throw new Error('No API response available. Make sure to send a request first.');
488
+ throw friendly('No API response available. Make sure to send a request first.');
488
489
  }
489
490
 
490
491
  const responseBody = typeof apiResponse.data === 'string' ?
@@ -531,7 +532,7 @@ Then(/^(?:the )?API response should not contain "([^"]*)"$/, function (unexpecte
531
532
  */
532
533
  Then(/^(?:the )?API response should contain json:$/, function (docString) {
533
534
  if (!apiResponse) {
534
- throw new Error('No API response available. Make sure to send a request first.');
535
+ throw friendly('No API response available. Make sure to send a request first.');
535
536
  }
536
537
 
537
538
  let expectedJson;
@@ -540,14 +541,14 @@ Then(/^(?:the )?API response should contain json:$/, function (docString) {
540
541
  try {
541
542
  expectedJson = JSON.parse(replacePlaceHolder(docString.trim()));
542
543
  } catch (error) {
543
- throw new Error(`Cannot convert expected JSON: ${docString}`);
544
+ throw friendly(`Cannot convert expected JSON: ${docString}`);
544
545
  }
545
546
 
546
547
  try {
547
548
  actualJson = typeof apiResponse.data === 'string' ?
548
549
  JSON.parse(apiResponse.data) : apiResponse.data;
549
550
  } catch (error) {
550
- throw new Error(`Cannot convert actual response to JSON: ${apiResponse.data}`);
551
+ throw friendly(`Cannot convert actual response to JSON: ${apiResponse.data}`);
551
552
  }
552
553
 
553
554
  // Check that expected properties exist in actual response and match values
@@ -573,7 +574,7 @@ Then(/^(?:the )?API response should contain json:$/, function (docString) {
573
574
  */
574
575
  Then(/^(?:the JSON response should have|the API response should have|the JSON property) "([^"]*)" (?:equal to|should be) (.+)$/, function (propertyPath, expectedValue) {
575
576
  if (!apiResponse) {
576
- throw new Error('No API response available. Make sure to send a request first.');
577
+ throw friendly('No API response available. Make sure to send a request first.');
577
578
  }
578
579
 
579
580
  // Replace placeholders in expected value first
@@ -612,7 +613,7 @@ Then(/^(?:the JSON response should have|the API response should have|the JSON pr
612
613
  */
613
614
  Then(/^(?:the JSON response should have property|the API response should contain property) "([^"]*)"$/, function (propertyPath) {
614
615
  if (!apiResponse) {
615
- throw new Error('No API response available. Make sure to send a request first.');
616
+ throw friendly('No API response available. Make sure to send a request first.');
616
617
  }
617
618
 
618
619
  const actualValue = getNestedProperty(apiResponse.data, propertyPath);
@@ -635,7 +636,7 @@ Then(/^(?:the JSON response should have property|the API response should contain
635
636
  */
636
637
  Then(/^(?:the JSON response should not have property|the API response should not contain property) "([^"]*)"$/, function (propertyPath) {
637
638
  if (!apiResponse) {
638
- throw new Error('No API response available. Make sure to send a request first.');
639
+ throw friendly('No API response available. Make sure to send a request first.');
639
640
  }
640
641
 
641
642
  const actualValue = getNestedProperty(apiResponse.data, propertyPath);
@@ -647,12 +648,19 @@ Then(/^(?:the JSON response should not have property|the API response should not
647
648
  /**
648
649
  * Verify the response is valid JSON.
649
650
  *
651
+ * Two equivalent phrasings.
652
+ *
650
653
  * Example #1: Then the response should be valid JSON
651
654
  * Example #2: Then the API response should be valid JSON
655
+ * Example #3: And the response should be valid JSON
656
+ * Example #4: When I send a GET request to "/api/users"
657
+ * Then the API response should be valid JSON
658
+ * Example #5: When I send a POST request to "/api/orders"
659
+ * Then the response should be valid JSON
652
660
  */
653
661
  Then(/^(?:the response should be valid JSON|the API response should be valid JSON)$/, function () {
654
662
  if (!apiResponse) {
655
- throw new Error('No API response available. Make sure to send a request first.');
663
+ throw friendly('No API response available. Make sure to send a request first.');
656
664
  }
657
665
 
658
666
  assert(typeof apiResponse.data === 'object' && apiResponse.data !== null,
@@ -673,7 +681,7 @@ Then(/^(?:the response should be valid JSON|the API response should be valid JSO
673
681
  */
674
682
  Then(/^(?:the response header|the header) "([^"]*)" should (?:be|contain) "([^"]*)"$/, function (headerName, expectedValue) {
675
683
  if (!apiResponse) {
676
- throw new Error('No API response available. Make sure to send a request first.');
684
+ throw friendly('No API response available. Make sure to send a request first.');
677
685
  }
678
686
 
679
687
  const actualValue = apiResponse.headers[headerName.toLowerCase()];
@@ -683,9 +691,19 @@ Then(/^(?:the response header|the header) "([^"]*)" should (?:be|contain) "([^"]
683
691
  });
684
692
 
685
693
  /**
686
- * Prints last API response body for debugging.
687
- *
688
- * Example: Then print API response
694
+ * Prints the most recent API response body to stdout for debugging.
695
+ *
696
+ * Strip before merging — this is a developer aid only.
697
+ *
698
+ * Example #1: Then print API response
699
+ * Example #2: When I send a GET request to "/api/users"
700
+ * Then print API response
701
+ * Example #3: And print API response
702
+ * Example #4: When I send a POST request to "/api/login"
703
+ * Then the API response code should be 200
704
+ * And print API response
705
+ * Example #5: When I send a DELETE request to "/api/orders/1"
706
+ * Then print API response
689
707
  */
690
708
  Then(/^print API response$/, function () {
691
709
  if (!apiResponse) {