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
@@ -2,14 +2,13 @@
2
2
 
3
3
  'use strict';
4
4
 
5
+ const fs = require('fs');
5
6
  const path = require('path');
6
7
  const reporter = require('cucumber-html-reporter');
7
8
 
8
9
  const THEMES = new Set(['bootstrap', 'hierarchy', 'foundation', 'simple']);
9
-
10
- function bool(v) {
11
- return v !== 'false' && v !== '0' && v !== 'no';
12
- }
10
+ const FORMATS = new Set(['html', 'pdf', 'all']);
11
+ const PDF_FORMATS = new Set(['Letter', 'Legal', 'Tabloid', 'Ledger', 'A0', 'A1', 'A2', 'A3', 'A4', 'A5', 'A6']);
13
12
 
14
13
  function capitalize(s) {
15
14
  return s ? s.charAt(0).toUpperCase() + s.slice(1) : s;
@@ -25,6 +24,11 @@ function parseArgs(argv) {
25
24
  noInlineScreenshots: false,
26
25
  storeScreenshots: false,
27
26
  ignoreBadJsonFile: false,
27
+ formats: [],
28
+ pdfFormat: 'A4',
29
+ pdfLandscape: false,
30
+ pdfMargin: '20mm',
31
+ pdfPrintBackground: true,
28
32
  };
29
33
  for (let i = 0; i < argv.length; i++) {
30
34
  const a = argv[i];
@@ -53,6 +57,24 @@ function parseArgs(argv) {
53
57
  case '--platform': opts.metadata['Platform'] = next(); break;
54
58
  case '--parallel': opts.metadata['Parallel'] = next(); break;
55
59
  case '--executed': opts.metadata['Executed'] = next(); break;
60
+ case '--format': {
61
+ const f = (next() || '').toLowerCase();
62
+ if (!FORMATS.has(f)) {
63
+ console.error(`[webship-js] Unknown format "${f}". Use: ${[...FORMATS].join(', ')}`);
64
+ process.exit(1);
65
+ }
66
+ if (f === 'all') opts.formats.push('html', 'pdf');
67
+ else opts.formats.push(f);
68
+ break;
69
+ }
70
+ case '--pdf-out': opts.pdfOut = next(); break;
71
+ case '--pdf-format': opts.pdfFormat = next(); break;
72
+ case '--pdf-landscape': opts.pdfLandscape = true; break;
73
+ case '--pdf-margin': opts.pdfMargin = next(); break;
74
+ case '--pdf-no-background': opts.pdfPrintBackground = false; break;
75
+ case '--pdf-header': opts.pdfHeaderTemplate = next(); break;
76
+ case '--pdf-footer': opts.pdfFooterTemplate = next(); break;
77
+ case '--pdf-scale': opts.pdfScale = Number(next()); break;
56
78
  case '--metadata': {
57
79
  const kv = next() || '';
58
80
  const eq = kv.indexOf('=');
@@ -66,6 +88,7 @@ function parseArgs(argv) {
66
88
  }
67
89
  }
68
90
  }
91
+ if (opts.formats.length === 0) opts.formats = ['html'];
69
92
  return opts;
70
93
  }
71
94
 
@@ -74,13 +97,25 @@ function printHelp() {
74
97
  [
75
98
  'Usage: generate-reports [options]',
76
99
  '',
77
- 'Generate cucumber HTML report from JSON output.',
100
+ 'Generate HTML / PDF report from cucumber JSON output.',
78
101
  '',
79
102
  'Input / Output:',
80
103
  ' --json <path> JSON input (env WEBSHIP_REPORT_JSON,',
81
104
  ' default: tests/reports/cucumber_report.json)',
82
105
  ' --out <path> HTML output (env WEBSHIP_REPORT_OUT,',
83
106
  ' default: tests/reports/cucumber_report.html)',
107
+ ' --format <kind> html | pdf | all (repeatable)',
108
+ ' default: html',
109
+ '',
110
+ 'PDF options (require --format pdf or all):',
111
+ ' --pdf-out <path> PDF output (default: <out>.pdf)',
112
+ ' --pdf-format <name> Letter | Legal | A3 | A4 | A5 | … (default: A4)',
113
+ ' --pdf-landscape Landscape orientation',
114
+ ' --pdf-margin <css> Margin all sides (default: 20mm)',
115
+ ' --pdf-no-background Disable print background colors / images',
116
+ ' --pdf-header <html> Header template HTML',
117
+ ' --pdf-footer <html> Footer template HTML',
118
+ ' --pdf-scale <n> Scale factor 0.1-2.0',
84
119
  '',
85
120
  'Format:',
86
121
  ' --theme <name> bootstrap | hierarchy | foundation | simple',
@@ -108,11 +143,131 @@ function printHelp() {
108
143
  '',
109
144
  ' -h, --help Show this help',
110
145
  '',
146
+ 'Examples:',
147
+ ' generate-reports',
148
+ ' generate-reports --format pdf --pdf-format Letter --pdf-landscape',
149
+ ' generate-reports --format all --launch',
150
+ '',
111
151
  ].join('\n')
112
152
  );
113
153
  }
114
154
 
115
- function run(argv) {
155
+ async function generatePdf(htmlPath, pdfPath, args) {
156
+ let chromium;
157
+ try {
158
+ ({ chromium } = require('playwright'));
159
+ } catch (err) {
160
+ throw new Error(
161
+ 'PDF generation requires "playwright". Run `npm install playwright` and try again.\n' +
162
+ `Original error: ${err.message}`
163
+ );
164
+ }
165
+ if (!PDF_FORMATS.has(args.pdfFormat)) {
166
+ throw new Error(`Unknown --pdf-format "${args.pdfFormat}". Use: ${[...PDF_FORMATS].join(', ')}`);
167
+ }
168
+ const browser = await chromium.launch();
169
+ try {
170
+ const context = await browser.newContext();
171
+ const page = await context.newPage();
172
+ const fileUrl = 'file://' + path.resolve(htmlPath);
173
+ // The cucumber-html-reporter output references CDN scripts that may
174
+ // never settle; use `domcontentloaded` and add a short render delay.
175
+ // `commit` returns once navigation accepts; safer than domcontentloaded
176
+ // when the report references third-party CDN assets that may stall.
177
+ await page.goto(fileUrl, { waitUntil: 'commit', timeout: 60000 });
178
+ await page.waitForLoadState('domcontentloaded', { timeout: 30000 }).catch(() => {});
179
+ await page.waitForTimeout(2500);
180
+
181
+ // Render exactly what is shown on screen (preserves badges, panels,
182
+ // gradients). The `print` media flips to greyscale on many themes.
183
+ await page.emulateMedia({ media: 'screen' });
184
+
185
+ // Force-expand every collapsed feature/scenario block and apply
186
+ // print-friendly styles so the PDF shows ALL steps without clipping.
187
+ await page.addStyleTag({ content: `
188
+ /* Preserve every color (status badges, panels, charts) when printing. */
189
+ *, *::before, *::after {
190
+ -webkit-print-color-adjust: exact !important;
191
+ print-color-adjust: exact !important;
192
+ color-adjust: exact !important;
193
+ }
194
+ @media print {
195
+ .collapse, .panel-collapse, [aria-expanded="false"] + .collapse,
196
+ .collapse.in, .collapse.show, .collapsing {
197
+ display: block !important;
198
+ visibility: visible !important;
199
+ height: auto !important;
200
+ max-height: none !important;
201
+ overflow: visible !important;
202
+ opacity: 1 !important;
203
+ }
204
+ .feature, .feature-container, .scenario, .scenario-container,
205
+ .row.steps, .step, .features-summary { page-break-inside: avoid; }
206
+ .feature, .feature-container { page-break-before: auto; }
207
+ details { display: block !important; } details > * { display: block !important; }
208
+ a[href]:after { content: ""; }
209
+ .btn, button.collapse-toggle, .toggle-icon, .glyphicon-chevron-right,
210
+ .glyphicon-chevron-down { display: none !important; }
211
+ pre, code { white-space: pre-wrap !important; word-wrap: break-word !important; }
212
+ img { max-width: 100% !important; height: auto !important; }
213
+ }
214
+ .collapse { display: block !important; height: auto !important; }
215
+ .collapsing { transition: none !important; }
216
+ details:not([open]) { }
217
+ ` });
218
+
219
+ // Flatten the report: kill every script, expand every panel, neutralise
220
+ // every collapse trigger so the resulting PDF is static. No JS runs at
221
+ // PDF time — what you see is exactly what gets rendered.
222
+ await page.evaluate(() => {
223
+ document.querySelectorAll('script').forEach(s => s.remove());
224
+ document.querySelectorAll('[data-toggle], [data-bs-toggle]').forEach(el => {
225
+ el.removeAttribute('data-toggle');
226
+ el.removeAttribute('data-bs-toggle');
227
+ el.removeAttribute('data-target');
228
+ el.removeAttribute('data-bs-target');
229
+ el.removeAttribute('href');
230
+ el.style.cursor = 'default';
231
+ });
232
+ document.querySelectorAll('.collapse, .panel-collapse, [class*="collapse"]').forEach(el => {
233
+ el.classList.add('in', 'show');
234
+ el.classList.remove('collapsing');
235
+ el.style.cssText += ';height:auto !important;display:block !important;visibility:visible !important;opacity:1 !important;';
236
+ el.setAttribute('aria-expanded', 'true');
237
+ });
238
+ document.querySelectorAll('[aria-expanded]').forEach(el => el.setAttribute('aria-expanded', 'true'));
239
+ document.querySelectorAll('details').forEach(el => el.setAttribute('open', ''));
240
+ document.querySelectorAll('.glyphicon-chevron-right').forEach(el => {
241
+ el.classList.remove('glyphicon-chevron-right');
242
+ el.classList.add('glyphicon-chevron-down');
243
+ });
244
+ });
245
+ await page.waitForTimeout(300);
246
+ const opts = {
247
+ path: pdfPath,
248
+ format: args.pdfFormat,
249
+ landscape: !!args.pdfLandscape,
250
+ printBackground: args.pdfPrintBackground,
251
+ margin: {
252
+ top: args.pdfMargin,
253
+ right: args.pdfMargin,
254
+ bottom: args.pdfMargin,
255
+ left: args.pdfMargin,
256
+ },
257
+ };
258
+ if (args.pdfHeaderTemplate || args.pdfFooterTemplate) {
259
+ opts.displayHeaderFooter = true;
260
+ if (args.pdfHeaderTemplate) opts.headerTemplate = args.pdfHeaderTemplate;
261
+ if (args.pdfFooterTemplate) opts.footerTemplate = args.pdfFooterTemplate;
262
+ }
263
+ if (Number.isFinite(args.pdfScale)) opts.scale = args.pdfScale;
264
+ await page.pdf(opts);
265
+ } finally {
266
+ await browser.close();
267
+ }
268
+ }
269
+
270
+ async function run(argv) {
116
271
  const args = parseArgs(argv);
117
272
  if (args.help) return printHelp();
118
273
 
@@ -162,13 +317,17 @@ function run(argv) {
162
317
  metadata[k] = v;
163
318
  }
164
319
 
320
+ const wantHtml = args.formats.includes('html');
321
+ const wantPdf = args.formats.includes('pdf');
322
+ const needsHtmlForExport = wantPdf;
323
+
165
324
  const options = {
166
325
  theme,
167
326
  jsonFile,
168
327
  output,
169
328
  reportSuiteAsScenarios: args.reportSuiteAsScenarios,
170
329
  scenarioTimestamp: args.scenarioTimestamp,
171
- launchReport: args.launchReport,
330
+ launchReport: args.launchReport && wantHtml,
172
331
  brandTitle:
173
332
  args.brandTitle || process.env.WEBSHIP_REPORT_TITLE || 'Test Report',
174
333
  name: args.name || process.env.WEBSHIP_REPORT_NAME,
@@ -181,11 +340,24 @@ function run(argv) {
181
340
  metadata,
182
341
  };
183
342
 
184
- reporter.generate(options);
343
+ if (wantHtml || needsHtmlForExport) {
344
+ reporter.generate(options);
345
+ console.log(`[webship-js] HTML report → ${output}`);
346
+ }
347
+
348
+ if (wantPdf) {
349
+ const pdfOut = path.resolve(cwd, args.pdfOut || output.replace(/\.html?$/i, '') + '.pdf');
350
+ await generatePdf(output, pdfOut, args);
351
+ console.log(`[webship-js] PDF report → ${pdfOut}`);
352
+ }
353
+
185
354
  }
186
355
 
187
356
  if (require.main === module) {
188
- run(process.argv.slice(2));
357
+ Promise.resolve(run(process.argv.slice(2))).catch(err => {
358
+ console.error(`[webship-js] ${err.message || err}`);
359
+ process.exit(1);
360
+ });
189
361
  }
190
362
 
191
363
  module.exports = { run };
package/buildspec.yml ADDED
@@ -0,0 +1,56 @@
1
+ # AWS CodeBuild spec for webship-js.
2
+ #
3
+ # Runs the full BDD suite on AWS-managed compute. Pair with CodePipeline
4
+ # (for source/build/test orchestration) or invoke CodeBuild directly from a
5
+ # GitHub webhook. Free tier covers 100 build-minutes / month on
6
+ # `general1.small` indefinitely.
7
+ #
8
+ # Suggested CodeBuild project settings:
9
+ # Environment image: aws/codebuild/standard:7.0
10
+ # Compute: general1.small (3 GB RAM, 2 vCPU) — fits the suite
11
+ # Service role: needs S3 PutObject for the artifacts bucket
12
+ #
13
+ # See docs/16-ci-cd.md → "AWS CodeBuild" for the account + project walkthrough.
14
+
15
+ version: 0.2
16
+
17
+ env:
18
+ variables:
19
+ FORCE_COLOR: "1"
20
+ LAUNCH_URL: "http://localhost:8080"
21
+ NPM_CONFIG_CACHE: "/codebuild/output/npm-cache"
22
+
23
+ phases:
24
+ install:
25
+ runtime-versions:
26
+ nodejs: 20
27
+ commands:
28
+ - node --version
29
+ - npm --version
30
+ - npm install
31
+ - npx playwright install --with-deps chromium
32
+
33
+ pre_build:
34
+ commands:
35
+ - nohup npm start > /tmp/srv.log 2>&1 &
36
+ - sleep 3
37
+ - curl -sf http://localhost:8080/ > /dev/null
38
+
39
+ build:
40
+ commands:
41
+ - npm test
42
+
43
+ cache:
44
+ paths:
45
+ - 'node_modules/**/*'
46
+ - '/root/.cache/ms-playwright/**/*'
47
+ - '/codebuild/output/npm-cache/**/*'
48
+
49
+ artifacts:
50
+ name: webship-js-report-$(date +%Y%m%d-%H%M%S)
51
+ files:
52
+ - tests/reports/cucumber_report.html
53
+ - tests/reports/cucumber_report.pdf
54
+ - tests/reports/cucumber_report.json
55
+ - screenshots/**/*
56
+ discard-paths: no
@@ -0,0 +1,49 @@
1
+ # Google Cloud Build config for webship-js.
2
+ #
3
+ # Runs the full BDD suite inside a Playwright-prepped container on Google's
4
+ # managed builder pool. Free tier (post-$300 credit): 120 build-minutes per
5
+ # day on the default `e2-standard-2` machine — the 9-minute suite fits ~13
6
+ # runs / day.
7
+ #
8
+ # Setup (full walkthrough in docs/16-ci-cd.md → "Google Cloud Build"):
9
+ # 1. console.cloud.google.com → create project → enable Cloud Build API.
10
+ # 2. Cloud Build → Triggers → Connect repository → GitHub OAuth.
11
+ # 3. Add trigger pointing at this file on branch ^2\.0\.x$.
12
+
13
+ substitutions:
14
+ _BRANCH_NAME: '2.0.x'
15
+ _ARTIFACT_BUCKET: 'webship-js-reports'
16
+
17
+ options:
18
+ logging: CLOUD_LOGGING_ONLY
19
+ machineType: 'E2_STANDARD_2'
20
+
21
+ timeout: '1800s'
22
+
23
+ steps:
24
+ - id: install-and-test
25
+ name: 'mcr.microsoft.com/playwright:v1.58.2-jammy'
26
+ entrypoint: 'bash'
27
+ env:
28
+ - 'FORCE_COLOR=1'
29
+ - 'LAUNCH_URL=http://localhost:8080'
30
+ args:
31
+ - '-c'
32
+ - |
33
+ set -euo pipefail
34
+ node --version
35
+ npm --version
36
+ npm install
37
+ npx playwright install --with-deps chromium
38
+ nohup npm start > /tmp/srv.log 2>&1 &
39
+ sleep 3
40
+ curl -sf http://localhost:8080/ > /dev/null
41
+ npm test
42
+
43
+ artifacts:
44
+ objects:
45
+ location: 'gs://${_ARTIFACT_BUCKET}/$BUILD_ID/'
46
+ paths:
47
+ - 'tests/reports/cucumber_report.html'
48
+ - 'tests/reports/cucumber_report.pdf'
49
+ - 'tests/reports/cucumber_report.json'
package/codefresh.yml ADDED
@@ -0,0 +1,77 @@
1
+ # Codefresh Classic pipeline for webship-js.
2
+ #
3
+ # Codefresh is a Kubernetes-native CI/CD platform. The Classic pipeline format
4
+ # (used here) reads `codefresh.yml` from the repository. Free tier covers 100
5
+ # build-minutes per month on shared infrastructure; OSS public repositories
6
+ # can apply for the Community plan with more capacity.
7
+ #
8
+ # Setup (full walkthrough in docs/16-ci-cd.md → "Codefresh"):
9
+ # 1. codefresh.io → sign up with GitHub → create pipeline → "Inline YAML
10
+ # from repository".
11
+ # 2. Point at this file on branch 2.0.x.
12
+ #
13
+ # References:
14
+ # - https://codefresh.io/docs/docs/pipelines/pipeline-spec/
15
+ # - https://codefresh.io/docs/docs/pipelines/steps/
16
+
17
+ version: "1.0"
18
+ kind: pipeline
19
+
20
+ stages:
21
+ - prepare
22
+ - test
23
+
24
+ steps:
25
+ main_clone:
26
+ title: "Clone repository"
27
+ type: git-clone
28
+ arguments:
29
+ repo: "${{CF_REPO_OWNER}}/${{CF_REPO_NAME}}"
30
+ revision: "${{CF_REVISION}}"
31
+ git: github
32
+ stage: prepare
33
+
34
+ install_dependencies:
35
+ title: "Install npm dependencies + Playwright browsers"
36
+ type: freestyle
37
+ image: mcr.microsoft.com/playwright:v1.58.2-jammy
38
+ working_directory: ${{main_clone}}
39
+ environment:
40
+ - FORCE_COLOR=1
41
+ commands:
42
+ - node --version
43
+ - npm --version
44
+ - npm install
45
+ - npx playwright install --with-deps chromium
46
+ stage: prepare
47
+
48
+ test_suite:
49
+ title: "Run cucumber-js"
50
+ type: freestyle
51
+ image: mcr.microsoft.com/playwright:v1.58.2-jammy
52
+ working_directory: ${{main_clone}}
53
+ environment:
54
+ - FORCE_COLOR=1
55
+ - LAUNCH_URL=http://localhost:8080
56
+ commands:
57
+ - nohup npm start > /tmp/srv.log 2>&1 &
58
+ - sleep 3
59
+ - curl -sf http://localhost:8080/ > /dev/null
60
+ - npm test
61
+ stage: test
62
+
63
+ upload_reports:
64
+ title: "Upload HTML / PDF / JSON cucumber report"
65
+ type: freestyle
66
+ image: alpine:3
67
+ working_directory: ${{main_clone}}
68
+ when:
69
+ condition:
70
+ any:
71
+ successOnly: "'${{TEST_SUITE_OUTCOME}}' == 'success'"
72
+ failureToo: "true"
73
+ commands:
74
+ - mkdir -p /codefresh/volume/cucumber-report
75
+ - cp -a tests/reports/cucumber_report.html tests/reports/cucumber_report.pdf tests/reports/cucumber_report.json /codefresh/volume/cucumber-report/ || true
76
+ - cp -a screenshots /codefresh/volume/cucumber-report/screenshots 2>/dev/null || true
77
+ stage: test
package/cucumber.js CHANGED
@@ -1,10 +1,17 @@
1
1
  module.exports = {
2
2
  default: {
3
- timeout: 30000,
4
- requireModule: ['ts-node/register'],
3
+ // Cucumber step timeout must exceed Playwright's default 30s so the
4
+ // try/catch wrappers in step files always see the Playwright error
5
+ // first (and emit a friendly message) rather than cucumber's raw
6
+ // "function timed out" stack.
7
+ timeout: 45000,
8
+ // tsx/cjs registers a require() hook so cucumber-js can load both
9
+ // `.js` and `.ts` step files with zero build step. If you ship only
10
+ // JavaScript, drop `requireModule` and the `.ts` half of the glob.
11
+ requireModule: ['tsx/cjs'],
5
12
  require: [
6
- 'tests/step-definitions/**/*.js', // Default Webship-js step definitions.
7
- 'tests/step-definitions-diffy/**/*.js', // diffy.website step definitions.
13
+ 'tests/step-definitions/**/*.js',
14
+ 'tests/step-definitions-diffy/**/*.js',
8
15
  ],
9
16
  paths: ['tests/features/**/*.feature'],
10
17
  format: [
@@ -12,7 +19,8 @@ module.exports = {
12
19
  'json:tests/reports/cucumber_report.json',
13
20
  ],
14
21
  formatOptions: {
15
- colorsEnabled: true,
22
+ // Color toggle is controlled via the FORCE_COLOR env var (per
23
+ // cucumber-js v10+); the deprecated `colorsEnabled` option is gone.
16
24
  theme: {
17
25
  'feature keyword': ['bold', 'blue'],
18
26
  'feature name': ['blue', 'underline'],
@@ -78,6 +86,41 @@ module.exports = {
78
86
  filenamePatternFailed: '{failed_prefix}{datetime}.{feature_file}.feature_{step_line}.{ext}', // WEBSHIP_SCREENSHOT_PATTERN_FAIL
79
87
  infoTypes: '', // WEBSHIP_SCREENSHOT_INFO_TYPES e.g. "url,feature,step,datetime"
80
88
  },
89
+ video: {
90
+ // Record the browser as a webm video.
91
+ // 'off' (default) — no recording.
92
+ // 'on' — record every scenario.
93
+ // 'on-failure' — record every scenario, keep only failures.
94
+ // 'tag' — record only scenarios tagged @video.
95
+ // Override per scenario with tags:
96
+ // @video — force recording on (independent of mode).
97
+ // @no-video — suppress recording for this scenario.
98
+ // Override per run with env: WEBSHIP_VIDEO.
99
+ mode: 'off', // WEBSHIP_VIDEO
100
+ dir: './videos', // WEBSHIP_VIDEO_DIR
101
+ size: { width: 1280, height: 720 }, // viewport size of the recording
102
+ // Filename template tokens: {datetime} {feature_file} {feature} {scenario}
103
+ // {status} {ext}. Sanitised to filesystem-safe characters.
104
+ filenamePattern: '{datetime}.{feature_file}.{scenario}.{status}.{ext}',
105
+ },
106
+ javascript: {
107
+ // How to report collected JavaScript errors at scenario end.
108
+ // 'warn' (default) — log a yellow warning, scenario still passes.
109
+ // 'fail' — fail the scenario.
110
+ // 'off' — silent.
111
+ // Override per scenario with tags: @js-fail, @js-warn, @js-off.
112
+ // Override per run with env: WEBSHIP_JS_ERROR_MODE.
113
+ mode: 'warn', // WEBSHIP_JS_ERROR_MODE
114
+ // Console levels to capture in addition to `pageerror`.
115
+ // Common: ['error'], ['error','warning'], ['error','warning','info'].
116
+ levels: ['error'], // WEBSHIP_JS_ERROR_LEVELS (csv)
117
+ // Regex string. Errors whose message matches are ignored.
118
+ ignore: '', // WEBSHIP_JS_ERROR_IGNORE
119
+ // Snapshot any pre-existing errors at scenario start.
120
+ beforeScenario: false, // WEBSHIP_JS_ERROR_BEFORE
121
+ // Report collected errors at scenario end (default true).
122
+ afterScenario: true, // WEBSHIP_JS_ERROR_AFTER
123
+ },
81
124
  diffy: {
82
125
  apiKey: 'mock-key', // DIFFY_API_KEY
83
126
  projectId: 1, // DIFFY_PROJECT_ID
@@ -0,0 +1,102 @@
1
+ # Quick Start (5 minutes)
2
+
3
+ Brand new to webship-js? Read this page once. You'll be writing tests in
4
+ five minutes.
5
+
6
+ ## What you write
7
+
8
+ Plain English scenarios. No JavaScript required.
9
+
10
+ ```gherkin
11
+ Feature: Sign in
12
+
13
+ Scenario: Successful login
14
+ Given I am on "/login"
15
+ When I fill in "Email" with "alice@example.com"
16
+ And I fill in "Password" with "s3cret"
17
+ And I press "Sign in"
18
+ Then I should see "Welcome, Alice"
19
+ ```
20
+
21
+ That's a complete test. Every line maps to a built-in step. No setup
22
+ code. No selector jargon.
23
+
24
+ ## What you get
25
+
26
+ * **Real browser** — runs in Chromium, Firefox, or WebKit via Playwright.
27
+ * **Automatic smart waits** — every action waits for the page to
28
+ settle. No `sleep` / `wait 5s` needed in the happy path.
29
+ * **HTML report** — runs auto-generate `tests/reports/cucumber_report.html`.
30
+ * **Screenshots on failure** — saved to `screenshots/` for instant
31
+ debugging.
32
+
33
+ ## 30-second install
34
+
35
+ ```bash
36
+ npm install webship-js --save-dev
37
+ ```
38
+
39
+ The post-install script copies a starter `cucumber.js`,
40
+ `playwright.config.ts`, and `tests/` skeleton.
41
+
42
+ ## 60-second first test
43
+
44
+ 1. Drop your scenario into `tests/features/smoke.feature`.
45
+ 2. Make sure your dev server is running on `http://localhost:8080`
46
+ (or set `LAUNCH_URL` to point elsewhere).
47
+ 3. Run:
48
+
49
+ ```bash
50
+ npm test
51
+ ```
52
+
53
+ If your scenario passes, you're done. If it fails, the Cucumber output
54
+ names the step that failed and the expected vs actual.
55
+
56
+ ## Where to go next
57
+
58
+ | Want to… | Read |
59
+ | --- | --- |
60
+ | Understand smart waits (no `sleep`) | [02 BBR smart waits](02-bbr-smart-waits.md) |
61
+ | Use named selectors instead of long CSS | [03 Selector registry](03-selector-registry.md) |
62
+ | See every built-in step | [04 Step reference](04-step-reference.md) |
63
+ | Test forms / clicks / modals | [04 Step reference](04-step-reference.md) |
64
+ | Mock APIs / dialogs | [06 Networking & dialogs](06-network-and-dialogs.md) |
65
+ | Accessibility audits | [10 Accessibility](10-accessibility.md) |
66
+ | Use AI to generate tests | [12 AI agent guide](12-ai-agent-guide.md) |
67
+ | FAQ | [13 FAQ](13-faq.md) |
68
+ | Recipes cookbook | [14 Recipes cookbook](14-recipes-cookbook.md) |
69
+
70
+ ## The mental model
71
+
72
+ * `Given` — set up the scene (navigate, restore auth, seed data).
73
+ * `When` — do something (click, fill, submit).
74
+ * `Then` — check what should be true (text visible, URL changed).
75
+ * `And` / `But` — continuation. Pick whichever reads naturally.
76
+ * `Background:` — steps shared across every scenario in a feature.
77
+ * `Scenario Outline:` + `Examples:` — same scenario with different data.
78
+
79
+ ## The golden rule
80
+
81
+ **Wait for events, not time.** Webship-js does this for you in the
82
+ common case. If you ever feel tempted to add `wait 5 seconds` because
83
+ something flaked, look for an event-based wait first:
84
+
85
+ ```gherkin
86
+ # Bad — slow, brittle.
87
+ When I press "Save"
88
+ And I wait 5 seconds
89
+ Then I should see "Saved"
90
+
91
+ # Good — instant when fast, patient when slow.
92
+ When I press "Save"
93
+ Then I should see "Saved"
94
+
95
+ # Best when "Save" navigates.
96
+ When I press "Save"
97
+ And I wait until the URL contains "/saved"
98
+ Then I should see "Saved"
99
+ ```
100
+
101
+ That's the entire philosophy. Read [02 BBR smart waits](02-bbr-smart-waits.md)
102
+ when you're ready to internalise the details.