webship-js 2.0.11 → 2.0.13

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 (175) hide show
  1. package/.circleci/config.yml +10 -1
  2. package/.drone.yml +7 -7
  3. package/.github/workflows/github-actions.yml +48 -0
  4. package/.gitlab-ci.yml +9 -4
  5. package/.harness/webship-js-pipeline.yml +5 -6
  6. package/.semaphore/semaphore.yml +6 -9
  7. package/.teamcity/settings.kts +7 -6
  8. package/.travis.yml +6 -1
  9. package/AGENTS.md +1 -1
  10. package/CLAUDE.md +65 -23
  11. package/Jenkinsfile +5 -3
  12. package/azure-pipelines.yml +17 -8
  13. package/bamboo-specs/bamboo.yml +9 -15
  14. package/bin/init-webship.js +53 -10
  15. package/bitbucket-pipelines.yml +5 -1
  16. package/buildspec.yml +6 -7
  17. package/cloudbuild.yaml +28 -12
  18. package/codefresh.yml +6 -6
  19. package/cucumber.js +17 -10
  20. package/docs/00-quick-start.md +8 -0
  21. package/docs/02-bbr-smart-waits.md +15 -10
  22. package/docs/03-selector-registry.md +24 -0
  23. package/docs/04-step-reference.md +51 -25
  24. package/docs/05-web-first-assertions.md +6 -0
  25. package/docs/07-auth-state.md +1 -1
  26. package/docs/08-clock-mocking.md +21 -2
  27. package/docs/09-api-testing.md +40 -2
  28. package/docs/10-accessibility.md +2 -0
  29. package/docs/11-debugging.md +3 -1
  30. package/docs/12-ai-agent-guide.md +5 -0
  31. package/docs/13-faq.md +72 -1
  32. package/docs/14-recipes-cookbook.md +2 -0
  33. package/docs/15-tag-conventions.md +2 -1
  34. package/docs/16-ci-cd.md +140 -119
  35. package/docs/README.md +5 -5
  36. package/docs/advanced-screenshots.md +3 -1
  37. package/docs/api-step-definitions.md +16 -2
  38. package/docs/global-settings.md +69 -17
  39. package/docs/install-webship-js.md +2 -0
  40. package/docs/step-definitions/then-i-should-see.md +14 -1
  41. package/docs/step-definitions/then-item-checkbox.md +2 -0
  42. package/docs/step-definitions/when-i-fill.md +4 -0
  43. package/docs/step-definitions/when-i-select-option-select-list.md +2 -0
  44. package/examples/check-switch.html +37 -0
  45. package/examples/choice-controls.html +29 -0
  46. package/examples/click-whitespace.html +37 -0
  47. package/examples/datetime-fields.html +52 -0
  48. package/examples/element-selector-hint.html +16 -0
  49. package/examples/field-states.html +27 -0
  50. package/examples/fill-in-empty.html +26 -0
  51. package/examples/fill-unreachable.html +27 -0
  52. package/examples/follow-hidden-first.html +29 -0
  53. package/examples/iframe-inner.html +20 -0
  54. package/examples/iframe-nested.html +16 -0
  55. package/examples/iframe-outer.html +15 -0
  56. package/examples/multi-value-fields.html +54 -0
  57. package/examples/registered-names.html +15 -0
  58. package/examples/select-by-label.html +33 -0
  59. package/examples/settle-budget.html +21 -0
  60. package/examples/sorted-tables.html +38 -0
  61. package/examples/text-matching.html +48 -0
  62. package/examples/text-order.html +25 -0
  63. package/examples/touch.html +22 -0
  64. package/examples/viewport-top.html +36 -0
  65. package/package.json +17 -1
  66. package/playwright.config.ts +3 -1
  67. package/tests/check-api-launch-url.js +106 -0
  68. package/tests/check-assets.js +103 -0
  69. package/tests/check-attachments.js +105 -0
  70. package/tests/check-breakpoints.js +117 -0
  71. package/tests/check-clock.js +143 -0
  72. package/tests/check-config.js +90 -0
  73. package/tests/check-context.js +215 -0
  74. package/tests/check-dry-run.js +104 -0
  75. package/tests/check-examples.js +10 -4
  76. package/tests/check-exit-report.js +141 -0
  77. package/tests/check-javascript-errors.js +105 -0
  78. package/tests/check-must-fail.js +5 -4
  79. package/tests/check-network-changed.js +137 -0
  80. package/tests/check-scaffold.js +54 -2
  81. package/tests/check-screenshots.js +117 -0
  82. package/tests/check-settle-verbs.js +137 -0
  83. package/tests/check-time-limit.js +104 -0
  84. package/tests/check-video.js +156 -0
  85. package/tests/check-world.js +167 -0
  86. package/tests/features/api-base-url.feature +25 -0
  87. package/tests/features/api-form-data.feature +18 -0
  88. package/tests/features/api-json-paths.feature +24 -0
  89. package/tests/features/api-response-contains.feature +21 -0
  90. package/tests/features/api-response-header-presence.feature +17 -0
  91. package/tests/features/api-response-header.feature +17 -0
  92. package/tests/features/api-saved-placeholders.feature +37 -0
  93. package/tests/features/api-step-definitions-individual.feature +1 -1
  94. package/tests/features/api-tables.feature +40 -0
  95. package/tests/features/breakpoints.feature +25 -0
  96. package/tests/features/check-switch.feature +28 -0
  97. package/tests/features/choice-controls.feature +35 -0
  98. package/tests/features/click-whitespace.feature +29 -0
  99. package/tests/features/complete-api-testing-examples.feature +1 -1
  100. package/tests/features/datetime-field-lookup.feature +29 -0
  101. package/tests/features/element-selector-hint.feature +14 -0
  102. package/tests/features/field-state.feature +21 -0
  103. package/tests/features/fill-in-empty-value.feature +41 -0
  104. package/tests/features/fill-reachable.feature +13 -0
  105. package/tests/features/follow-hidden-first.feature +9 -0
  106. package/tests/features/iframe-nested.feature +43 -0
  107. package/tests/features/javascript-tolerated-errors.feature +20 -0
  108. package/tests/features/modal-open.feature +13 -0
  109. package/tests/features/multi-value-field-lookup.feature +30 -0
  110. package/tests/features/registered-names.feature +14 -0
  111. package/tests/features/select-by-label.feature +31 -0
  112. package/tests/features/selector-files.feature +14 -0
  113. package/tests/features/selectors-table-header.feature +35 -0
  114. package/tests/features/settle-budget.feature +11 -0
  115. package/tests/features/sorted-tables.feature +19 -0
  116. package/tests/features/storage-quoted-values.feature +26 -0
  117. package/tests/features/text-matching.feature +38 -0
  118. package/tests/features/text-order.feature +14 -0
  119. package/tests/features/touch.feature +21 -0
  120. package/tests/features/viewport-top.feature +13 -0
  121. package/tests/features/xml-namespaces.feature +34 -0
  122. package/tests/must-fail/api-json-paths.feature +21 -0
  123. package/tests/must-fail/api-response-contains.feature +23 -0
  124. package/tests/must-fail/api-response-header-presence.feature +17 -0
  125. package/tests/must-fail/api-response-header.feature +21 -0
  126. package/tests/must-fail/api-without-base-url.feature +11 -0
  127. package/tests/must-fail/breakpoints.feature +15 -0
  128. package/tests/must-fail/choice-controls.feature +25 -0
  129. package/tests/must-fail/clock.feature +11 -0
  130. package/tests/must-fail/datetime-field.feature +10 -0
  131. package/tests/must-fail/element-selector-hint.feature +17 -0
  132. package/tests/must-fail/field-state.feature +20 -0
  133. package/tests/must-fail/fill-field.feature +30 -0
  134. package/tests/must-fail/iframe-text.feature +17 -0
  135. package/tests/must-fail/modal-open.feature +26 -0
  136. package/tests/must-fail/multi-value-field.feature +18 -0
  137. package/tests/must-fail/registered-names.feature +25 -0
  138. package/tests/must-fail/select-list.feature +15 -0
  139. package/tests/must-fail/selector-files.feature +10 -0
  140. package/tests/must-fail/sorted-tables.feature +20 -0
  141. package/tests/must-fail/storage-before-a-page.feature +13 -0
  142. package/tests/must-fail/text-matching.feature +16 -0
  143. package/tests/must-fail/text-order.feature +15 -0
  144. package/tests/must-fail/viewport-top.feature +20 -0
  145. package/tests/must-fail/yaml-numbers.feature +48 -0
  146. package/tests/step-definitions/a11y.steps.js +24 -15
  147. package/tests/step-definitions/action.steps.js +53 -20
  148. package/tests/step-definitions/api.steps.js +349 -67
  149. package/tests/step-definitions/assertion.steps.js +100 -10
  150. package/tests/step-definitions/auth.steps.js +15 -18
  151. package/tests/step-definitions/clock.steps.js +22 -0
  152. package/tests/step-definitions/debug.steps.js +8 -0
  153. package/tests/step-definitions/dialog.steps.js +7 -0
  154. package/tests/step-definitions/element.steps.js +132 -17
  155. package/tests/step-definitions/field.steps.js +412 -96
  156. package/tests/step-definitions/form.steps.js +88 -37
  157. package/tests/step-definitions/iframe.steps.js +89 -29
  158. package/tests/step-definitions/input.steps.js +26 -7
  159. package/tests/step-definitions/javascript.steps.js +64 -22
  160. package/tests/step-definitions/modal.steps.js +79 -13
  161. package/tests/step-definitions/navigation.steps.js +14 -0
  162. package/tests/step-definitions/network.steps.js +15 -5
  163. package/tests/step-definitions/response.steps.js +6 -4
  164. package/tests/step-definitions/responsive.steps.js +26 -33
  165. package/tests/step-definitions/screenshot.steps.js +25 -8
  166. package/tests/step-definitions/scroll.steps.js +20 -0
  167. package/tests/step-definitions/selectors.steps.js +95 -48
  168. package/tests/step-definitions/storage.steps.js +38 -13
  169. package/tests/step-definitions/table.steps.js +81 -6
  170. package/tests/step-definitions/video.steps.js +52 -55
  171. package/tests/step-definitions/wait.steps.js +88 -23
  172. package/tests/step-definitions/web-first.steps.js +69 -35
  173. package/tests/step-definitions/webship.js +741 -145
  174. package/tests/step-definitions/xml.steps.js +49 -15
  175. package/tests/step-definitions/yaml.steps.js +45 -20
@@ -72,7 +72,10 @@ module.exports = {
72
72
  xpath: {},
73
73
  filesPath: './tests/selectors/',
74
74
  files: [],
75
- 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.
76
79
  breakpoints: {
77
80
  xs: { width: 375, height: 667 },
78
81
  sm: { width: 576, height: 800 },
@@ -126,7 +129,9 @@ const config: PlaywrightConfig = {
126
129
  browser,
127
130
  launchOptions: {
128
131
  headless: process.env.HEADLESS !== 'false',
129
- // 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.
130
135
  slowMo: parseInt(process.env.SLOW_MO || (process.env.HEADLESS === 'false' ? '800' : '300'), 10),
131
136
  args: browser === 'chromium' ? chromiumArgs : [],
132
137
  },
@@ -192,6 +197,15 @@ const TEST_SCRIPTS = {
192
197
  // the project, so the scaffold replaces it.
193
198
  const NPM_PLACEHOLDER_TEST = /^echo "Error: no test specified" && exit 1$/;
194
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
+
195
209
  const DEFAULT_PKG = {
196
210
  name: 'project-name',
197
211
  version: '2.0.0',
@@ -227,7 +241,8 @@ function printHelp() {
227
241
  'Idempotent — safe to run multiple times.',
228
242
  '',
229
243
  'Options:',
230
- ' -f, --force Overwrite existing files',
244
+ ' -f, --force Overwrite the files and scripts of the scaffold',
245
+ ' (never tests/step-definitions/custom.js)',
231
246
  ' --skip-browsers Skip `npx playwright install chromium`',
232
247
  ' --cwd <dir> Target directory (default: $INIT_CWD or cwd)',
233
248
  ' -h, --help Show this help',
@@ -263,7 +278,8 @@ function writeTextAssets(projectPath, opts) {
263
278
  const results = [];
264
279
  for (const [rel, content] of Object.entries(TEXT_ASSETS)) {
265
280
  const dest = path.join(projectPath, rel);
266
- const written = writeFileIfMissing(dest, content, opts);
281
+ const force = opts.force && !PROJECT_FILES.has(rel);
282
+ const written = writeFileIfMissing(dest, content, { force });
267
283
  results.push({ file: rel, written });
268
284
  }
269
285
  return results;
@@ -288,20 +304,34 @@ function ensurePackageJson(projectPath, opts) {
288
304
  }
289
305
 
290
306
  pkg.scripts = pkg.scripts || {};
307
+ let replacedNightwatch = null;
291
308
  for (const [name, cmd] of Object.entries(TEST_SCRIPTS)) {
292
- const placeholder = name === 'test' && NPM_PLACEHOLDER_TEST.test(String(pkg.scripts[name] || '').trim());
293
- if (opts.force || !pkg.scripts[name] || placeholder) {
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) {
294
317
  pkg.scripts[name] = cmd;
295
318
  }
296
319
  }
297
320
 
298
- pkg.dependencies = pkg.dependencies || {};
299
- if (opts.force || !pkg.dependencies['webship-js']) {
321
+ // webship-js is listed once: where the project already declares it (a dev or peer dependency
322
+ // included), with its range; --force only refreshes that range. Otherwise it goes under
323
+ // dependencies.
324
+ const declaredIn = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']
325
+ .find((field) => pkg[field] && pkg[field]['webship-js']);
326
+ if (!declaredIn) {
327
+ pkg.dependencies = pkg.dependencies || {};
300
328
  pkg.dependencies['webship-js'] = readPkgVersion();
329
+ } else if (opts.force) {
330
+ pkg[declaredIn]['webship-js'] = readPkgVersion();
301
331
  }
302
332
 
303
333
  fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf8');
304
- return { created: !existed };
334
+ return { created: !existed, replacedNightwatch };
305
335
  }
306
336
 
307
337
  // The browser itself goes into the Playwright cache of the user: no special
@@ -352,12 +382,25 @@ function run(argv) {
352
382
  const pkgResult = ensurePackageJson(projectPath, opts);
353
383
 
354
384
  for (const r of assetResults) {
355
- console.log(` [${r.written ? 'wrote ' : 'kept '}] ${r.file}`);
385
+ const note = !r.written && opts.force && PROJECT_FILES.has(r.file)
386
+ ? ' (the steps of the project: --force never overwrites it)'
387
+ : '';
388
+ console.log(` [${r.written ? 'wrote ' : 'kept '}] ${r.file}${note}`);
356
389
  }
357
390
  console.log(` [${tsconfigWritten ? 'wrote ' : 'kept '}] tsconfig.json`);
358
391
  console.log(
359
392
  ` [${pkgResult.created ? 'wrote ' : 'merged'}] package.json`
360
393
  );
394
+ if (pkgResult.replacedNightwatch) {
395
+ console.log(
396
+ [
397
+ '',
398
+ ' [webship-js] "npm test" ran Nightwatch (a webship-js 1.x project). It now runs',
399
+ ' cucumber-js: cucumber-js --config cucumber.js',
400
+ ' The old command is kept as "npm run test:nightwatch".',
401
+ ].join('\n')
402
+ );
403
+ }
361
404
 
362
405
  const browsersInstalled = opts.skipBrowsers || installBrowsers(projectPath);
363
406
 
@@ -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
package/cucumber.js CHANGED
@@ -91,9 +91,12 @@ module.exports = {
91
91
  // Load additional selectors from JSON files at scenario start.
92
92
  filesPath: './tests/selectors/', // base path for selector files
93
93
  files: [], // e.g. ['homepage-selectors.json'] or ['front-end-selectors.json', 'back-end-selectors.json']
94
- // Relative-position scroll offset (px) — WEBSHIP_SELECTORS_OFFSET
95
- offset: 60,
96
- // Viewport breakpoints — WEBSHIP_SELECTORS_BREAKPOINTS (JSON string)
94
+ // Named viewport sizes for every step and tag that names one (viewing
95
+ // the site on a … screen, set the viewport to the "…" breakpoint,
96
+ // @mobile, @desktop). Built in: xs..xxxl, mobile, tablet, desktop;
97
+ // these replace or add names. WEBSHIP_SELECTORS_BREAKPOINTS (a JSON
98
+ // object) is merged over them. Without a `desktop` here, @desktop
99
+ // opens at the breakpoint marked default: true.
97
100
  breakpoints: {
98
101
  xs: { width: 375, height: 667 }, // phone portrait
99
102
  sm: { width: 576, height: 800 }, // large phone / phablet
@@ -117,19 +120,23 @@ module.exports = {
117
120
  },
118
121
  video: {
119
122
  // Record the browser as a webm video.
120
- // 'off' (default) — no recording.
123
+ // 'off' (default) — no recording, except scenarios tagged @video.
121
124
  // 'on' — record every scenario.
122
- // 'on-failure' — record every scenario, keep only failures.
123
- // 'tag' — record only scenarios tagged @video.
125
+ // 'on-failure' — record every scenario, keep only failures (and
126
+ // the videos of @video scenarios or with a name
127
+ // reserved by "I save the current video as").
128
+ // 'tag' — the same as 'off': only scenarios tagged @video.
124
129
  // Override per scenario with tags:
125
- // @video — force recording on (independent of mode).
130
+ // @video — force recording on (in every mode).
126
131
  // @no-video — suppress recording for this scenario.
127
132
  // Override per run with env: WEBSHIP_VIDEO.
128
133
  mode: 'off', // WEBSHIP_VIDEO
129
134
  dir: './videos', // WEBSHIP_VIDEO_DIR
130
- size: { width: 1280, height: 720 }, // viewport size of the recording
131
- // Filename template tokens: {datetime} {feature_file} {feature} {scenario}
132
- // {status} {ext}. Sanitised to filesystem-safe characters.
135
+ size: { width: 1280, height: 720 }, // WEBSHIP_VIDEO_SIZE e.g. "1280x720"
136
+ // Filename template tokens: {datetime} (when the recording started)
137
+ // {feature_file} {feature} {scenario} {status} (passed, failed, … in
138
+ // lower case; "manual" for a recording stopped by a step) {ext}.
139
+ // Sanitised to filesystem-safe characters.
133
140
  filenamePattern: '{datetime}.{feature_file}.{scenario}.{status}.{ext}',
134
141
  },
135
142
  javascript: {
@@ -55,6 +55,14 @@ npx init-webship-js
55
55
  npm install-scripts approve webship-js
56
56
  ```
57
57
 
58
+ The scaffold never replaces a file or a `test` script the project already
59
+ has, with two exceptions: npm's "no test specified" placeholder, and a
60
+ `test` script that runs Nightwatch (a project upgraded from webship-js
61
+ 1.x), which becomes the cucumber-js suite while the old command stays
62
+ available as `npm run test:nightwatch`. `npx init-webship-js --force`
63
+ rewrites the scaffold's files and scripts, but never
64
+ `tests/step-definitions/custom.js`, which holds the project's own steps.
65
+
58
66
  Firefox and WebKit are optional: `npx playwright install firefox webkit`.
59
67
 
60
68
  ## 60-second first test
@@ -32,21 +32,23 @@ reads the count the same way.
32
32
  ### How the budget is shared
33
33
 
34
34
  Each phase is best-effort — a phase that times out is not a failure — and each
35
- gets a **share of the budget** rather than "whatever is left":
35
+ but the last gets a **share of the budget** rather than "whatever is left":
36
36
 
37
37
  | Phase | Share of the budget |
38
38
  | --- | --- |
39
39
  | `<body>` attached | 25% |
40
40
  | `DOMContentLoaded` | 25% |
41
41
  | `networkidle` | 50% |
42
- | AJAX + pending timers + DOM quiet | 50% |
42
+ | AJAX + pending timers + DOM quiet | everything left |
43
43
 
44
- The shares add up to more than 100% on purpose: a phase that finishes early
45
- hands its unspent time to the ones after it, and no phase is ever given more
46
- than what is actually left. Capping `networkidle` matters, because on a page
47
- with analytics, a chat widget or a self-rescheduling timer it never arrives —
48
- uncapped it would eat the whole budget and starve the AJAX / pending-timer /
49
- DOM-quiet probe, which is the phase that decides the answer.
44
+ A phase that finishes early hands its unspent time to the ones after it, and
45
+ no phase is ever given more than what is actually left. Capping `networkidle`
46
+ matters, because on a page with analytics, a chat widget or a
47
+ self-rescheduling timer it never arrives — uncapped it would eat the whole
48
+ budget and starve the AJAX / pending-timer / DOM-quiet probe, which is the
49
+ phase that decides the answer. That probe comes last, so it takes the whole
50
+ rest of the budget: after a step that changes the page (1.5 seconds), a
51
+ request or a timer of a second is still waited for.
50
52
 
51
53
  `smartSettle` returns within `budget` even when nothing on the page ever
52
54
  settles, and never hands Playwright a zero timeout (Playwright reads `0` as
@@ -82,14 +84,17 @@ When I wait for the modal to disappear
82
84
  # Body + DOMContentLoaded only (cheaper than full smart settle).
83
85
  When I wait until the page is interactive
84
86
 
85
- # Polling text assertion — re-runs the matcher until the deadline.
87
+ # Polling text assertion — re-runs the matcher until the deadline. It reads the
88
+ # page as "I should see" does: letter case ignored, hidden text included.
86
89
  Then eventually I should see "Done"
87
90
  Then eventually I should see "Done" within 10 seconds
88
91
  ```
89
92
 
90
93
  ## Auto-settle after actions
91
94
 
92
- 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`.
95
+ After every state-changing step, 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`.
96
+
97
+ A step is state-changing when its own words — not its quoted arguments — carry one of these verbs: click, press, fill, submit, select, check, uncheck, choose, attach, upload, reload, move back / forward, go to, navigate, on the homepage, open, close, add, remove, insert, delete, save, publish, edit, update, create, enter, type, clear, reset, drag, drop, hover, tap, toggle, expand, collapse, search, send, request, flush, confirm, cancel, accept, dismiss, log in / out, sign in / out. The list covers the built-in steps and the way a project's own steps are usually worded (`When I add "Laptop" to the cart`, `When I log out`, `When I enter the 2FA code "123456"`). `Then I should see "Delete"` is no action: the verb is in the quoted text. A scroll gets no settle on purpose: it often starts a loader ("Loading more items…") that the next step checks while it shows. A project step whose words carry none of the verbs waits the same way by calling `await this.smartSettle()` itself.
93
98
 
94
99
  ## What this kills
95
100
 
@@ -25,6 +25,8 @@ Scenario: Layout assertions
25
25
  Then "main" should be visible
26
26
  ```
27
27
 
28
+ The table may start with a row that names its columns, `| name | css selector |` (or `| name | xpath selector |` for `I define xpath selectors:`): that first row is read as the header of the table and registers nothing.
29
+
28
30
  ### 3. JSON file (project-wide preset)
29
31
 
30
32
  ```js
@@ -37,6 +39,8 @@ worldParameters: {
37
39
  }
38
40
  ```
39
41
 
42
+ A file of `files` (and of `When I add selectors from "…" file`) is looked for in the `filesPath` folder first (default `./tests/selectors/`), then as written from the project root: `'auth.json'` and `'tests/selectors/auth.json'` name the same file. A file found in neither place fails the scenario with the paths tried.
43
+
40
44
  Every scenario starts with a fresh registry. Later entries with the same name override earlier ones (last wins).
41
45
 
42
46
  ## Built-in CMS / framework presets
@@ -93,3 +97,23 @@ To keep tests portable, every preset exposes the same core names. See `tests/sel
93
97
  - Modifier first (`active tab`, `danger button`, `first list item`).
94
98
  - Synonyms collapse to canonical names (`alert success` / `notification success` / `callout success` → `notice success`).
95
99
  - `data table` for HTML tables; `data list` for `ul`/`ol` collections.
100
+
101
+ ## Bare names and your own steps
102
+
103
+ The steps that take registered names without quotes (`When I click primary button`, `Then I see visible header, footer`, `Then I don't see promo banner`, `Then I see header above footer`, `Then I see search input has focus`) match any unquoted words after their verb, so that every registered name works, `sign in button` and `log in link` included. A custom step of your project that starts the same way with unquoted words matches them too: `When I click next button in tour` is ambiguous between your step and the bare-name click, and cucumber-js stops at it.
104
+
105
+ Write such a step with a quoted argument and words of its own around it (`When I click "Next" in the tour`), or start it with other words (`When I move to the next step of the tour`). Or register the element and use the built-in step: `When I add "tour next button" selector for ".tour .next" css selector`, then `When I click tour next button`. After adding a step, `npx cucumber-js --dry-run` lists every step that is ambiguous.
106
+
107
+ ## Which steps read a registered name
108
+
109
+ The registry is read by the bare-name steps above and by the modal steps. Every step that takes its argument in quotes reads it as it is written: a text (`I click "Subscribe"`, `I press "Save"`), a label, a placeholder or a name (`I fill in "Email" with "…"`), or a CSS selector (`"#dashboard" should be visible`, `the element "#hero" should be displayed`). A registered name given to one of those steps matches nothing, and its failure says so and names the step to use:
110
+
111
+ ```
112
+ ✖ Then "premium-banner" should be visible
113
+ Expected "premium-banner" to be visible.
114
+ Found: last seen: false
115
+ Page: http://localhost:8080/registered-names.html
116
+ Hint: "premium-banner" is a name of the selector registry (.promo-banner), but this step does not read the registry. Use: I see visible premium-banner, or: ".promo-banner" should be visible
117
+ ```
118
+
119
+ The hint is added to the failures of the click and press steps, the fill steps, the web-first steps (`"…" should be visible`, `… should have text`, …) and the element steps (`I click on the element "…"`, `I scroll to the element "…"`, `the element "…" should be at the top of the viewport`, …).