webship-js 2.0.2 → 2.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (162) hide show
  1. package/AGENTS.md +109 -0
  2. package/CLAUDE.md +317 -0
  3. package/bin/generate-reports.js +181 -9
  4. package/cucumber.js +10 -4
  5. package/docs/00-quick-start.md +102 -0
  6. package/docs/01-getting-started.md +102 -0
  7. package/docs/02-bbr-smart-waits.md +77 -0
  8. package/docs/03-selector-registry.md +95 -0
  9. package/docs/04-step-reference.md +728 -0
  10. package/docs/05-web-first-assertions.md +91 -0
  11. package/docs/06-network-and-dialogs.md +83 -0
  12. package/docs/07-auth-state.md +75 -0
  13. package/docs/08-clock-mocking.md +59 -0
  14. package/docs/09-api-testing.md +114 -0
  15. package/docs/10-accessibility.md +167 -0
  16. package/docs/11-debugging.md +129 -0
  17. package/docs/12-ai-agent-guide.md +338 -0
  18. package/docs/13-faq.md +236 -0
  19. package/docs/14-recipes-cookbook.md +255 -0
  20. package/docs/15-tag-conventions.md +76 -0
  21. package/docs/advanced-screenshots/then-i-save-fullscreen-screenshot.md +36 -0
  22. package/docs/advanced-screenshots/then-i-save-width-x-height-screenshot.md +34 -0
  23. package/docs/advanced-screenshots/when-i-save-screenshot-name-filename.md +45 -0
  24. package/docs/advanced-screenshots.md +52 -0
  25. package/docs/advanced-selectors.md +18 -0
  26. package/docs/api-step-definitions.md +45 -0
  27. package/docs/diffy-step-definitions/then-compare-diffy-env1-env2.md +30 -0
  28. package/docs/diffy-step-definitions/then-create-diffy-comparison-name-value.md +21 -0
  29. package/docs/diffy-step-definitions/then-create-diffy-comparison.md +25 -0
  30. package/docs/diffy-step-definitions/then-create-diffy-screenshot-environment-name.md +35 -0
  31. package/docs/diffy-step-definitions/then-i-take-screenshot.md +21 -0
  32. package/docs/diffy-step-definitions/then-i-take-screenshots-all-breakpoints.md +27 -0
  33. package/docs/diffy-step-definitions/then-send-screenshots-diffy-name-value.md +27 -0
  34. package/docs/diffy-step-definitions/then-upload-folder-url-diffy-snapshotname.md +28 -0
  35. package/docs/diffy-step-definitions/then-wait-diffy-comparison-complete.md +21 -0
  36. package/docs/diffy-step-definitions/when-i-resize-window-number.md +29 -0
  37. package/docs/diffy-step-definitions.md +21 -0
  38. package/docs/global-settings.md +244 -0
  39. package/docs/index.md +104 -0
  40. package/docs/install-webship-js/ddev-webship-js.md +52 -0
  41. package/docs/install-webship-js.md +35 -0
  42. package/docs/overview.md +41 -0
  43. package/docs/step-definitions/given-i-am-anonymous-user.md +67 -0
  44. package/docs/step-definitions/given-i-am-homepage.md +68 -0
  45. package/docs/step-definitions/given-i-am-specific-page.md +72 -0
  46. package/docs/step-definitions/then-i-should-be.md +56 -0
  47. package/docs/step-definitions/then-i-should-see.md +62 -0
  48. package/docs/step-definitions/then-item-checkbox.md +54 -0
  49. package/docs/step-definitions/then-item-link-should-contain-url.md +84 -0
  50. package/docs/step-definitions/then-item-should-contain.md +67 -0
  51. package/docs/step-definitions/then-radio-button-value-should-be-selected.md +68 -0
  52. package/docs/step-definitions/then-response-status-code-should-be-number.md +69 -0
  53. package/docs/step-definitions/then-value-radio-button-selected.md +62 -0
  54. package/docs/step-definitions/when-i-attach-file-file-name-element.md +71 -0
  55. package/docs/step-definitions/when-i-check-checkbox.md +60 -0
  56. package/docs/step-definitions/when-i-click-link.md +51 -0
  57. package/docs/step-definitions/when-i-click-operation-text-row.md +71 -0
  58. package/docs/step-definitions/when-i-fill.md +59 -0
  59. package/docs/step-definitions/when-i-go-homepage.md +60 -0
  60. package/docs/step-definitions/when-i-go-specific-page.md +67 -0
  61. package/docs/step-definitions/when-i-move-backward-one-page.md +49 -0
  62. package/docs/step-definitions/when-i-move-forward-one-page.md +58 -0
  63. package/docs/step-definitions/when-i-press-button.md +58 -0
  64. package/docs/step-definitions/when-i-reload-page.md +51 -0
  65. package/docs/step-definitions/when-i-scroll.md +73 -0
  66. package/docs/step-definitions/when-i-select-option-select-list.md +53 -0
  67. package/docs/step-definitions/when-i-select-radio-button-value.md +62 -0
  68. package/docs/step-definitions/when-i-uncheck-checkbox.md +57 -0
  69. package/docs/step-definitions/when-i-wait-ajax-finish.md +64 -0
  70. package/docs/step-definitions/when-i-wait.md +62 -0
  71. package/docs/step-definitions.md +50 -0
  72. package/examples/a11y.html +31 -0
  73. package/examples/cookies.html +10 -0
  74. package/examples/date.html +12 -0
  75. package/examples/element.html +11 -0
  76. package/examples/field.html +24 -0
  77. package/examples/keyboard.html +11 -0
  78. package/examples/links.html +9 -0
  79. package/examples/modal.html +14 -0
  80. package/examples/path.html +3 -0
  81. package/examples/table.html +13 -0
  82. package/package.json +10 -3
  83. package/playwright.config.ts +3 -2
  84. package/tests/features/a11y.feature +39 -0
  85. package/tests/features/cookie.feature +13 -0
  86. package/tests/features/date.feature +11 -0
  87. package/tests/features/element.feature +16 -0
  88. package/tests/features/field.feature +25 -0
  89. package/tests/features/keyboard.feature +10 -0
  90. package/tests/features/link.feature +11 -0
  91. package/tests/features/modal-advanced-example.feature +1 -1
  92. package/tests/features/modal.feature +11 -0
  93. package/tests/features/path.feature +16 -0
  94. package/tests/features/response.feature +8 -0
  95. package/tests/features/responsive.feature +10 -0
  96. package/tests/features/table.feature +18 -0
  97. package/tests/features/wait.feature +7 -0
  98. package/tests/features/yaml.feature +102 -0
  99. package/tests/reports/README.md +55 -0
  100. package/tests/selectors/_canonical-keys.json +113 -0
  101. package/tests/selectors/back-end-selectors.json +7 -1
  102. package/tests/selectors/cms-contentful-admin.json +35 -0
  103. package/tests/selectors/cms-craft-admin.json +39 -0
  104. package/tests/selectors/cms-drupal-cms-gin.json +56 -0
  105. package/tests/selectors/cms-drupal-core-claro.json +50 -0
  106. package/tests/selectors/cms-generic-admin.json +34 -0
  107. package/tests/selectors/cms-ghost-admin.json +34 -0
  108. package/tests/selectors/cms-joomla-admin.json +41 -0
  109. package/tests/selectors/cms-magento2-admin.json +32 -0
  110. package/tests/selectors/cms-prestashop-admin.json +38 -0
  111. package/tests/selectors/cms-shopify-admin.json +25 -0
  112. package/tests/selectors/cms-strapi-admin.json +42 -0
  113. package/tests/selectors/cms-typo3-admin.json +41 -0
  114. package/tests/selectors/cms-woocommerce-front.json +50 -0
  115. package/tests/selectors/cms-wordpress-admin.json +31 -0
  116. package/tests/selectors/framework-ant-design.json +80 -0
  117. package/tests/selectors/framework-bootstrap.json +86 -0
  118. package/tests/selectors/framework-bulma.json +74 -0
  119. package/tests/selectors/framework-chakra.json +58 -0
  120. package/tests/selectors/framework-foundation.json +51 -0
  121. package/tests/selectors/framework-material-ui.json +72 -0
  122. package/tests/selectors/framework-shadcn.json +51 -0
  123. package/tests/selectors/framework-tailwind.json +40 -0
  124. package/tests/selectors/framework-vuetify.json +61 -0
  125. package/tests/step-definitions/a11y.steps.js +798 -0
  126. package/tests/step-definitions/action.steps.js +167 -0
  127. package/tests/step-definitions/{webship-api.js → api.steps.js} +24 -7
  128. package/tests/step-definitions/assertion.steps.js +352 -0
  129. package/tests/step-definitions/auth.steps.js +124 -0
  130. package/tests/step-definitions/clock.steps.js +128 -0
  131. package/tests/step-definitions/cookie.steps.js +216 -0
  132. package/tests/step-definitions/debug.steps.js +31 -0
  133. package/tests/step-definitions/dialog.steps.js +193 -0
  134. package/tests/step-definitions/element.steps.js +314 -0
  135. package/tests/step-definitions/field.steps.js +653 -0
  136. package/tests/step-definitions/file-download.steps.js +193 -0
  137. package/tests/step-definitions/form.steps.js +333 -0
  138. package/tests/step-definitions/iframe.steps.js +178 -0
  139. package/tests/step-definitions/input.steps.js +163 -0
  140. package/tests/step-definitions/javascript.steps.js +71 -0
  141. package/tests/step-definitions/keyboard.steps.js +78 -0
  142. package/tests/step-definitions/link.steps.js +142 -0
  143. package/tests/step-definitions/metatag.steps.js +91 -0
  144. package/tests/step-definitions/modal.steps.js +219 -0
  145. package/tests/step-definitions/navigation.steps.js +218 -0
  146. package/tests/step-definitions/network.steps.js +238 -0
  147. package/tests/step-definitions/path.steps.js +141 -0
  148. package/tests/step-definitions/response.steps.js +98 -0
  149. package/tests/step-definitions/responsive.steps.js +123 -0
  150. package/tests/step-definitions/rest.steps.js +111 -0
  151. package/tests/step-definitions/{webship-screenshot.js → screenshot.steps.js} +1 -5
  152. package/tests/step-definitions/scroll.steps.js +189 -0
  153. package/tests/step-definitions/{webship-selectors.js → selectors.steps.js} +46 -11
  154. package/tests/step-definitions/storage.steps.js +194 -0
  155. package/tests/step-definitions/table.steps.js +181 -0
  156. package/tests/step-definitions/wait.steps.js +400 -0
  157. package/tests/step-definitions/web-first.steps.js +296 -0
  158. package/tests/step-definitions/webship.js +552 -1507
  159. package/tests/step-definitions/xml.steps.js +409 -0
  160. package/tests/step-definitions/yaml.steps.js +911 -0
  161. package/tests/step-definitions-diffy/webship-diffy.js +0 -13
  162. package/tsconfig.json +19 -3
@@ -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/cucumber.js CHANGED
@@ -1,10 +1,15 @@
1
1
  module.exports = {
2
2
  default: {
3
3
  timeout: 30000,
4
- requireModule: ['ts-node/register'],
4
+ // tsx/cjs registers a require() hook so cucumber-js can load both
5
+ // `.js` and `.ts` step files with zero build step. If you ship only
6
+ // JavaScript, drop `requireModule` and the `.ts` half of the glob.
7
+ requireModule: ['tsx/cjs'],
5
8
  require: [
6
- 'tests/step-definitions/**/*.js', // Default Webship-js step definitions.
7
- 'tests/step-definitions-diffy/**/*.js', // diffy.website step definitions.
9
+ 'tests/step-definitions/**/*.js',
10
+ 'tests/step-definitions/**/*.ts',
11
+ 'tests/step-definitions-diffy/**/*.js',
12
+ 'tests/step-definitions-diffy/**/*.ts',
8
13
  ],
9
14
  paths: ['tests/features/**/*.feature'],
10
15
  format: [
@@ -12,7 +17,8 @@ module.exports = {
12
17
  'json:tests/reports/cucumber_report.json',
13
18
  ],
14
19
  formatOptions: {
15
- colorsEnabled: true,
20
+ // Color toggle is controlled via the FORCE_COLOR env var (per
21
+ // cucumber-js v10+); the deprecated `colorsEnabled` option is gone.
16
22
  theme: {
17
23
  'feature keyword': ['bold', 'blue'],
18
24
  'feature name': ['blue', 'underline'],
@@ -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.
@@ -0,0 +1,102 @@
1
+ # Getting Started
2
+
3
+ Webship-js is an automated functional testing harness built on Playwright + Cucumber-js. You write feature files in plain Gherkin; webship-js handles the browser, smart waits, screenshots, reports, and CMS-aware selectors out of the box.
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ npm install webship-js --save-dev
9
+ ```
10
+
11
+ The post-install script copies a starter `cucumber.js`, `playwright.config.ts`, and `tests/` skeleton into your project on first install.
12
+
13
+ ## Project layout
14
+
15
+ ```
16
+ your-project/
17
+ ├── cucumber.js # Profiles + worldParameters
18
+ ├── playwright.config.ts # Browser launch + context options
19
+ └── tests/
20
+ ├── features/ # *.feature files (Gherkin)
21
+ ├── selectors/ # CMS / framework selector JSON
22
+ └── step-definitions/ # *.js or *.ts (loaded automatically)
23
+ ```
24
+
25
+ ## TypeScript and JavaScript together
26
+
27
+ Step definitions can be plain JavaScript (`.js`) or TypeScript (`.ts`) — mix freely in the same project. The default `cucumber.js` registers the [`tsx`](https://tsx.is) require hook, so `.ts` files run with zero build step:
28
+
29
+ ```js
30
+ // cucumber.js (default)
31
+ requireModule: ['tsx/cjs'],
32
+ require: ['tests/step-definitions/**/*.{js,ts}'],
33
+ ```
34
+
35
+ Add a TypeScript step alongside JS ones:
36
+
37
+ ```ts
38
+ // tests/step-definitions/custom.steps.ts
39
+ import { Then } from '@cucumber/cucumber';
40
+ import assert from 'node:assert';
41
+
42
+ Then(/^(I |we )*see a TypeScript step$/, async function (this: { page: import('playwright').Page }) {
43
+ assert.ok(this.page);
44
+ });
45
+ ```
46
+
47
+ Pure-JS shops can drop both `requireModule` and the `.ts` half of the glob.
48
+
49
+ ## Run the suite
50
+
51
+ ```bash
52
+ # Default — full pretty output, optional auto-screenshots on failure.
53
+ npm test
54
+
55
+ # Fast run — no slow-mo.
56
+ npm run test:fast
57
+
58
+ # Watch the browser interactively.
59
+ npm run test:headed
60
+
61
+ # Pick a single browser.
62
+ BROWSER=firefox npm test
63
+ BROWSER=webkit npm test
64
+
65
+ # Parallel + retry (CLI flags — no separate profile needed).
66
+ npx cucumber-js --parallel 4 --retry 1 --retry-tag-filter @flaky
67
+ ```
68
+
69
+ ## Environment variables
70
+
71
+ | Variable | Default | Effect |
72
+ | --- | --- | --- |
73
+ | `LAUNCH_URL` | `http://localhost:8080` | Base URL for `Given I am on "/path"` |
74
+ | `BROWSER` | `chromium` | `chromium` / `firefox` / `webkit` |
75
+ | `HEADLESS` | `true` | Set to `false` for headed mode |
76
+ | `SLOW_MO` | `300` headed: `800` | Per-action delay (ms); set `0` for fast runs |
77
+ | `WEBSHIP_AUTO_SETTLE` | on | Set to `off` to disable auto edge-wait after actions |
78
+
79
+ ## First feature file
80
+
81
+ ```gherkin
82
+ Feature: Smoke
83
+
84
+ Scenario: Homepage loads
85
+ Given I am on the homepage
86
+ Then the page should declare a language
87
+ And the page should have exactly one h1
88
+ And there should be no JavaScript errors
89
+ ```
90
+
91
+ ## Next reading
92
+
93
+ - [BBR smart waits](02-bbr-smart-waits.md) — why we never `sleep N seconds`.
94
+ - [Selector registry](03-selector-registry.md) — named selectors + CMS presets.
95
+ - [Step reference](04-step-reference.md) — every built-in step, by topic.
96
+ - [Web-first assertions](05-web-first-assertions.md) — auto-retrying matchers.
97
+ - [Networking & dialogs](06-network-and-dialogs.md) — mocks, routes, alerts.
98
+ - [Auth state](07-auth-state.md) — save / restore login.
99
+ - [Clock mocking](08-clock-mocking.md) — control time.
100
+ - [API testing](09-api-testing.md) — direct HTTP from BDD.
101
+ - [Accessibility](10-accessibility.md) — POUR smoke checks.
102
+ - [Debugging](11-debugging.md) — screenshots, headed mode, traces.
@@ -0,0 +1,77 @@
1
+ # BBR Smart Waits
2
+
3
+ Webship-js follows a **Behavior-Based Robotics** philosophy: **react to the environment, not the clock.** A test never sleeps for a fixed N seconds. Instead, every wait step returns as soon as the page is at the **edge** of activity — DOM ready, no in-flight network, no pending timers, no live mutations.
4
+
5
+ ## What gets tracked
6
+
7
+ Webship-js installs a small init script in every browser context. It exposes four signals:
8
+
9
+ | Signal | Counter / time | Source |
10
+ | --- | --- | --- |
11
+ | Fetch / XHR in flight | `window.__webshipAjaxCount` | wraps `window.fetch` and `XMLHttpRequest.send` |
12
+ | Pending `setTimeout` | `window.__webshipPendingTimers` | wraps `window.setTimeout` / `clearTimeout` |
13
+ | Last DOM mutation | `window.__webshipLastMutation` | `MutationObserver` on `<html>` |
14
+ | Network idle | (Playwright internal) | `page.waitForLoadState('networkidle')` |
15
+
16
+ `smartSettle(page, budget)` polls all four atomically and returns when:
17
+
18
+ ```
19
+ __webshipAjaxCount === 0
20
+ && __webshipPendingTimers === 0
21
+ && (Date.now() - __webshipLastMutation) >= 250 ms
22
+ ```
23
+
24
+ …or when `budget` elapses, whichever comes first. Each phase is best-effort, so a slow network does not stall the others.
25
+
26
+ ## Step phrasings
27
+
28
+ ```gherkin
29
+ # Bounded smart wait (returns early on idle).
30
+ When I wait 5 seconds
31
+ When I wait max of 5 seconds
32
+ When I wait for 3 seconds for AJAX to finish
33
+
34
+ # Pure edge waits.
35
+ When I wait until the page is loaded
36
+ When I wait for AJAX to finish
37
+ When I wait until pending timers settle
38
+ When I wait until the network is idle
39
+
40
+ # Targeted edge waits.
41
+ When I wait for "#dashboard" to appear
42
+ When I wait for "#loading" to disappear
43
+ When I wait for the text "Welcome" to appear
44
+ When I wait until the URL contains "/dashboard"
45
+ When I wait until the page title contains "Dashboard"
46
+ When I wait until 5 elements match ".product-card"
47
+ When I wait until at least 3 elements match ".item"
48
+
49
+ # Modal-specific.
50
+ When I wait for the modal to appear
51
+ When I wait for the modal to disappear
52
+
53
+ # Body + DOMContentLoaded only (cheaper than full smart settle).
54
+ When I wait until the page is interactive
55
+
56
+ # Polling text assertion — re-runs the matcher until the deadline.
57
+ Then eventually I should see "Done"
58
+ Then eventually I should see "Done" within 10 seconds
59
+ ```
60
+
61
+ ## Auto-settle after actions
62
+
63
+ After every state-changing step (click, press, fill, submit, select, check, uncheck, choose, attach, reload, navigate), webship-js silently runs `smartSettle(page, 1500)`. Tests do not need an explicit wait between an action and its follow-up assertion in the typical case. Disable per-run with `WEBSHIP_AUTO_SETTLE=off`.
64
+
65
+ ## What this kills
66
+
67
+ - **Sleep-driven testing** — `wait 3s` no longer means "sleep three seconds." It means "wait up to three seconds for the page to become quiet."
68
+ - **`networkidle` blind spots** — animations and `setTimeout`-driven UI changes that did not trigger a network request still register on the DOM-mutation and timer-pending signals.
69
+ - **Race-condition flake** — a click followed by an assertion that runs before the DOM finishes updating is now caught by the auto-settle hook.
70
+
71
+ ## When to override
72
+
73
+ You generally don't. A few legitimate cases:
74
+
75
+ - **Real animation** with a known duration (`wait 3 seconds` is fine — smart wait will exit early but the budget is still honored).
76
+ - **Polling backend** that mutates without fetch/XHR (e.g. raw WebSocket pushes). Use a targeted edge wait: `wait for the text "..." to appear`.
77
+ - **Off-by-design UI** that runs an `setInterval` heartbeat. The pending-timer counter only tracks `setTimeout`, so heartbeats do not block `smartSettle`.
@@ -0,0 +1,95 @@
1
+ # Selector Registry
2
+
3
+ Long, brittle CSS strings poison feature files. Webship-js solves this with a **named selector registry**: register a CSS or XPath string once, refer to it by a friendly name in every step.
4
+
5
+ ## Three ways to register
6
+
7
+ ### 1. Inline (one selector at a time)
8
+
9
+ ```gherkin
10
+ Scenario: Add to cart
11
+ Given I am on "/products/101"
12
+ When I add "buy button" selector for ".product__buy button[type=submit]" css selector
13
+ And I click "buy button" by attr
14
+ ```
15
+
16
+ ### 2. Bulk (Gherkin data table)
17
+
18
+ ```gherkin
19
+ Scenario: Layout assertions
20
+ Given I define css selectors:
21
+ | header | header.site |
22
+ | nav | nav[role="navigation"] |
23
+ | main | main |
24
+ | footer | footer |
25
+ Then "main" should be visible
26
+ ```
27
+
28
+ ### 3. JSON file (project-wide preset)
29
+
30
+ ```js
31
+ // cucumber.js
32
+ worldParameters: {
33
+ selectors: {
34
+ filesPath: './tests/selectors/',
35
+ files: ['cms-drupal-cms-gin.json'],
36
+ }
37
+ }
38
+ ```
39
+
40
+ Every scenario starts with a fresh registry. Later entries with the same name override earlier ones (last wins).
41
+
42
+ ## Built-in CMS / framework presets
43
+
44
+ Webship-js ships ready-made selector packs:
45
+
46
+ ```
47
+ tests/selectors/
48
+ ├── _canonical-keys.json # Index of canonical keys + naming rules
49
+ ├── back-end-selectors.json # Generic admin layout
50
+ ├── front-end-selectors.json # Generic public layout
51
+ ├── cms-drupal-cms-gin.json # Drupal CMS (Gin admin theme)
52
+ ├── cms-drupal-core-claro.json # Drupal Core (Claro admin theme)
53
+ ├── cms-generic-admin.json # Pattern-matching generic CMS admin
54
+ ├── cms-ghost-admin.json # Ghost
55
+ ├── cms-joomla-admin.json # Joomla
56
+ ├── cms-magento2-admin.json # Magento 2
57
+ ├── cms-prestashop-admin.json # PrestaShop
58
+ ├── cms-shopify-admin.json # Shopify Polaris admin
59
+ ├── cms-strapi-admin.json # Strapi
60
+ ├── cms-typo3-admin.json # TYPO3
61
+ ├── cms-contentful-admin.json # Contentful
62
+ ├── cms-craft-admin.json # Craft CMS
63
+ ├── cms-wordpress-admin.json # WordPress
64
+ ├── cms-woocommerce-front.json # WooCommerce storefront
65
+ ├── framework-ant-design.json # Ant Design
66
+ ├── framework-bootstrap.json # Bootstrap
67
+ ├── framework-bulma.json # Bulma
68
+ ├── framework-chakra.json # Chakra UI
69
+ ├── framework-foundation.json # Foundation
70
+ ├── framework-material-ui.json # MUI
71
+ ├── framework-shadcn.json # shadcn / Radix
72
+ ├── framework-tailwind.json # Tailwind common patterns
73
+ └── framework-vuetify.json # Vuetify
74
+ ```
75
+
76
+ ## Canonical key set
77
+
78
+ To keep tests portable, every preset exposes the same core names. See `tests/selectors/_canonical-keys.json` for the full list. Highlights:
79
+
80
+ - **Layout** — `main nav`, `main nav item`, `sidebar`, `header bar`, `main content`, `page title`, `breadcrumb`, `user menu`
81
+ - **Modal** — `modal`, `modal overlay`, `modal title`, `modal body`, `modal footer`, `modal close`
82
+ - **Buttons** — `primary button`, `secondary button`, `danger button`, `save button`, `cancel button`, `delete button`
83
+ - **Notices** — `notice success`, `notice error`, `notice warning`, `notice info`, `toast`
84
+ - **Forms** — `form`, `form item`, `form label`, `form input`, `form select`, `form textarea`, `form actions`
85
+ - **Tables** — `data table`, `table header`, `table row`, `table first row`, `table row cell`
86
+ - **Tabs** — `tabs`, `tab item`, `active tab`, `tab content`
87
+ - **Search** — `search input`
88
+ - **Pagination** — `pagination`
89
+
90
+ ## Naming rules
91
+
92
+ - Lowercase words separated by single spaces (`primary button`, not `primary-button`).
93
+ - Modifier first (`active tab`, `danger button`, `first list item`).
94
+ - Synonyms collapse to canonical names (`alert success` / `notification success` / `callout success` → `notice success`).
95
+ - `data table` for HTML tables; `data list` for `ul`/`ol` collections.