webship-js 2.0.10 → 2.0.12

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 (248) hide show
  1. package/.circleci/config.yml +10 -1
  2. package/.drone.yml +7 -7
  3. package/.github/ISSUE_TEMPLATE/issue.md +37 -0
  4. package/.github/PULL_REQUEST_TEMPLATE.md +24 -0
  5. package/.github/workflows/github-actions.yml +101 -4
  6. package/.gitlab-ci.yml +9 -4
  7. package/.harness/webship-js-pipeline.yml +5 -6
  8. package/.semaphore/semaphore.yml +6 -9
  9. package/.teamcity/settings.kts +7 -6
  10. package/.travis.yml +6 -1
  11. package/AGENTS.md +1 -1
  12. package/CLAUDE.md +69 -24
  13. package/Jenkinsfile +5 -3
  14. package/README.md +13 -1
  15. package/azure-pipelines.yml +17 -8
  16. package/bamboo-specs/bamboo.yml +9 -15
  17. package/bin/generate-reports.js +51 -7
  18. package/bin/init-webship.js +127 -23
  19. package/bitbucket-pipelines.yml +5 -1
  20. package/buildspec.yml +6 -7
  21. package/cloudbuild.yaml +28 -12
  22. package/codefresh.yml +6 -6
  23. package/cucumber.js +46 -11
  24. package/docs/00-quick-start.md +38 -7
  25. package/docs/02-bbr-smart-waits.md +21 -10
  26. package/docs/03-selector-registry.md +24 -0
  27. package/docs/04-step-reference.md +53 -27
  28. package/docs/05-web-first-assertions.md +6 -0
  29. package/docs/07-auth-state.md +1 -1
  30. package/docs/08-clock-mocking.md +21 -2
  31. package/docs/09-api-testing.md +40 -2
  32. package/docs/10-accessibility.md +2 -0
  33. package/docs/11-debugging.md +24 -1
  34. package/docs/12-ai-agent-guide.md +8 -1
  35. package/docs/13-faq.md +75 -1
  36. package/docs/14-recipes-cookbook.md +2 -0
  37. package/docs/15-tag-conventions.md +5 -1
  38. package/docs/16-ci-cd.md +161 -124
  39. package/docs/README.md +5 -5
  40. package/docs/advanced-screenshots.md +3 -1
  41. package/docs/api-step-definitions.md +16 -2
  42. package/docs/global-settings.md +70 -18
  43. package/docs/install-webship-js/ddev-webship-js.md +3 -0
  44. package/docs/install-webship-js.md +16 -2
  45. package/docs/step-definitions/then-i-should-see.md +14 -1
  46. package/docs/step-definitions/then-item-checkbox.md +2 -0
  47. package/docs/step-definitions/when-i-fill.md +4 -0
  48. package/docs/step-definitions/when-i-select-option-select-list.md +2 -0
  49. package/examples/a11y-legacy-widget.html +34 -0
  50. package/examples/auth-state.html +42 -0
  51. package/examples/choice-controls.html +29 -0
  52. package/examples/clock.html +33 -0
  53. package/examples/datetime-fields.html +52 -0
  54. package/examples/downloads/webship-archive.zip +0 -0
  55. package/examples/downloads/webship-notes.txt +4 -0
  56. package/examples/downloads/webship-report.csv +4 -0
  57. package/examples/downloads.html +16 -0
  58. package/examples/element-selector-hint.html +16 -0
  59. package/examples/element-viewport.html +42 -0
  60. package/examples/field-states.html +27 -0
  61. package/examples/field-types.html +98 -0
  62. package/examples/fill-in-empty.html +26 -0
  63. package/examples/fill-unreachable.html +27 -0
  64. package/examples/iframe-inner.html +20 -0
  65. package/examples/iframe-nested.html +16 -0
  66. package/examples/iframe-newsletter.html +29 -0
  67. package/examples/iframe-order.html +26 -0
  68. package/examples/iframe-outer.html +15 -0
  69. package/examples/iframe.html +21 -0
  70. package/examples/javascript-errors.html +35 -0
  71. package/examples/links.html +1 -0
  72. package/examples/metatags.html +18 -0
  73. package/examples/mouse-and-pointer.html +83 -0
  74. package/examples/multi-value-fields.html +54 -0
  75. package/examples/native-dialogs.html +8 -0
  76. package/examples/network.html +83 -0
  77. package/examples/registered-names.html +15 -0
  78. package/examples/scroll-horizontal.html +50 -0
  79. package/examples/select-by-label.html +33 -0
  80. package/examples/selectors-position.html +29 -0
  81. package/examples/settle-budget.html +21 -0
  82. package/examples/sorted-tables.html +38 -0
  83. package/examples/storage.html +57 -0
  84. package/examples/text-matching.html +48 -0
  85. package/examples/text-order.html +25 -0
  86. package/examples/touch.html +22 -0
  87. package/examples/viewport-size.html +24 -0
  88. package/examples/viewport-top.html +36 -0
  89. package/examples/wait-conditions.html +69 -0
  90. package/examples/web-first.html +99 -0
  91. package/package.json +24 -2
  92. package/playwright.config.ts +3 -1
  93. package/tests/assets/catalog.xml +19 -0
  94. package/tests/assets/feed-namespaced.xml +13 -0
  95. package/tests/assets/sitemap.xml +14 -0
  96. package/tests/assets/webship-site-expected.yaml +21 -0
  97. package/tests/assets/webship-site.schema.json +46 -0
  98. package/tests/assets/webship-site.yaml +21 -0
  99. package/tests/check-api-launch-url.js +106 -0
  100. package/tests/check-assets.js +103 -0
  101. package/tests/check-attachments.js +105 -0
  102. package/tests/check-breakpoints.js +117 -0
  103. package/tests/check-clock.js +143 -0
  104. package/tests/check-config.js +90 -0
  105. package/tests/check-context.js +215 -0
  106. package/tests/check-dry-run.js +104 -0
  107. package/tests/check-examples.js +241 -0
  108. package/tests/check-exit-report.js +141 -0
  109. package/tests/check-javascript-errors.js +105 -0
  110. package/tests/check-must-fail.js +85 -0
  111. package/tests/check-paths.js +82 -0
  112. package/tests/check-report.js +119 -0
  113. package/tests/check-scaffold.js +246 -0
  114. package/tests/check-screenshots.js +117 -0
  115. package/tests/check-settle-verbs.js +137 -0
  116. package/tests/check-time-limit.js +104 -0
  117. package/tests/check-video.js +156 -0
  118. package/tests/check-world.js +167 -0
  119. package/tests/features/a11y.feature +18 -0
  120. package/tests/features/api-base-url.feature +25 -0
  121. package/tests/features/api-form-data.feature +18 -0
  122. package/tests/features/api-json-paths.feature +24 -0
  123. package/tests/features/api-response-contains.feature +21 -0
  124. package/tests/features/api-response-header-presence.feature +17 -0
  125. package/tests/features/api-response-header.feature +17 -0
  126. package/tests/features/api-saved-placeholders.feature +37 -0
  127. package/tests/features/api-step-definitions-individual.feature +1 -1
  128. package/tests/features/api-tables.feature +40 -0
  129. package/tests/features/auth-state.feature +32 -0
  130. package/tests/features/breakpoints.feature +25 -0
  131. package/tests/features/choice-controls.feature +35 -0
  132. package/tests/features/clock.feature +27 -0
  133. package/tests/features/complete-api-testing-examples.feature +1 -1
  134. package/tests/features/cookie.feature +9 -0
  135. package/tests/features/datetime-field-lookup.feature +29 -0
  136. package/tests/features/dialog.feature +27 -0
  137. package/tests/features/element-selector-hint.feature +14 -0
  138. package/tests/features/element.feature +47 -0
  139. package/tests/features/field-state.feature +21 -0
  140. package/tests/features/field.feature +104 -0
  141. package/tests/features/file-download.feature +64 -0
  142. package/tests/features/fill-in-empty-value.feature +41 -0
  143. package/tests/features/fill-reachable.feature +13 -0
  144. package/tests/features/iframe-nested.feature +43 -0
  145. package/tests/features/iframe.feature +83 -0
  146. package/tests/features/javascript-tolerated-errors.feature +20 -0
  147. package/tests/features/javascript.feature +47 -0
  148. package/tests/features/link.feature +11 -0
  149. package/tests/features/metatag.feature +38 -0
  150. package/tests/features/modal-open.feature +13 -0
  151. package/tests/features/mouse-and-pointer.feature +86 -0
  152. package/tests/features/multi-value-field-lookup.feature +30 -0
  153. package/tests/features/network-mocking.feature +80 -0
  154. package/tests/features/registered-names.feature +14 -0
  155. package/tests/features/responsive.feature +27 -0
  156. package/tests/features/scroll-horizontal.feature +55 -0
  157. package/tests/features/select-by-label.feature +31 -0
  158. package/tests/features/selector-files.feature +14 -0
  159. package/tests/features/selectors-position.feature +41 -0
  160. package/tests/features/selectors-table-header.feature +35 -0
  161. package/tests/features/settle-budget.feature +11 -0
  162. package/tests/features/sorted-tables.feature +19 -0
  163. package/tests/features/storage-quoted-values.feature +26 -0
  164. package/tests/features/storage.feature +98 -0
  165. package/tests/features/test--then--i-see-locator.feature +13 -0
  166. package/tests/features/test--then--i-should--see-text-in-element.feature +9 -1
  167. package/tests/features/test--then--the-field-should-contain-value.feature +8 -0
  168. package/tests/features/text-matching.feature +38 -0
  169. package/tests/features/text-order.feature +14 -0
  170. package/tests/features/touch.feature +21 -0
  171. package/tests/features/video.feature +1 -0
  172. package/tests/features/viewport-top.feature +13 -0
  173. package/tests/features/wait.feature +89 -0
  174. package/tests/features/web-first.feature +100 -0
  175. package/tests/features/xml-namespaces.feature +34 -0
  176. package/tests/features/xml.feature +96 -0
  177. package/tests/features/yaml.feature +75 -0
  178. package/tests/must-fail/api-json-paths.feature +21 -0
  179. package/tests/must-fail/api-response-contains.feature +23 -0
  180. package/tests/must-fail/api-response-header-presence.feature +17 -0
  181. package/tests/must-fail/api-response-header.feature +21 -0
  182. package/tests/must-fail/api-without-base-url.feature +11 -0
  183. package/tests/must-fail/assertions.feature +96 -0
  184. package/tests/must-fail/breakpoints.feature +15 -0
  185. package/tests/must-fail/choice-controls.feature +25 -0
  186. package/tests/must-fail/clock.feature +11 -0
  187. package/tests/must-fail/datetime-field.feature +10 -0
  188. package/tests/must-fail/element-selector-hint.feature +17 -0
  189. package/tests/must-fail/field-state.feature +20 -0
  190. package/tests/must-fail/fill-field.feature +30 -0
  191. package/tests/must-fail/iframe-text.feature +17 -0
  192. package/tests/must-fail/modal-open.feature +26 -0
  193. package/tests/must-fail/multi-value-field.feature +18 -0
  194. package/tests/must-fail/registered-names.feature +25 -0
  195. package/tests/must-fail/select-list.feature +15 -0
  196. package/tests/must-fail/selector-files.feature +10 -0
  197. package/tests/must-fail/sorted-tables.feature +20 -0
  198. package/tests/must-fail/storage-before-a-page.feature +13 -0
  199. package/tests/must-fail/text-matching.feature +16 -0
  200. package/tests/must-fail/text-order.feature +15 -0
  201. package/tests/must-fail/viewport-top.feature +20 -0
  202. package/tests/must-fail/waits.feature +51 -0
  203. package/tests/must-fail/yaml-numbers.feature +48 -0
  204. package/tests/reports/README.md +2 -2
  205. package/tests/step-definitions/a11y.steps.js +36 -23
  206. package/tests/step-definitions/action.steps.js +22 -8
  207. package/tests/step-definitions/api.steps.js +349 -67
  208. package/tests/step-definitions/assertion.steps.js +327 -63
  209. package/tests/step-definitions/auth.steps.js +15 -18
  210. package/tests/step-definitions/clock.steps.js +22 -0
  211. package/tests/step-definitions/debug.steps.js +8 -0
  212. package/tests/step-definitions/dialog.steps.js +9 -2
  213. package/tests/step-definitions/element.steps.js +135 -18
  214. package/tests/step-definitions/field.steps.js +523 -80
  215. package/tests/step-definitions/file-download.steps.js +74 -10
  216. package/tests/step-definitions/form.steps.js +76 -29
  217. package/tests/step-definitions/iframe.steps.js +89 -29
  218. package/tests/step-definitions/input.steps.js +26 -7
  219. package/tests/step-definitions/javascript.steps.js +64 -22
  220. package/tests/step-definitions/modal.steps.js +79 -13
  221. package/tests/step-definitions/navigation.steps.js +14 -0
  222. package/tests/step-definitions/network.steps.js +15 -5
  223. package/tests/step-definitions/response.steps.js +6 -4
  224. package/tests/step-definitions/responsive.steps.js +26 -33
  225. package/tests/step-definitions/screenshot.steps.js +26 -9
  226. package/tests/step-definitions/scroll.steps.js +20 -0
  227. package/tests/step-definitions/selectors.steps.js +104 -51
  228. package/tests/step-definitions/storage.steps.js +41 -16
  229. package/tests/step-definitions/table.steps.js +81 -6
  230. package/tests/step-definitions/video.steps.js +52 -55
  231. package/tests/step-definitions/wait.steps.js +209 -54
  232. package/tests/step-definitions/web-first.steps.js +69 -35
  233. package/tests/step-definitions/webship.js +807 -128
  234. package/tests/step-definitions/xml.steps.js +124 -28
  235. package/tests/step-definitions/yaml.steps.js +90 -46
  236. package/.scratch/commit.txt +0 -14
  237. package/.scratch/docs.py +0 -42
  238. package/.scratch/echo-server.js +0 -8
  239. package/.scratch/echo.js +0 -35
  240. package/.scratch/echo.pid +0 -1
  241. package/.scratch/features/cookies.feature +0 -22
  242. package/.scratch/http.pid +0 -1
  243. package/.scratch/https.pid +0 -1
  244. package/.scratch/issue.md +0 -49
  245. package/.scratch/one.js +0 -2
  246. package/.scratch/one.json +0 -280
  247. package/.scratch/patch.py +0 -163
  248. package/.scratch/pr.md +0 -30
@@ -1,8 +1,8 @@
1
1
  # Azure DevOps Pipelines for webship-js.
2
2
  #
3
- # Runs the full BDD suite on a Microsoft-hosted Ubuntu agent. Free tier for
4
- # public projects: 10 parallel jobs, unlimited minutes. Free tier for private
5
- # projects: 1 job, 1,800 minutes / month.
3
+ # Runs the full BDD suite on a Microsoft-hosted Ubuntu agent. For the free
4
+ # parallel jobs and minutes of public and private projects, see the Azure
5
+ # DevOps pricing and parallel-jobs pages: they change over time.
6
6
  #
7
7
  # Setup:
8
8
  # 1. dev.azure.com → sign in → create Organization → create Project.
@@ -35,8 +35,8 @@ variables:
35
35
  steps:
36
36
  - task: NodeTool@0
37
37
  inputs:
38
- versionSpec: '20.x'
39
- displayName: 'Install Node 20'
38
+ versionSpec: '24.x'
39
+ displayName: 'Install Node 24'
40
40
 
41
41
  - task: Cache@2
42
42
  inputs:
@@ -75,8 +75,17 @@ steps:
75
75
  displayName: 'Publish HTML / PDF / JSON report'
76
76
 
77
77
  - task: PublishBuildArtifacts@1
78
- condition: failed()
78
+ condition: always()
79
+ continueOnError: true
79
80
  inputs:
80
81
  pathToPublish: 'screenshots'
81
- artifactName: 'failure-screenshots'
82
- displayName: 'Publish failure screenshots'
82
+ artifactName: 'screenshots'
83
+ displayName: 'Publish screenshots'
84
+
85
+ - task: PublishBuildArtifacts@1
86
+ condition: always()
87
+ continueOnError: true
88
+ inputs:
89
+ pathToPublish: 'videos'
90
+ artifactName: 'videos'
91
+ displayName: 'Publish videos'
@@ -1,9 +1,7 @@
1
1
  # Atlassian Bamboo YAML Specs for webship-js.
2
2
  #
3
- # Runs the full BDD suite on a Bamboo Data Center self-hosted instance.
4
- # (Bamboo Cloud was retired by Atlassian on 2024-02-15; the YAML below
5
- # targets Bamboo Data Center 9.x — which is the only flavour still
6
- # supported.)
3
+ # Runs the full BDD suite on a self-hosted Bamboo Data Center instance:
4
+ # Atlassian offers Bamboo as Data Center only, there is no hosted Bamboo.
7
5
  #
8
6
  # Setup (full walkthrough in docs/16-ci-cd.md → "Bamboo Data Center"):
9
7
  # 1. Bamboo admin → Linked repositories → add the GitHub repo.
@@ -30,7 +28,7 @@ stages:
30
28
  Cucumber:
31
29
  key: CUC
32
30
  docker:
33
- image: mcr.microsoft.com/playwright:v1.58.2-jammy
31
+ image: mcr.microsoft.com/playwright:v1.65.1-noble
34
32
  docker-run-arguments:
35
33
  - --user=root:root
36
34
  - --network=host
@@ -61,22 +59,18 @@ Cucumber:
61
59
  scripts:
62
60
  - npm test
63
61
  artifacts:
64
- - name: cucumber-report-html
65
- pattern: tests/reports/cucumber_report.html
66
- shared: true
67
- required: false
68
- - name: cucumber-report-pdf
69
- pattern: tests/reports/cucumber_report.pdf
70
- shared: true
71
- required: false
72
- - name: cucumber-report-json
73
- pattern: tests/reports/cucumber_report.json
62
+ - name: cucumber-report
63
+ pattern: tests/reports/**
74
64
  shared: true
75
65
  required: false
76
66
  - name: screenshots
77
67
  pattern: screenshots/**
78
68
  shared: true
79
69
  required: false
70
+ - name: videos
71
+ pattern: videos/**
72
+ shared: true
73
+ required: false
80
74
  requirements:
81
75
  - os: Linux
82
76
 
@@ -133,12 +133,14 @@ function printHelp() {
133
133
  ' --ignore-bad-json Do not fail on malformed JSON entries',
134
134
  '',
135
135
  'Metadata:',
136
- ' --app-version <s> App Version (env WEBSHIP_REPORT_APP_VERSION)',
136
+ ' --app-version <s> App Version (env WEBSHIP_REPORT_APP_VERSION;',
137
+ ' default: the version of the project\'s package.json)',
137
138
  ' --env <s> Test Environment (env WEBSHIP_REPORT_ENV)',
138
139
  ' --browser <s> Browser (env BROWSER)',
139
140
  ' --platform <s> Platform (default: process.platform)',
140
141
  ' --parallel <s> Parallel (default: Scenarios)',
141
- ' --executed <s> Executed (env WEBSHIP_REPORT_EXECUTED)',
142
+ ' --executed <s> Executed (env WEBSHIP_REPORT_EXECUTED;',
143
+ ' default: Remote when CI is set, else Local)',
142
144
  ' --metadata key=value Arbitrary key/value (repeatable)',
143
145
  '',
144
146
  ' -h, --help Show this help',
@@ -294,11 +296,15 @@ async function run(argv) {
294
296
  process.exit(1);
295
297
  }
296
298
 
299
+ // The version of the project under test, not a fixed number: asked for,
300
+ // else read from the package.json of the project, else left out.
301
+ const appVersion =
302
+ args.metadata['App Version'] ||
303
+ process.env.WEBSHIP_REPORT_APP_VERSION ||
304
+ projectVersion(cwd);
305
+
297
306
  const metadata = {
298
- 'App Version':
299
- args.metadata['App Version'] ||
300
- process.env.WEBSHIP_REPORT_APP_VERSION ||
301
- '2.0.0',
307
+ ...(appVersion ? { 'App Version': appVersion } : {}),
302
308
  'Test Environment':
303
309
  args.metadata['Test Environment'] ||
304
310
  process.env.WEBSHIP_REPORT_ENV ||
@@ -311,7 +317,7 @@ async function run(argv) {
311
317
  Executed:
312
318
  args.metadata['Executed'] ||
313
319
  process.env.WEBSHIP_REPORT_EXECUTED ||
314
- 'Remote',
320
+ (process.env.CI ? 'Remote' : 'Local'),
315
321
  };
316
322
  for (const [k, v] of Object.entries(args.metadata)) {
317
323
  metadata[k] = v;
@@ -342,6 +348,7 @@ async function run(argv) {
342
348
 
343
349
  if (wantHtml || needsHtmlForExport) {
344
350
  reporter.generate(options);
351
+ removeThirdPartyIcon(output);
345
352
  console.log(`[webship-js] HTML report → ${output}`);
346
353
  }
347
354
 
@@ -353,6 +360,43 @@ async function run(argv) {
353
360
 
354
361
  }
355
362
 
363
+ /**
364
+ * The `version` of the package.json of the project the report is made for,
365
+ * or an empty string when there is none.
366
+ *
367
+ * @param {string} cwd - Folder of the project.
368
+ * @returns {string}
369
+ */
370
+ function projectVersion(cwd) {
371
+ try {
372
+ const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'));
373
+ return typeof pkg.version === 'string' ? pkg.version : '';
374
+ } catch {
375
+ return '';
376
+ }
377
+ }
378
+
379
+ /**
380
+ * The report template links the favicon of a third-party site. A report of
381
+ * the project must not show another company's icon, nor fetch anything from
382
+ * its site: the link is replaced by an empty icon.
383
+ *
384
+ * @param {string} htmlPath - Generated report.
385
+ */
386
+ function removeThirdPartyIcon(htmlPath) {
387
+ let html;
388
+ try {
389
+ html = fs.readFileSync(htmlPath, 'utf8');
390
+ } catch {
391
+ return;
392
+ }
393
+ const cleaned = html.replace(
394
+ /<link\b[^>]*\brel=["']?(?:shortcut )?icon["']?[^>]*>/gi,
395
+ '<link rel="icon" href="data:,">'
396
+ );
397
+ if (cleaned !== html) fs.writeFileSync(htmlPath, cleaned, 'utf8');
398
+ }
399
+
356
400
  if (require.main === module) {
357
401
  Promise.resolve(run(process.argv.slice(2))).catch(err => {
358
402
  console.error(`[webship-js] ${err.message || err}`);
@@ -8,7 +8,32 @@ const { spawnSync } = require('child_process');
8
8
 
9
9
  const packagePath = path.join(__dirname, '..');
10
10
 
11
- const CUCUMBER_JS = `module.exports = {
11
+ const CUCUMBER_JS = `// A feature file, a scenario (file:line), a folder or a rerun file named on
12
+ // the command line of cucumber-js runs alone (cucumber-js 12 would add it to
13
+ // the paths below): \`npx cucumber-js tests/features/login.feature\`.
14
+ const OPTIONS_WITH_A_VALUE = new Set([
15
+ '-c', '--config', '-f', '--format', '--format-options', '--i18n-keywords',
16
+ '-i', '--import', '-l', '--loader', '--language', '--name', '--order',
17
+ '-p', '--profile', '--parallel', '--plugin', '--plugin-options',
18
+ '-r', '--require', '--require-module', '--retry', '--retry-tag-filter',
19
+ '--shard', '-t', '--tags', '--world-parameters',
20
+ ]);
21
+
22
+ function commandLinePaths() {
23
+ if (!/cucumber(-js|\\.js)?$/.test(String(process.argv[1] || ''))) return [];
24
+ const args = process.argv.slice(2);
25
+ const paths = [];
26
+ for (let i = 0; i < args.length; i += 1) {
27
+ if (args[i].startsWith('-')) {
28
+ if (OPTIONS_WITH_A_VALUE.has(args[i])) i += 1;
29
+ } else {
30
+ paths.push(args[i]);
31
+ }
32
+ }
33
+ return paths;
34
+ }
35
+
36
+ module.exports = {
12
37
  default: {
13
38
  timeout: 30000, // Overridden by webship-js's setDefaultTimeout (45s); raise it with WEBSHIP_STEP_TIMEOUT.
14
39
  requireModule: ['tsx/cjs'],
@@ -16,14 +41,13 @@ const CUCUMBER_JS = `module.exports = {
16
41
  'node_modules/webship-js/tests/step-definitions/**/*.js', // Webship-js core step definitions (auto HTML report on exit; disable: WEBSHIP_REPORT_DISABLE=1).
17
42
  'tests/step-definitions/**/*.js', // Your custom step definitions.
18
43
  ],
19
- // FEATURES=tests/features/a.feature,tests/features/b.feature runs a subset.
20
- paths: process.env.FEATURES ? process.env.FEATURES.split(',') : ['tests/features/**/*.feature'],
44
+ // FEATURES=tests/features/a.feature,tests/features/b.feature runs a subset too.
45
+ paths: process.env.FEATURES ? process.env.FEATURES.split(',') : (commandLinePaths().length ? [] : ['tests/features/**/*.feature']),
21
46
  format: [
22
47
  '@cucumber/pretty-formatter',
23
48
  'json:tests/reports/cucumber_report.json',
24
49
  ],
25
50
  formatOptions: {
26
- colorsEnabled: true,
27
51
  theme: {
28
52
  'feature keyword': ['bold', 'blue'],
29
53
  'feature name': ['blue', 'underline'],
@@ -48,7 +72,10 @@ const CUCUMBER_JS = `module.exports = {
48
72
  xpath: {},
49
73
  filesPath: './tests/selectors/',
50
74
  files: [],
51
- offset: 60,
75
+ // Named viewport sizes for the viewing-the-site and set-the-viewport
76
+ // steps and the @mobile / @desktop tags (built in: xs..xxxl, mobile,
77
+ // tablet, desktop). Without a desktop here, @desktop opens at the
78
+ // breakpoint marked default: true.
52
79
  breakpoints: {
53
80
  xs: { width: 375, height: 667 },
54
81
  sm: { width: 576, height: 800 },
@@ -102,7 +129,9 @@ const config: PlaywrightConfig = {
102
129
  browser,
103
130
  launchOptions: {
104
131
  headless: process.env.HEADLESS !== 'false',
105
- // SLOW_MO env var: 0 in CI for speed, 800ms when watching headed runs.
132
+ // Pause before every browser action, in ms: 300 by default, 800 with
133
+ // HEADLESS=false so a headed run can be watched. SLOW_MO wins over both:
134
+ // SLOW_MO=0 for full speed (npm run test:fast), in CI too.
106
135
  slowMo: parseInt(process.env.SLOW_MO || (process.env.HEADLESS === 'false' ? '800' : '300'), 10),
107
136
  args: browser === 'chromium' ? chromiumArgs : [],
108
137
  },
@@ -125,14 +154,17 @@ const TSCONFIG_JSON = {
125
154
  },
126
155
  };
127
156
 
157
+ // The starter feature passes on any site that answers on the launch URL
158
+ // (LAUNCH_URL, default http://localhost:8080): it asserts nothing about the
159
+ // content of a site the scaffold cannot know.
128
160
  const FEATURE_SAMPLE = `Feature: Check the home page
129
- As a nonymouse user
161
+ As an anonymous user
130
162
  I want to be able to visit the home page
131
163
  So that I know that the site is working
132
164
 
133
165
  Scenario: Check homepage
134
166
  Given I am on the homepage
135
- Then I should see "Love to help in speeding up the work of having Automated Functional Acceptance Testing for products to ship websites in a swift way."
167
+ Then I should be on the homepage
136
168
  `;
137
169
 
138
170
  const CUSTOM_STEP_JS = `const { Given, When, Then } = require('@cucumber/cucumber');
@@ -156,9 +188,24 @@ const TEST_SCRIPTS = {
156
188
  'test:chromium': 'BROWSER=chromium cucumber-js --config cucumber.js',
157
189
  'test:firefox': 'BROWSER=firefox cucumber-js --config cucumber.js',
158
190
  'test:webkit': 'BROWSER=webkit cucumber-js --config cucumber.js',
191
+ 'test:headed': 'HEADLESS=false cucumber-js --config cucumber.js',
192
+ 'test:fast': 'SLOW_MO=0 cucumber-js --config cucumber.js',
159
193
  'generate-reports': 'generate-reports',
160
194
  };
161
195
 
196
+ // The `test` script `npm init` writes. It is a placeholder, not a choice of
197
+ // the project, so the scaffold replaces it.
198
+ const NPM_PLACEHOLDER_TEST = /^echo "Error: no test specified" && exit 1$/;
199
+
200
+ // A `test` script that runs Nightwatch is the one webship-js 1.x gave a
201
+ // project. webship-js 2.x runs on cucumber-js and Playwright and brings no
202
+ // Nightwatch, so the scaffold replaces it and keeps it as `test:nightwatch`.
203
+ const NIGHTWATCH_TEST = /(^|[\s;&|/])nightwatch(\s|$)/i;
204
+
205
+ // Files of the scaffold that hold the project's own code once written: never
206
+ // overwritten, not even with --force.
207
+ const PROJECT_FILES = new Set(['tests/step-definitions/custom.js']);
208
+
162
209
  const DEFAULT_PKG = {
163
210
  name: 'project-name',
164
211
  version: '2.0.0',
@@ -194,8 +241,9 @@ function printHelp() {
194
241
  'Idempotent — safe to run multiple times.',
195
242
  '',
196
243
  'Options:',
197
- ' -f, --force Overwrite existing files',
198
- ' --skip-browsers Skip `playwright install chromium`',
244
+ ' -f, --force Overwrite the files and scripts of the scaffold',
245
+ ' (never tests/step-definitions/custom.js)',
246
+ ' --skip-browsers Skip `npx playwright install chromium`',
199
247
  ' --cwd <dir> Target directory (default: $INIT_CWD or cwd)',
200
248
  ' -h, --help Show this help',
201
249
  '',
@@ -230,7 +278,8 @@ function writeTextAssets(projectPath, opts) {
230
278
  const results = [];
231
279
  for (const [rel, content] of Object.entries(TEXT_ASSETS)) {
232
280
  const dest = path.join(projectPath, rel);
233
- const written = writeFileIfMissing(dest, content, opts);
281
+ const force = opts.force && !PROJECT_FILES.has(rel);
282
+ const written = writeFileIfMissing(dest, content, { force });
234
283
  results.push({ file: rel, written });
235
284
  }
236
285
  return results;
@@ -255,8 +304,16 @@ function ensurePackageJson(projectPath, opts) {
255
304
  }
256
305
 
257
306
  pkg.scripts = pkg.scripts || {};
307
+ let replacedNightwatch = null;
258
308
  for (const [name, cmd] of Object.entries(TEST_SCRIPTS)) {
259
- if (opts.force || !pkg.scripts[name]) {
309
+ const current = String(pkg.scripts[name] || '').trim();
310
+ const placeholder = name === 'test' && NPM_PLACEHOLDER_TEST.test(current);
311
+ const nightwatch = name === 'test' && NIGHTWATCH_TEST.test(current);
312
+ if (nightwatch && current !== cmd) {
313
+ if (!pkg.scripts['test:nightwatch']) pkg.scripts['test:nightwatch'] = pkg.scripts.test;
314
+ replacedNightwatch = pkg.scripts.test;
315
+ }
316
+ if (opts.force || !pkg.scripts[name] || placeholder || nightwatch) {
260
317
  pkg.scripts[name] = cmd;
261
318
  }
262
319
  }
@@ -267,16 +324,24 @@ function ensurePackageJson(projectPath, opts) {
267
324
  }
268
325
 
269
326
  fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf8');
270
- return { created: !existed };
327
+ return { created: !existed, replacedNightwatch };
328
+ }
329
+
330
+ // The browser itself goes into the Playwright cache of the user: no special
331
+ // rights are needed. The system libraries it runs on need root, so they are
332
+ // installed with it only when the scaffold already runs as root (a container,
333
+ // a CI job); otherwise the user is told how to add them.
334
+ function isRoot() {
335
+ return typeof process.getuid === 'function' && process.getuid() === 0;
271
336
  }
272
337
 
273
338
  function installBrowsers(projectPath) {
274
- console.log('\n [webship-js] Installing Playwright browsers...\n');
275
- const res = spawnSync(
276
- 'npx',
277
- ['playwright', 'install', '--with-deps', 'chromium'],
278
- { cwd: projectPath, stdio: 'inherit', shell: true }
279
- );
339
+ console.log('\n [webship-js] Installing the Playwright browser (Chromium)...\n');
340
+ const win = process.platform === 'win32';
341
+ const args = ['playwright', 'install'].concat(isRoot() ? ['--with-deps'] : [], ['chromium']);
342
+ const res = win
343
+ ? spawnSync(`npx ${args.join(' ')}`, { cwd: projectPath, stdio: 'inherit', shell: true })
344
+ : spawnSync('npx', args, { cwd: projectPath, stdio: 'inherit' });
280
345
  return res.status === 0;
281
346
  }
282
347
 
@@ -310,16 +375,55 @@ function run(argv) {
310
375
  const pkgResult = ensurePackageJson(projectPath, opts);
311
376
 
312
377
  for (const r of assetResults) {
313
- console.log(` [${r.written ? 'wrote ' : 'kept '}] ${r.file}`);
378
+ const note = !r.written && opts.force && PROJECT_FILES.has(r.file)
379
+ ? ' (the steps of the project: --force never overwrites it)'
380
+ : '';
381
+ console.log(` [${r.written ? 'wrote ' : 'kept '}] ${r.file}${note}`);
314
382
  }
315
383
  console.log(` [${tsconfigWritten ? 'wrote ' : 'kept '}] tsconfig.json`);
316
384
  console.log(
317
385
  ` [${pkgResult.created ? 'wrote ' : 'merged'}] package.json`
318
386
  );
387
+ if (pkgResult.replacedNightwatch) {
388
+ console.log(
389
+ [
390
+ '',
391
+ ' [webship-js] "npm test" ran Nightwatch (a webship-js 1.x project). It now runs',
392
+ ' cucumber-js: cucumber-js --config cucumber.js',
393
+ ' The old command is kept as "npm run test:nightwatch".',
394
+ ].join('\n')
395
+ );
396
+ }
319
397
 
320
- if (!opts.skipBrowsers) installBrowsers(projectPath);
321
-
322
- console.log('\n [webship-js] Setup complete!\n');
398
+ const browsersInstalled = opts.skipBrowsers || installBrowsers(projectPath);
399
+
400
+ if (!browsersInstalled) {
401
+ console.log(
402
+ [
403
+ '',
404
+ ' [webship-js] The project files are in place, but the browser was NOT installed.',
405
+ ' Install it before the first run:',
406
+ '',
407
+ ' npx playwright install chromium',
408
+ '',
409
+ ].join('\n')
410
+ );
411
+ } else {
412
+ console.log('\n [webship-js] Setup complete!');
413
+ }
414
+ console.log(
415
+ [
416
+ '',
417
+ ' Run the starter feature against your site:',
418
+ '',
419
+ ' LAUNCH_URL=https://your-site.example npm test',
420
+ '',
421
+ ' If the browser does not start for a missing system library (Linux):',
422
+ '',
423
+ ' sudo npx playwright install-deps chromium',
424
+ '',
425
+ ].join('\n')
426
+ );
323
427
  }
324
428
 
325
429
  if (require.main === module) {
@@ -1,4 +1,4 @@
1
- image: node:20
1
+ image: node:24
2
2
 
3
3
  pipelines:
4
4
  default:
@@ -12,3 +12,7 @@ pipelines:
12
12
  - npm start &
13
13
  - sleep 3
14
14
  - FORCE_COLOR=1 npm test
15
+ artifacts:
16
+ - tests/reports/**
17
+ - screenshots/**
18
+ - videos/**
package/buildspec.yml CHANGED
@@ -2,11 +2,11 @@
2
2
  #
3
3
  # Runs the full BDD suite on AWS-managed compute. Pair with CodePipeline
4
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.
5
+ # GitHub webhook. For the free tier and the prices, see the CodeBuild pricing
6
+ # page: they change over time.
7
7
  #
8
8
  # Suggested CodeBuild project settings:
9
- # Environment image: aws/codebuild/standard:7.0
9
+ # Environment image: aws/codebuild/standard:8.0 (Ubuntu 24.04, Node 22/24/26)
10
10
  # Compute: general1.small (3 GB RAM, 2 vCPU) — fits the suite
11
11
  # Service role: needs S3 PutObject for the artifacts bucket
12
12
  #
@@ -23,7 +23,7 @@ env:
23
23
  phases:
24
24
  install:
25
25
  runtime-versions:
26
- nodejs: 20
26
+ nodejs: 24
27
27
  commands:
28
28
  - node --version
29
29
  - npm --version
@@ -49,8 +49,7 @@ cache:
49
49
  artifacts:
50
50
  name: webship-js-report-$(date +%Y%m%d-%H%M%S)
51
51
  files:
52
- - tests/reports/cucumber_report.html
53
- - tests/reports/cucumber_report.pdf
54
- - tests/reports/cucumber_report.json
52
+ - tests/reports/**/*
55
53
  - screenshots/**/*
54
+ - videos/**/*
56
55
  discard-paths: no
package/cloudbuild.yaml CHANGED
@@ -1,9 +1,10 @@
1
1
  # Google Cloud Build config for webship-js.
2
2
  #
3
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.
4
+ # managed builder pool. For the free tier and the prices, see the Cloud Build
5
+ # pricing page: they change over time. The image is the one of the Playwright
6
+ # the install brings; `npx playwright install` gets the browser of a newer
7
+ # Playwright release when there is one.
7
8
  #
8
9
  # Setup (full walkthrough in docs/16-ci-cd.md → "Google Cloud Build"):
9
10
  # 1. console.cloud.google.com → create project → enable Cloud Build API.
@@ -22,7 +23,7 @@ timeout: '1800s'
22
23
 
23
24
  steps:
24
25
  - id: install-and-test
25
- name: 'mcr.microsoft.com/playwright:v1.58.2-jammy'
26
+ name: 'mcr.microsoft.com/playwright:v1.65.1-noble'
26
27
  entrypoint: 'bash'
27
28
  env:
28
29
  - 'FORCE_COLOR=1'
@@ -38,12 +39,27 @@ steps:
38
39
  nohup npm start > /tmp/srv.log 2>&1 &
39
40
  sleep 3
40
41
  curl -sf http://localhost:8080/ > /dev/null
41
- npm test
42
+ # A failing suite must not stop the build before the report is kept:
43
+ # the result is checked by the last step.
44
+ npm test || touch /workspace/.tests-failed
42
45
 
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'
46
+ # Cloud Build uploads the files of `artifacts:` only when every step
47
+ # succeeds, so the report, the screenshots and the videos are copied here,
48
+ # passed or failed.
49
+ - id: keep-report
50
+ name: 'gcr.io/cloud-builders/gsutil'
51
+ entrypoint: 'bash'
52
+ args:
53
+ - '-c'
54
+ - |
55
+ for dir in tests/reports screenshots videos; do
56
+ if [ -d "$$dir" ]; then gsutil -m cp -r "$$dir" "gs://${_ARTIFACT_BUCKET}/$BUILD_ID/"; fi
57
+ done
58
+
59
+ - id: test-result
60
+ name: 'gcr.io/cloud-builders/gsutil'
61
+ entrypoint: 'bash'
62
+ args:
63
+ - '-c'
64
+ - |
65
+ if [ -f /workspace/.tests-failed ]; then echo "The suite failed: see the report in gs://${_ARTIFACT_BUCKET}/$BUILD_ID/"; exit 1; fi
package/codefresh.yml CHANGED
@@ -1,9 +1,8 @@
1
1
  # Codefresh Classic pipeline for webship-js.
2
2
  #
3
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.
4
+ # (used here) reads `codefresh.yml` from the repository. For the plans and
5
+ # their build capacity, see the Codefresh pricing page: they change over time.
7
6
  #
8
7
  # Setup (full walkthrough in docs/16-ci-cd.md → "Codefresh"):
9
8
  # 1. codefresh.io → sign up with GitHub → create pipeline → "Inline YAML
@@ -34,7 +33,7 @@ steps:
34
33
  install_dependencies:
35
34
  title: "Install npm dependencies + Playwright browsers"
36
35
  type: freestyle
37
- image: mcr.microsoft.com/playwright:v1.58.2-jammy
36
+ image: mcr.microsoft.com/playwright:v1.65.1-noble
38
37
  working_directory: ${{main_clone}}
39
38
  environment:
40
39
  - FORCE_COLOR=1
@@ -48,7 +47,7 @@ steps:
48
47
  test_suite:
49
48
  title: "Run cucumber-js"
50
49
  type: freestyle
51
- image: mcr.microsoft.com/playwright:v1.58.2-jammy
50
+ image: mcr.microsoft.com/playwright:v1.65.1-noble
52
51
  working_directory: ${{main_clone}}
53
52
  environment:
54
53
  - FORCE_COLOR=1
@@ -72,6 +71,7 @@ steps:
72
71
  failureToo: "true"
73
72
  commands:
74
73
  - 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
74
+ - cp -a tests/reports/. /codefresh/volume/cucumber-report/ 2>/dev/null || true
76
75
  - cp -a screenshots /codefresh/volume/cucumber-report/screenshots 2>/dev/null || true
76
+ - cp -a videos /codefresh/volume/cucumber-report/videos 2>/dev/null || true
77
77
  stage: test