webship-js 2.0.11 → 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 (168) hide show
  1. package/.circleci/config.yml +10 -1
  2. package/.drone.yml +7 -7
  3. package/.github/workflows/github-actions.yml +45 -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 +44 -8
  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/choice-controls.html +29 -0
  45. package/examples/datetime-fields.html +52 -0
  46. package/examples/element-selector-hint.html +16 -0
  47. package/examples/field-states.html +27 -0
  48. package/examples/fill-in-empty.html +26 -0
  49. package/examples/fill-unreachable.html +27 -0
  50. package/examples/iframe-inner.html +20 -0
  51. package/examples/iframe-nested.html +16 -0
  52. package/examples/iframe-outer.html +15 -0
  53. package/examples/multi-value-fields.html +54 -0
  54. package/examples/registered-names.html +15 -0
  55. package/examples/select-by-label.html +33 -0
  56. package/examples/settle-budget.html +21 -0
  57. package/examples/sorted-tables.html +38 -0
  58. package/examples/text-matching.html +48 -0
  59. package/examples/text-order.html +25 -0
  60. package/examples/touch.html +22 -0
  61. package/examples/viewport-top.html +36 -0
  62. package/package.json +16 -1
  63. package/playwright.config.ts +3 -1
  64. package/tests/check-api-launch-url.js +106 -0
  65. package/tests/check-assets.js +103 -0
  66. package/tests/check-attachments.js +105 -0
  67. package/tests/check-breakpoints.js +117 -0
  68. package/tests/check-clock.js +143 -0
  69. package/tests/check-config.js +90 -0
  70. package/tests/check-context.js +215 -0
  71. package/tests/check-dry-run.js +104 -0
  72. package/tests/check-examples.js +10 -4
  73. package/tests/check-exit-report.js +141 -0
  74. package/tests/check-javascript-errors.js +105 -0
  75. package/tests/check-must-fail.js +5 -4
  76. package/tests/check-scaffold.js +36 -1
  77. package/tests/check-screenshots.js +117 -0
  78. package/tests/check-settle-verbs.js +137 -0
  79. package/tests/check-time-limit.js +104 -0
  80. package/tests/check-video.js +156 -0
  81. package/tests/check-world.js +167 -0
  82. package/tests/features/api-base-url.feature +25 -0
  83. package/tests/features/api-form-data.feature +18 -0
  84. package/tests/features/api-json-paths.feature +24 -0
  85. package/tests/features/api-response-contains.feature +21 -0
  86. package/tests/features/api-response-header-presence.feature +17 -0
  87. package/tests/features/api-response-header.feature +17 -0
  88. package/tests/features/api-saved-placeholders.feature +37 -0
  89. package/tests/features/api-step-definitions-individual.feature +1 -1
  90. package/tests/features/api-tables.feature +40 -0
  91. package/tests/features/breakpoints.feature +25 -0
  92. package/tests/features/choice-controls.feature +35 -0
  93. package/tests/features/complete-api-testing-examples.feature +1 -1
  94. package/tests/features/datetime-field-lookup.feature +29 -0
  95. package/tests/features/element-selector-hint.feature +14 -0
  96. package/tests/features/field-state.feature +21 -0
  97. package/tests/features/fill-in-empty-value.feature +41 -0
  98. package/tests/features/fill-reachable.feature +13 -0
  99. package/tests/features/iframe-nested.feature +43 -0
  100. package/tests/features/javascript-tolerated-errors.feature +20 -0
  101. package/tests/features/modal-open.feature +13 -0
  102. package/tests/features/multi-value-field-lookup.feature +30 -0
  103. package/tests/features/registered-names.feature +14 -0
  104. package/tests/features/select-by-label.feature +31 -0
  105. package/tests/features/selector-files.feature +14 -0
  106. package/tests/features/selectors-table-header.feature +35 -0
  107. package/tests/features/settle-budget.feature +11 -0
  108. package/tests/features/sorted-tables.feature +19 -0
  109. package/tests/features/storage-quoted-values.feature +26 -0
  110. package/tests/features/text-matching.feature +38 -0
  111. package/tests/features/text-order.feature +14 -0
  112. package/tests/features/touch.feature +21 -0
  113. package/tests/features/viewport-top.feature +13 -0
  114. package/tests/features/xml-namespaces.feature +34 -0
  115. package/tests/must-fail/api-json-paths.feature +21 -0
  116. package/tests/must-fail/api-response-contains.feature +23 -0
  117. package/tests/must-fail/api-response-header-presence.feature +17 -0
  118. package/tests/must-fail/api-response-header.feature +21 -0
  119. package/tests/must-fail/api-without-base-url.feature +11 -0
  120. package/tests/must-fail/breakpoints.feature +15 -0
  121. package/tests/must-fail/choice-controls.feature +25 -0
  122. package/tests/must-fail/clock.feature +11 -0
  123. package/tests/must-fail/datetime-field.feature +10 -0
  124. package/tests/must-fail/element-selector-hint.feature +17 -0
  125. package/tests/must-fail/field-state.feature +20 -0
  126. package/tests/must-fail/fill-field.feature +30 -0
  127. package/tests/must-fail/iframe-text.feature +17 -0
  128. package/tests/must-fail/modal-open.feature +26 -0
  129. package/tests/must-fail/multi-value-field.feature +18 -0
  130. package/tests/must-fail/registered-names.feature +25 -0
  131. package/tests/must-fail/select-list.feature +15 -0
  132. package/tests/must-fail/selector-files.feature +10 -0
  133. package/tests/must-fail/sorted-tables.feature +20 -0
  134. package/tests/must-fail/storage-before-a-page.feature +13 -0
  135. package/tests/must-fail/text-matching.feature +16 -0
  136. package/tests/must-fail/text-order.feature +15 -0
  137. package/tests/must-fail/viewport-top.feature +20 -0
  138. package/tests/must-fail/yaml-numbers.feature +48 -0
  139. package/tests/step-definitions/a11y.steps.js +24 -15
  140. package/tests/step-definitions/action.steps.js +22 -8
  141. package/tests/step-definitions/api.steps.js +349 -67
  142. package/tests/step-definitions/assertion.steps.js +100 -10
  143. package/tests/step-definitions/auth.steps.js +15 -18
  144. package/tests/step-definitions/clock.steps.js +22 -0
  145. package/tests/step-definitions/debug.steps.js +8 -0
  146. package/tests/step-definitions/dialog.steps.js +7 -0
  147. package/tests/step-definitions/element.steps.js +132 -17
  148. package/tests/step-definitions/field.steps.js +409 -96
  149. package/tests/step-definitions/form.steps.js +76 -29
  150. package/tests/step-definitions/iframe.steps.js +89 -29
  151. package/tests/step-definitions/input.steps.js +26 -7
  152. package/tests/step-definitions/javascript.steps.js +64 -22
  153. package/tests/step-definitions/modal.steps.js +79 -13
  154. package/tests/step-definitions/navigation.steps.js +14 -0
  155. package/tests/step-definitions/network.steps.js +15 -5
  156. package/tests/step-definitions/response.steps.js +6 -4
  157. package/tests/step-definitions/responsive.steps.js +26 -33
  158. package/tests/step-definitions/screenshot.steps.js +25 -8
  159. package/tests/step-definitions/scroll.steps.js +20 -0
  160. package/tests/step-definitions/selectors.steps.js +95 -48
  161. package/tests/step-definitions/storage.steps.js +38 -13
  162. package/tests/step-definitions/table.steps.js +81 -6
  163. package/tests/step-definitions/video.steps.js +52 -55
  164. package/tests/step-definitions/wait.steps.js +88 -23
  165. package/tests/step-definitions/web-first.steps.js +69 -35
  166. package/tests/step-definitions/webship.js +681 -143
  167. package/tests/step-definitions/xml.steps.js +49 -15
  168. 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,9 +304,16 @@ 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
  }
@@ -301,7 +324,7 @@ function ensurePackageJson(projectPath, opts) {
301
324
  }
302
325
 
303
326
  fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf8');
304
- return { created: !existed };
327
+ return { created: !existed, replacedNightwatch };
305
328
  }
306
329
 
307
330
  // The browser itself goes into the Playwright cache of the user: no special
@@ -352,12 +375,25 @@ function run(argv) {
352
375
  const pkgResult = ensurePackageJson(projectPath, opts);
353
376
 
354
377
  for (const r of assetResults) {
355
- 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}`);
356
382
  }
357
383
  console.log(` [${tsconfigWritten ? 'wrote ' : 'kept '}] tsconfig.json`);
358
384
  console.log(
359
385
  ` [${pkgResult.created ? 'wrote ' : 'merged'}] package.json`
360
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
+ }
361
397
 
362
398
  const browsersInstalled = opts.skipBrowsers || installBrowsers(projectPath);
363
399
 
@@ -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`, …).
@@ -29,15 +29,15 @@ This is a topical reference. For per-step examples, see the JSDoc comment above
29
29
 
30
30
  | Step | Notes |
31
31
  | --- | --- |
32
- | `When I fill in "Label" with "value"` | Resolves by label / placeholder / name |
32
+ | `When I fill in "Label" with "value"` | Resolves by label / placeholder / name. `with ""` empties the field, in every fill form. A hidden, disabled or read-only field fails within 5 s, saying which |
33
33
  | `When I fill in "value" for "Label"` | Reverse phrasing |
34
34
  | `When I fill in "value" for "selector" by attr` | By attribute |
35
35
  | `When I fill in the following:` (table) | Bulk fill |
36
- | `When I select "Option" from "Label"` | `<select>` |
36
+ | `When I select "Option" from "Label"` | `<select>` by the exact text of its label, its name, its id, or a CSS selector (`#`, `.`, `[`); the option by its text or value |
37
37
  | `When I additionally select "Option" from "Label"` | Multi-select |
38
- | `When I check the checkbox "#agree"` | |
39
- | `When I uncheck the checkbox "#agree"` | |
40
- | `When I choose the radio button "#radio"` | |
38
+ | `When I check the checkbox "#agree"` | By CSS selector, label, name, id or value |
39
+ | `When I uncheck the checkbox "#agree"` | By CSS selector, label, name, id or value |
40
+ | `When I choose the radio button "#radio"` | By CSS selector, label, id or value |
41
41
 
42
42
  ## Waits — see [BBR](02-bbr-smart-waits.md)
43
43
 
@@ -64,6 +64,16 @@ I wait for the modal to appear/disappear # Modal edge
64
64
  eventually I should see "..." # Polling text assertion
65
65
  ```
66
66
 
67
+ ## Page text
68
+
69
+ | Step | Notes |
70
+ | --- | --- |
71
+ | `Then I should see "text"` | Waits up to 5 s for the text to come |
72
+ | `Then I should not see "text"` | Waits up to 5 s for the text to go |
73
+ | `Then eventually I should see "text" [within N seconds]` | Waits up to 10 s, or N |
74
+
75
+ The three read the page the same way: letter case ignored, white space collapsed, the text of hidden elements included, the text of `<script>` and `<style>` left out. For the text a visitor can see, with its letter case, use `I wait for the text "..." to appear` / `to disappear`. See [Then I should see](step-definitions/then-i-should-see.md).
76
+
67
77
  ## Modal
68
78
 
69
79
  | Step | |
@@ -72,9 +82,9 @@ eventually I should see "..." # Polling text assertion
72
82
  | `Then I should not see the modal` | |
73
83
  | `Then I should see "text" in the modal` | |
74
84
  | `Then the modal should contain "text"` | |
75
- | `When I click "OK" in the modal` | |
76
- | `When I click on "#sel" in the modal` | |
77
- | `When I close the modal` | |
85
+ | `When I click "OK" in the modal` | Waits up to 5 s for a modal to be open, else fails with "No modal is open"; a button the open modal lacks fails, listing the ones it has |
86
+ | `When I click on "#sel" in the modal` | The selector inside the open modal only; same 5 s wait for an open modal |
87
+ | `When I close the modal` | Close button, else Escape; same 5 s wait for an open modal |
78
88
 
79
89
  ## Web-first assertions (auto-retry)
80
90
 
@@ -101,9 +111,12 @@ See `cookie.steps.js`, `response.steps.js`, `metatag.steps.js`.
101
111
  the table "selector" should have N rows
102
112
  the table "selector" should have N columns
103
113
  the table "selector" should not be empty
114
+ the table "selector" should be sorted by "Column" in "ascending|descending" order
104
115
  I should see "Text" in the "RowMatch" row
105
116
  ```
106
117
 
118
+ The sorted step compares the cells of the column the way a reader orders them: as numbers when every cell reads as a number (`$9.99`, `1,299`, `12 %`), else as dates when every cell reads as a date, else as text with letter case ignored and the numbers inside the text in number order ("Item 2" before "Item 10"). Equal cells may come in any order.
119
+
107
120
  ## Iframes / file download / REST / XML / keyboard
108
121
 
109
122
  See per-topic files in `tests/step-definitions/`. Each file has JSDoc above every step with all pronoun and tense variants.
@@ -227,7 +240,9 @@ Settings (`worldParameters.javascript`):
227
240
  | `beforeScenario` | `WEBSHIP_JS_ERROR_BEFORE` | `false` | Snapshot pre-existing errors at scenario start |
228
241
  | `afterScenario` | `WEBSHIP_JS_ERROR_AFTER` | `true` | Report at scenario end |
229
242
 
230
- The explicit step `Then there should be no JavaScript errors` always asserts (independent of `mode`) and suppresses the auto-report so a single error is not announced twice.
243
+ The explicit step `Then there should be no JavaScript errors` counts errors only — uncaught errors and `console.error`, not the warnings when `warning` is a captured level — always asserts (independent of `mode`) and leaves the errors out of the auto-report so a single error is not announced twice; `Then there should be no JavaScript warnings` does the same for the warnings. What a check did not read is still reported at the end of the scenario.
244
+
245
+ `Then JavaScript errors should not match "…"` handles the errors it read in the same way: a page with noise it tolerates does not fail the scenario at its end in `fail` mode, only an error that matches the pattern fails it.
231
246
 
232
247
  ## Video recording
233
248
 
@@ -248,10 +263,10 @@ Mode semantics:
248
263
 
249
264
  | Mode | Behaviour |
250
265
  | --- | --- |
251
- | `off` (default) | No recording. |
266
+ | `off` (default) | No recording, except the scenarios tagged `@video`. |
252
267
  | `on` | Every scenario produces a `webm`. |
253
- | `on-failure` | Every scenario records; only failures are kept on disk. |
254
- | `tag` | Only scenarios tagged `@video` record. |
268
+ | `on-failure` | Every scenario records; only failures are kept on disk, with the `@video` scenarios and the videos whose name `I save the current video as` reserved. |
269
+ | `tag` | The same as `off`: only scenarios tagged `@video` record. |
255
270
 
256
271
  Settings (`worldParameters.video`):
257
272
 
@@ -259,10 +274,10 @@ Settings (`worldParameters.video`):
259
274
  | --- | --- | --- | --- |
260
275
  | `mode` | `WEBSHIP_VIDEO` | `off` | Activation mode. |
261
276
  | `dir` | `WEBSHIP_VIDEO_DIR` | `./videos` | Output directory (created automatically). |
262
- | `size` | _none_ | `{ width: 1280, height: 720 }` | Recording resolution. |
263
- | `filenamePattern` | _none_ | `{datetime}.{feature_file}.{scenario}.{status}.{ext}` | Per-scenario filename. Tokens: `{datetime} {feature_file} {feature} {scenario} {status} {ext}`. |
277
+ | `size` | `WEBSHIP_VIDEO_SIZE` (`1280x720`) | `{ width: 1280, height: 720 }` | Recording resolution. |
278
+ | `filenamePattern` | _none_ | `{datetime}.{feature_file}.{scenario}.{status}.{ext}` | Per-scenario filename. Tokens: `{datetime}` (when the recording started) `{feature_file} {feature} {scenario} {status}` (`passed`, `failed`, … in lower case; `manual` for a recording `stop video recording` ended) `{ext}`. |
264
279
 
265
- The `start` / `stop` mid-scenario steps close + reopen the browser context (Playwright records at context creation only). Page state is lost across the boundary — call `start` BEFORE any navigation. `videos/` is gitignored.
280
+ `print video path` prints the path the video is saved under when the scenario ends (`<status>` stands for the result still to come). `start video recording` on a scenario that already records changes nothing. The `start` / `stop` mid-scenario steps open a new browser context (Playwright records at context creation only). The cookies and local storage, the viewport of an `@mobile` / `@desktop` tag, the smart waits, JavaScript-error capture and a running request log go on with it; the page itself starts blank — call `start` BEFORE any navigation, and open the page again after `stop`. `videos/` is gitignored.
266
281
 
267
282
  ## Date tokens
268
283
 
@@ -343,9 +358,11 @@ This index lists every public step grouped by source file, with one Gherkin exam
343
358
  - *^(?:the JSON response should have property|the API response should contain property) "([^"]*)"$* · Example: `Then the JSON response should have property "id"`
344
359
  - *^(?:the JSON response should not have property|the API response should not contain property) "([^"]*)"$* · Example: `Then the JSON response should not have property "password"`
345
360
  - *^(?:the response should be valid JSON|the API response should be valid JSON)$* · Example: `Then the response should be valid JSON`
346
- - *^(?:the response header|the header) "([^"]*)" should (?:be|contain) "([^"]*)"$* · Example: `Then the response header "Content-Type" should be "application/json"`
361
+ - *^(?:the response header|the header) "([^"]*)" should (be|contain) "([^"]*)"$* · Example: `Then the response header "Content-Type" should be "application/json; charset=utf-8"`
347
362
  - *^print API response$* · Example: `Then print API response`
363
+ - *^(?:the )?API response should( not)? contain the header "([^"]*)"$* · Example: `Then the API response should contain the header "ETag"`
348
364
  - *^(?:I|we) set placeholder "([^"]*)" to "([^"]*)"$* · Example: `Given I set placeholder "{{userId}}" to "123"`
365
+ - *^(I |we )*save the JSON property "([^"]*)" as placeholder "([^"]*)"$* · Example: `When I save the JSON property "token" as placeholder "{{token}}"`
349
366
 
350
367
  ### assertion.steps.js
351
368
 
@@ -415,6 +432,7 @@ This index lists every public step grouped by source file, with one Gherkin exam
415
432
 
416
433
  - *the element {string} should appear after the element {string}* · Example: `Then the element "#footer" should appear after the element "#main"`
417
434
  - *the text {string} should appear after the text {string}* · Example: `Then the text "Sign in" should appear after the text "Welcome"`
435
+ - *the text {string} should appear after the text {string} in the {string} element* · Example: `Then the text "Products" should appear after the text "Home" in the "nav.breadcrumb" element`
418
436
  - *the element {string} with the attribute {string} and the value {string} should exist* · Example: `Then the element "a" with the attribute "href" and the value "/about" should exist`
419
437
  - *the element {string} with the attribute {string} and the value containing {string} should exist* · Example: `Then the element "a" with the attribute "href" and the value containing "/about" should exist`
420
438
  - *the element {string} with the attribute {string} and the value {string} should not exist* · Example: `Then the element "a" with the attribute "href" and the value "/admin" should not exist`
@@ -439,10 +457,10 @@ This index lists every public step grouped by source file, with one Gherkin exam
439
457
  - *the field {string} should not be empty* · Example: `Then the field "username" should not be empty`
440
458
  - *the field {string} should exist* · Example: `Then the field "username" should exist`
441
459
  - *the field {string} should not exist* · Example: `Then the field "missing-field" should not exist`
442
- - *the field {string} should have {string} state* · Example: `Then the field "username" should have "enabled" state`
460
+ - *the field {string} should have {string} state* · Example: `Then the field "username" should have "enabled" state` · States: `enabled`, `disabled`, `editable`, `read-only` (or `readonly`); any other word fails the step
443
461
  - *the field {string} should be required* · Example: `Then the field "username" should be required`
444
462
  - *the field {string} should not be required* · Example: `Then the field "bio" should not be required`
445
- - *^(I |we )*fill in the multi-value field "([^"]*)" with the following values:$* · Example: `When I fill in the multi-value field "tags" with the following values:`
463
+ - *^(I |we )*fill in the multi-value field "([^"]*)" with the following values:$* · Example: `When I fill in the multi-value field "tags" with the following values:` · The field: the name of its inputs (`tags[]`, `tags[0]`, `tags[0][value]`), the legend of its fieldset, or its label; fewer inputs than values fails before anything is filled
446
464
  - *^(I |we )*fill in the color field "([^"]*)" with the value "([^"]*)"$* · Example: `When I fill in the color field "favorite" with the value "#ff0000"`
447
465
  - *the color field {string} should have the value {string}* · Example: `Then the color field "favorite" should have the value "#ff0000"`
448
466
  - *^(I |we )*fill in the WYSIWYG field "([^"]*)" with the "([^"]*)"$* · Example: `When I fill in the WYSIWYG field "body" with the "Hello world"`
@@ -462,6 +480,7 @@ This index lists every public step grouped by source file, with one Gherkin exam
462
480
  - *^(I |we )*fill in the time part of the datetime field "([^"]*)" with "([^"]*)"$* · Example: `When I fill in the time part of the datetime field "Start" with "10:00"`
463
481
  - *^(I |we )*fill in the start datetime field "([^"]*)" with date "([^"]*)" and time "([^"]*)"$* · Example: `When I fill in the start datetime field "Event" with date "2026-05-08" and time "10:00"`
464
482
  - *^(I |we )*fill in the end datetime field "([^"]*)" with date "([^"]*)" and time "([^"]*)"$* · Example: `When I fill in the end datetime field "Event" with date "2026-05-09" and time "18:00"`
483
+ - The datetime steps name a field by the exact text of its label or of the legend of its fieldset (white space and letter case aside) and fill only its own inputs: the one inside the label, the one the label is for, or the ones that follow the label before the next field; an input whose name or aria-label contains the text is found last. A field with no such input fails the step and fills nothing.
465
484
 
466
485
  ### file-download.steps.js
467
486
 
@@ -502,6 +521,7 @@ This index lists every public step grouped by source file, with one Gherkin exam
502
521
  - *^(I |we )*fill in "([^"]*)" with "([^"]*)" inside the iframe$* · Example: `When I fill in "card_number" with "4242 4242 4242 4242" inside the iframe`
503
522
  - *^I should see "([^"]*)" inside the iframe$* · Example: `Then I should see "Payment received" inside the iframe`
504
523
  - *^I should not see "([^"]*)" inside the iframe$* · Example: `Then I should not see "Error" inside the iframe`
524
+ - The iframe steps act in the iframe the scenario switched to last; while an iframe is active, a switch looks for the iframe inside it first, then in the page (nested iframes). `by attr inside the iframe` tries the attributes `I click "…" by attr` tries; the frame fill finds a field by label, placeholder, name or id; `I should (not) see "…" inside the iframe` reads the iframe as `I should (not) see` reads the page and waits up to 5 seconds.
505
525
 
506
526
  ### input.steps.js
507
527
 
@@ -513,7 +533,7 @@ This index lists every public step grouped by source file, with one Gherkin exam
513
533
  - *^(I |we )*click on "([^"]*)" while holding "([^"]*)"$* · Example: `When I click on "#row-1" while holding "Shift"`
514
534
  - *^(I |we )*drag "([^"]*)" to "([^"]*)"$* · Example: `When I drag "#card-1" to "#column-done"`
515
535
  - *^(I |we )*set the viewport size to (\d+)x(\d+)$* · Example: `When I set the viewport size to 1280x720`
516
- - *^(I |we )*tap on "([^"]*)"$* · Example: `When I tap on "#cta"`
536
+ - *^(I |we )*tap on "([^"]*)"$* · Example: `When I tap on "#cta"` — a real tap in a scenario tagged `@touch`; without touch, a click (and a note)
517
537
 
518
538
  ### javascript.steps.js
519
539
 
@@ -671,16 +691,20 @@ This index lists every public step grouped by source file, with one Gherkin exam
671
691
 
672
692
  ### storage.steps.js
673
693
 
674
- - *^(?:the cookie|cookie) "([^"]*)" is set to "([^"]*)"$* · Example: `Given the cookie "session" is set to "abc123"`
675
- - *^the cookie "([^"]*)" is removed$* · Example: `Given the cookie "session" is removed`
694
+ - *^(?:the cookie|cookie) "((?:[^"\\]|\\.)*)" is set to "((?:[^"\\]|\\.)*)"$* · Example: `Given the cookie "session" is set to "abc123"`
695
+ - *^the cookie "((?:[^"\\]|\\.)*)" is removed$* · Example: `Given the cookie "session" is removed`
676
696
  - *^all cookies are cleared$* · Example: `Given all cookies are cleared`
677
- - *^(?:the )?local storage "([^"]*)" is set to "([^"]*)"$* · Example: `Given the local storage "user" is set to "Alice"`
678
- - *^(?:the )?local storage "([^"]*)" is removed$* · Example: `Given the local storage "user" is removed`
697
+ - *^(?:the )?local storage "((?:[^"\\]|\\.)*)" is set to "((?:[^"\\]|\\.)*)"$* · Example: `Given the local storage "user" is set to "Alice"`
698
+ - *^(?:the )?local storage "((?:[^"\\]|\\.)*)" is removed$* · Example: `Given the local storage "user" is removed`
679
699
  - *^local storage is cleared$* · Example: `Given local storage is cleared`
680
- - *^(?:the )?session storage "([^"]*)" is set to "([^"]*)"$* · Example: `Given the session storage "checkout step" is set to "2"`
681
- - *^(?:the )?session storage "([^"]*)" is removed$* · Example: `Given the session storage "checkout step" is removed`
700
+ - *^(?:the )?session storage "((?:[^"\\]|\\.)*)" is set to "((?:[^"\\]|\\.)*)"$* · Example: `Given the session storage "checkout step" is set to "2"`
701
+ - *^(?:the )?session storage "((?:[^"\\]|\\.)*)" is removed$* · Example: `Given the session storage "checkout step" is removed`
682
702
  - *^session storage is cleared$* · Example: `Given session storage is cleared`
683
703
 
704
+ A key or a value may hold a double quote written `\"`, as in a JSON value: `Given the local storage "prefs" is set to "{\"theme\":\"dark\"}"`.
705
+
706
+ Local and session storage belong to the site of the page, so their steps need a page of the site first: before the first `Given I am on "…"` the page is blank, and the step fails with a hint to open one. A cookie can be set before any page.
707
+
684
708
  ### table.steps.js
685
709
 
686
710
  - *the table {string} should have {int} row(s)* · Example: `Then the table "#users" should have 5 rows`
@@ -763,6 +787,8 @@ This index lists every public step grouped by source file, with one Gherkin exam
763
787
 
764
788
  ### yaml.steps.js
765
789
 
790
+ The numeric steps (greater than, less than, between) compare a YAML number only: a quoted `"3"`, `true` or `null` fails with its type, where `Number()` would have read 3, 1 or 0.
791
+
766
792
  - *the YAML response content from the file {string}* · Example: `Given the YAML response content from the file "config.yml"`
767
793
  - *the YAML response content is the following:* · Example: `Given the YAML response content is the following:`
768
794
  - *the active YAML document is {int}* · Example: `Given the active YAML document is 1`