webship-js 2.0.9 → 2.0.11

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 (102) hide show
  1. package/.github/ISSUE_TEMPLATE/issue.md +37 -0
  2. package/.github/PULL_REQUEST_TEMPLATE.md +24 -0
  3. package/.github/workflows/github-actions.yml +56 -4
  4. package/CLAUDE.md +5 -2
  5. package/README.md +13 -1
  6. package/bin/generate-reports.js +51 -7
  7. package/bin/init-webship.js +85 -17
  8. package/cucumber.js +29 -1
  9. package/docs/00-quick-start.md +30 -7
  10. package/docs/02-bbr-smart-waits.md +6 -0
  11. package/docs/04-step-reference.md +2 -2
  12. package/docs/09-api-testing.md +9 -2
  13. package/docs/11-debugging.md +21 -0
  14. package/docs/12-ai-agent-guide.md +3 -1
  15. package/docs/13-faq.md +3 -0
  16. package/docs/15-tag-conventions.md +4 -1
  17. package/docs/16-ci-cd.md +29 -13
  18. package/docs/api-step-definitions.md +13 -2
  19. package/docs/global-settings.md +2 -2
  20. package/docs/install-webship-js/ddev-webship-js.md +3 -0
  21. package/docs/install-webship-js.md +14 -2
  22. package/examples/a11y-legacy-widget.html +34 -0
  23. package/examples/auth-state.html +42 -0
  24. package/examples/clock.html +33 -0
  25. package/examples/downloads/webship-archive.zip +0 -0
  26. package/examples/downloads/webship-notes.txt +4 -0
  27. package/examples/downloads/webship-report.csv +4 -0
  28. package/examples/downloads.html +16 -0
  29. package/examples/element-viewport.html +42 -0
  30. package/examples/field-types.html +98 -0
  31. package/examples/iframe-newsletter.html +29 -0
  32. package/examples/iframe-order.html +26 -0
  33. package/examples/iframe.html +21 -0
  34. package/examples/javascript-errors.html +35 -0
  35. package/examples/links.html +1 -0
  36. package/examples/metatags.html +18 -0
  37. package/examples/mouse-and-pointer.html +83 -0
  38. package/examples/native-dialogs.html +8 -0
  39. package/examples/network.html +83 -0
  40. package/examples/scroll-horizontal.html +50 -0
  41. package/examples/selectors-position.html +29 -0
  42. package/examples/storage.html +57 -0
  43. package/examples/viewport-size.html +24 -0
  44. package/examples/wait-conditions.html +69 -0
  45. package/examples/web-first.html +99 -0
  46. package/package.json +9 -2
  47. package/tests/assets/catalog.xml +19 -0
  48. package/tests/assets/feed-namespaced.xml +13 -0
  49. package/tests/assets/sitemap.xml +14 -0
  50. package/tests/assets/webship-site-expected.yaml +21 -0
  51. package/tests/assets/webship-site.schema.json +46 -0
  52. package/tests/assets/webship-site.yaml +21 -0
  53. package/tests/check-examples.js +235 -0
  54. package/tests/check-must-fail.js +84 -0
  55. package/tests/check-paths.js +82 -0
  56. package/tests/check-report.js +119 -0
  57. package/tests/check-scaffold.js +211 -0
  58. package/tests/features/a11y.feature +18 -0
  59. package/tests/features/auth-state.feature +32 -0
  60. package/tests/features/clock.feature +27 -0
  61. package/tests/features/cookie.feature +9 -0
  62. package/tests/features/dialog.feature +27 -0
  63. package/tests/features/element.feature +47 -0
  64. package/tests/features/field.feature +104 -0
  65. package/tests/features/file-download.feature +64 -0
  66. package/tests/features/iframe.feature +83 -0
  67. package/tests/features/javascript.feature +47 -0
  68. package/tests/features/link.feature +11 -0
  69. package/tests/features/metatag.feature +38 -0
  70. package/tests/features/mouse-and-pointer.feature +86 -0
  71. package/tests/features/network-mocking.feature +80 -0
  72. package/tests/features/responsive.feature +27 -0
  73. package/tests/features/rest-and-api-requests.feature +120 -0
  74. package/tests/features/scroll-horizontal.feature +55 -0
  75. package/tests/features/selectors-position.feature +41 -0
  76. package/tests/features/storage.feature +98 -0
  77. package/tests/features/test--then--i-see-locator.feature +13 -0
  78. package/tests/features/test--then--i-should--see-text-in-element.feature +9 -1
  79. package/tests/features/test--then--the-field-should-contain-value.feature +8 -0
  80. package/tests/features/video.feature +1 -0
  81. package/tests/features/wait.feature +89 -0
  82. package/tests/features/web-first.feature +100 -0
  83. package/tests/features/xml.feature +96 -0
  84. package/tests/features/yaml.feature +75 -0
  85. package/tests/must-fail/assertions.feature +96 -0
  86. package/tests/must-fail/waits.feature +51 -0
  87. package/tests/reports/README.md +2 -2
  88. package/tests/step-definitions/a11y.steps.js +12 -8
  89. package/tests/step-definitions/api.steps.js +18 -45
  90. package/tests/step-definitions/assertion.steps.js +235 -61
  91. package/tests/step-definitions/dialog.steps.js +2 -2
  92. package/tests/step-definitions/element.steps.js +3 -1
  93. package/tests/step-definitions/field.steps.js +152 -22
  94. package/tests/step-definitions/file-download.steps.js +74 -10
  95. package/tests/step-definitions/rest.steps.js +23 -12
  96. package/tests/step-definitions/screenshot.steps.js +1 -1
  97. package/tests/step-definitions/selectors.steps.js +9 -3
  98. package/tests/step-definitions/storage.steps.js +3 -3
  99. package/tests/step-definitions/wait.steps.js +129 -39
  100. package/tests/step-definitions/webship.js +211 -3
  101. package/tests/step-definitions/xml.steps.js +76 -14
  102. package/tests/step-definitions/yaml.steps.js +46 -27
@@ -0,0 +1,37 @@
1
+ ---
2
+ name: Issue
3
+ about: Report a problem or propose an addition, change, update or fix
4
+ ---
5
+
6
+ ### Problem/Motivation
7
+
8
+ <!-- What is wrong or missing, with the exact step phrase, error text or value. -->
9
+
10
+ #### Steps to reproduce
11
+
12
+ <!-- 1. ... 2. ... 3. ... -->
13
+
14
+ ### Proposed resolution
15
+
16
+ <!-- What should change, naming the file, step or setting. -->
17
+
18
+ ### Checkpoints:
19
+ - [ ] File an issue
20
+ - [ ] Addition/Change/Update/Fix
21
+ - [ ] Testing to ensure no regression
22
+ - [ ] Automated unit testing coverage
23
+ - [ ] Automated functional testing coverage
24
+ - [ ] UX/UI designer responsibilities
25
+ - [ ] Readability
26
+ - [ ] Accessibility
27
+ - [ ] Performance
28
+ - [ ] Security
29
+ - [ ] Developer Documentation
30
+ - [ ] User Guide Documentation
31
+ - [ ] Reviewed by human
32
+ - [ ] Code review by maintainers
33
+ - [ ] Full testing and approval
34
+ - [ ] Credit contributors
35
+ - [ ] Review with the product owner
36
+ - [ ] Release notes snippet
37
+ - [ ] Release
@@ -0,0 +1,24 @@
1
+ <!-- What changes, in two or three plain sentences, and one line of proof (scenarios and steps run, results). -->
2
+
3
+ Closes #
4
+
5
+ ### Checkpoints:
6
+ - [ ] File an issue
7
+ - [ ] Addition/Change/Update/Fix
8
+ - [ ] Testing to ensure no regression
9
+ - [ ] Automated unit testing coverage
10
+ - [ ] Automated functional testing coverage
11
+ - [ ] UX/UI designer responsibilities
12
+ - [ ] Readability
13
+ - [ ] Accessibility
14
+ - [ ] Performance
15
+ - [ ] Security
16
+ - [ ] Developer Documentation
17
+ - [ ] User Guide Documentation
18
+ - [ ] Reviewed by human
19
+ - [ ] Code review by maintainers
20
+ - [ ] Full testing and approval
21
+ - [ ] Credit contributors
22
+ - [ ] Review with the product owner
23
+ - [ ] Release notes snippet
24
+ - [ ] Release
@@ -1,10 +1,27 @@
1
1
  name: Github Actions
2
2
 
3
- on: [push]
3
+ on:
4
+ push:
5
+ branches: [2.0.x]
6
+ pull_request:
7
+ branches: [2.0.x]
8
+ workflow_dispatch: {}
9
+
10
+ permissions:
11
+ contents: read
12
+
13
+ # The runs of a pull request share a group, so a newer push cancels the run
14
+ # it supersedes. Every other run (a push to 2.0.x, a run started by hand)
15
+ # gets a group of its own: it is never queued behind another run, and never
16
+ # cancelled.
17
+ concurrency:
18
+ group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
19
+ cancel-in-progress: true
4
20
 
5
21
  jobs:
6
22
  build:
7
23
  runs-on: ubuntu-latest
24
+ timeout-minutes: 45
8
25
 
9
26
  env:
10
27
  TEST_BASE_URL: http://localhost:8080
@@ -12,24 +29,59 @@ jobs:
12
29
 
13
30
  steps:
14
31
  - name: Checkout repository
15
- uses: actions/checkout@v3
32
+ uses: actions/checkout@v7
16
33
 
17
34
  - name: Set up Node.js
18
- uses: actions/setup-node@v3
35
+ uses: actions/setup-node@v7
19
36
  with:
20
37
  node-version: '20.x'
38
+ cache: npm
39
+ cache-dependency-path: package.json
21
40
 
22
41
  - name: Install dependencies
23
42
  run: npm install
24
43
 
44
+ - name: Check the HTML report
45
+ run: npm run test:report
46
+
25
47
  - name: Install Playwright browsers
26
48
  run: npx playwright install --with-deps chromium
27
49
 
50
+ - name: Check the step examples and the feature steps
51
+ run: npm run test:examples
52
+
53
+ - name: Check that a feature named on the command line runs alone
54
+ run: npm run test:paths
55
+
28
56
  - name: Start virtual server
29
57
  run: npm start &
30
58
 
31
59
  - name: Wait for server
32
- run: sleep 3
60
+ run: |
61
+ for i in $(seq 1 30); do
62
+ curl -s -o /dev/null "$TEST_BASE_URL/" && exit 0
63
+ sleep 1
64
+ done
65
+ echo "The server did not answer on $TEST_BASE_URL in 30 seconds" >&2
66
+ exit 1
67
+
68
+ - name: Check the failures that must fail and their messages
69
+ run: npm run test:must-fail
33
70
 
34
71
  - name: Run tests
35
72
  run: npm test
73
+
74
+ - name: Check the scaffold of a new project
75
+ run: npm run test:scaffold
76
+
77
+ - name: Upload the report, screenshots and videos
78
+ if: always()
79
+ uses: actions/upload-artifact@v7
80
+ with:
81
+ name: cucumber-report
82
+ path: |
83
+ tests/reports/
84
+ screenshots/
85
+ videos/
86
+ retention-days: 14
87
+ if-no-files-found: ignore
package/CLAUDE.md CHANGED
@@ -38,6 +38,9 @@ suite — nearly every bundled feature loads a static fixture from `examples/`.
38
38
  | `npm run test:fast` | `SLOW_MO=0`. |
39
39
  | `npm run test:chromium` / `:firefox` / `:webkit` | Pick the browser (same as `BROWSER=…`). |
40
40
  | `npx cucumber-js --dry-run` | Ambiguity / undefined-step check. Run this before declaring done. |
41
+ | `npm run test:examples` | No browser: every step definition is documented, every `Example #n:` step and every feature step resolves to exactly one definition. |
42
+ | `npm run test:must-fail` | Runs the scenarios of `tests/must-fail/` (they must fail) and checks each failure message: what was looked for, the page, a hint. Needs `npm start`. |
43
+ | `npm run test:paths` | No browser: a feature or a scenario (`file:line`) named on the command line runs alone; naming none runs the whole suite. |
41
44
  | `npm run generate-reports` | HTML (+ optional PDF) report from `tests/reports/cucumber_report.json`. |
42
45
 
43
46
  Targeting a subset:
@@ -481,7 +484,7 @@ the workspace repos and installed into `~/.claude/`:
481
484
 
482
485
  | Agent | Model | Scope |
483
486
  | --- | --- | --- |
484
- | `agent-webship-js` | opus | The full specialist. Scaffold (Node.js or DDEV) → author `.feature` files → write custom steps → run → debug → HTML/PDF report. Carries a distilled copy of the whole step catalog, the BBR/selector/tag sections, the 20-recipe cookbook, Varbase learnings, and recipes AI-1…AI-5. Use for anything non-trivial. |
487
+ | `agent-webship-js` | opus | The full specialist. Scaffold (Node.js or DDEV) → author `.feature` files → write custom steps → run → debug → HTML/PDF report. Carries a distilled copy of the whole step catalog, the BBR/selector/tag sections, the 20-recipe cookbook, project learnings, and recipes AI-1…AI-5. Use for anything non-trivial. |
485
488
  | `webship-ai-agent` | sonnet | The loop-until-green worker for a consumer project: read available steps → write/fix scenarios → run → fix root cause → iterate to zero failures. Lighter, autonomous, Drupal/DDEV-flavoured (`NN-NN-NN-name.feature`, `https://<project>.ddev.site`). |
486
489
 
487
490
  ### Skills (slash commands)
@@ -519,7 +522,7 @@ copies be re-derived.
519
522
  3. **Known drift to be aware of, not to "fix" here:** the agents and the
520
523
  `/webship-js-run` skill reference a `worldParameters.users` registry and
521
524
  an auth helper built on it. There is no `users` key in this repo's
522
- `cucumber.js` or in `bin/init-webship.js` — it is a Varbase-project
525
+ `cucumber.js` or in `bin/init-webship.js` — it is a project-level
523
526
  convention layered on top. If a user asks about `users`, say so rather
524
527
  than adding the key on the agents' say-so.
525
528
  4. **Guardrails they already carry** (so don't re-litigate them): never
package/README.md CHANGED
@@ -18,8 +18,20 @@ All you need to know is at [webship-js Docs](https://webship.co/docs/webship-js/
18
18
  npm install webship-js
19
19
  ```
20
20
 
21
+ The install script of the package scaffolds the test project. When npm skips it (npm warns that webship-js has "install scripts not yet covered by allowScripts", or `--ignore-scripts` is set), scaffold it with:
22
+
23
+ ```
24
+ npx init-webship-js
25
+ ```
26
+
27
+ `npm install-scripts approve webship-js` lets the install script run on the next installs.
28
+
21
29
  ## Automated Functional Acceptance Testing
22
30
 
31
+ The install scaffolds the test project (`cucumber.js`, `playwright.config.ts`, `tests/`) with a starter feature that opens the home page of your site:
32
+
23
33
  ```
24
- npm test
34
+ LAUNCH_URL=https://your-site.example npm test
25
35
  ```
36
+
37
+ Without `LAUNCH_URL` the suite opens `http://localhost:8080`.
@@ -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'],
@@ -125,14 +149,17 @@ const TSCONFIG_JSON = {
125
149
  },
126
150
  };
127
151
 
152
+ // The starter feature passes on any site that answers on the launch URL
153
+ // (LAUNCH_URL, default http://localhost:8080): it asserts nothing about the
154
+ // content of a site the scaffold cannot know.
128
155
  const FEATURE_SAMPLE = `Feature: Check the home page
129
- As a nonymouse user
156
+ As an anonymous user
130
157
  I want to be able to visit the home page
131
158
  So that I know that the site is working
132
159
 
133
160
  Scenario: Check homepage
134
161
  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."
162
+ Then I should be on the homepage
136
163
  `;
137
164
 
138
165
  const CUSTOM_STEP_JS = `const { Given, When, Then } = require('@cucumber/cucumber');
@@ -156,9 +183,15 @@ const TEST_SCRIPTS = {
156
183
  'test:chromium': 'BROWSER=chromium cucumber-js --config cucumber.js',
157
184
  'test:firefox': 'BROWSER=firefox cucumber-js --config cucumber.js',
158
185
  'test:webkit': 'BROWSER=webkit cucumber-js --config cucumber.js',
186
+ 'test:headed': 'HEADLESS=false cucumber-js --config cucumber.js',
187
+ 'test:fast': 'SLOW_MO=0 cucumber-js --config cucumber.js',
159
188
  'generate-reports': 'generate-reports',
160
189
  };
161
190
 
191
+ // The `test` script `npm init` writes. It is a placeholder, not a choice of
192
+ // the project, so the scaffold replaces it.
193
+ const NPM_PLACEHOLDER_TEST = /^echo "Error: no test specified" && exit 1$/;
194
+
162
195
  const DEFAULT_PKG = {
163
196
  name: 'project-name',
164
197
  version: '2.0.0',
@@ -195,7 +228,7 @@ function printHelp() {
195
228
  '',
196
229
  'Options:',
197
230
  ' -f, --force Overwrite existing files',
198
- ' --skip-browsers Skip `playwright install chromium`',
231
+ ' --skip-browsers Skip `npx playwright install chromium`',
199
232
  ' --cwd <dir> Target directory (default: $INIT_CWD or cwd)',
200
233
  ' -h, --help Show this help',
201
234
  '',
@@ -256,7 +289,8 @@ function ensurePackageJson(projectPath, opts) {
256
289
 
257
290
  pkg.scripts = pkg.scripts || {};
258
291
  for (const [name, cmd] of Object.entries(TEST_SCRIPTS)) {
259
- if (opts.force || !pkg.scripts[name]) {
292
+ const placeholder = name === 'test' && NPM_PLACEHOLDER_TEST.test(String(pkg.scripts[name] || '').trim());
293
+ if (opts.force || !pkg.scripts[name] || placeholder) {
260
294
  pkg.scripts[name] = cmd;
261
295
  }
262
296
  }
@@ -270,13 +304,21 @@ function ensurePackageJson(projectPath, opts) {
270
304
  return { created: !existed };
271
305
  }
272
306
 
307
+ // The browser itself goes into the Playwright cache of the user: no special
308
+ // rights are needed. The system libraries it runs on need root, so they are
309
+ // installed with it only when the scaffold already runs as root (a container,
310
+ // a CI job); otherwise the user is told how to add them.
311
+ function isRoot() {
312
+ return typeof process.getuid === 'function' && process.getuid() === 0;
313
+ }
314
+
273
315
  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
- );
316
+ console.log('\n [webship-js] Installing the Playwright browser (Chromium)...\n');
317
+ const win = process.platform === 'win32';
318
+ const args = ['playwright', 'install'].concat(isRoot() ? ['--with-deps'] : [], ['chromium']);
319
+ const res = win
320
+ ? spawnSync(`npx ${args.join(' ')}`, { cwd: projectPath, stdio: 'inherit', shell: true })
321
+ : spawnSync('npx', args, { cwd: projectPath, stdio: 'inherit' });
280
322
  return res.status === 0;
281
323
  }
282
324
 
@@ -317,9 +359,35 @@ function run(argv) {
317
359
  ` [${pkgResult.created ? 'wrote ' : 'merged'}] package.json`
318
360
  );
319
361
 
320
- if (!opts.skipBrowsers) installBrowsers(projectPath);
321
-
322
- console.log('\n [webship-js] Setup complete!\n');
362
+ const browsersInstalled = opts.skipBrowsers || installBrowsers(projectPath);
363
+
364
+ if (!browsersInstalled) {
365
+ console.log(
366
+ [
367
+ '',
368
+ ' [webship-js] The project files are in place, but the browser was NOT installed.',
369
+ ' Install it before the first run:',
370
+ '',
371
+ ' npx playwright install chromium',
372
+ '',
373
+ ].join('\n')
374
+ );
375
+ } else {
376
+ console.log('\n [webship-js] Setup complete!');
377
+ }
378
+ console.log(
379
+ [
380
+ '',
381
+ ' Run the starter feature against your site:',
382
+ '',
383
+ ' LAUNCH_URL=https://your-site.example npm test',
384
+ '',
385
+ ' If the browser does not start for a missing system library (Linux):',
386
+ '',
387
+ ' sudo npx playwright install-deps chromium',
388
+ '',
389
+ ].join('\n')
390
+ );
323
391
  }
324
392
 
325
393
  if (require.main === module) {
package/cucumber.js CHANGED
@@ -1,3 +1,31 @@
1
+ // A feature file, a scenario (file:line), a folder or a rerun file named on
2
+ // the command line of cucumber-js runs alone. cucumber-js 12 adds the paths
3
+ // of the command line to the `paths` of this file instead of using them
4
+ // alone, so `paths` is left empty when the command line names any: what
5
+ // cucumber-js announces for its next major version.
6
+ const OPTIONS_WITH_A_VALUE = new Set([
7
+ '-c', '--config', '-f', '--format', '--format-options', '--i18n-keywords',
8
+ '-i', '--import', '-l', '--loader', '--language', '--name', '--order',
9
+ '-p', '--profile', '--parallel', '--plugin', '--plugin-options',
10
+ '-r', '--require', '--require-module', '--retry', '--retry-tag-filter',
11
+ '--shard', '-t', '--tags', '--world-parameters',
12
+ ]);
13
+
14
+ function commandLinePaths() {
15
+ // Only when cucumber-js itself runs, not when another script reads this file.
16
+ if (!/cucumber(-js|\.js)?$/.test(String(process.argv[1] || ''))) return [];
17
+ const args = process.argv.slice(2);
18
+ const paths = [];
19
+ for (let i = 0; i < args.length; i += 1) {
20
+ if (args[i].startsWith('-')) {
21
+ if (OPTIONS_WITH_A_VALUE.has(args[i])) i += 1;
22
+ } else {
23
+ paths.push(args[i]);
24
+ }
25
+ }
26
+ return paths;
27
+ }
28
+
1
29
  module.exports = {
2
30
  default: {
3
31
  // Cucumber step timeout must exceed Playwright's default 30s so the
@@ -14,7 +42,7 @@ module.exports = {
14
42
  require: [
15
43
  'tests/step-definitions/**/*.js',
16
44
  ],
17
- paths: ['tests/features/**/*.feature'],
45
+ paths: commandLinePaths().length ? [] : ['tests/features/**/*.feature'],
18
46
  format: [
19
47
  '@cucumber/pretty-formatter',
20
48
  'json:tests/reports/cucumber_report.json',
@@ -27,7 +27,7 @@ code. No selector jargon.
27
27
  * **Automatic smart waits** — every action waits for the page to
28
28
  settle. No `sleep` / `wait 5s` needed in the happy path.
29
29
  * **HTML report** — runs auto-generate `tests/reports/cucumber_report.html`.
30
- * **Screenshots on failure** — saved to `screenshots/` for instant
30
+ * **Screenshots on failure** — saved to `tests/screenshots/` for instant
31
31
  debugging.
32
32
 
33
33
  ## 30-second install
@@ -37,19 +37,42 @@ npm install webship-js --save-dev
37
37
  ```
38
38
 
39
39
  The post-install script copies a starter `cucumber.js`,
40
- `playwright.config.ts`, and `tests/` skeleton.
40
+ `playwright.config.ts`, and `tests/` skeleton, adds the `test` scripts to
41
+ `package.json`, and downloads Chromium into the Playwright cache. If it
42
+ reports that the browser was not installed, run:
43
+
44
+ ```bash
45
+ npx playwright install chromium
46
+ ```
47
+
48
+ When npm skips install scripts (it warns that webship-js has "install
49
+ scripts not yet covered by allowScripts", or `--ignore-scripts` is set),
50
+ nothing is copied and `npm test` answers `Error: no test specified`. Run
51
+ the same scaffold by hand, then let the script run on the next installs:
52
+
53
+ ```bash
54
+ npx init-webship-js
55
+ npm install-scripts approve webship-js
56
+ ```
57
+
58
+ Firefox and WebKit are optional: `npx playwright install firefox webkit`.
41
59
 
42
60
  ## 60-second first test
43
61
 
44
- 1. Drop your scenario into `tests/features/smoke.feature`.
45
- 2. Make sure your dev server is running on `http://localhost:8080`
46
- (or set `LAUNCH_URL` to point elsewhere).
47
- 3. Run:
62
+ The skeleton comes with `tests/features/check-homepage.feature`, which
63
+ opens the home page of your site. Run it first:
48
64
 
49
65
  ```bash
50
- npm test
66
+ LAUNCH_URL=https://your-site.example npm test
51
67
  ```
52
68
 
69
+ Without `LAUNCH_URL` the suite opens `http://localhost:8080`.
70
+
71
+ Then:
72
+
73
+ 1. Drop your scenario into `tests/features/smoke.feature`.
74
+ 2. Run `npm test` again.
75
+
53
76
  If your scenario passes, you're done. If it fails, the Cucumber output
54
77
  names the step that failed and the expected vs actual.
55
78
 
@@ -23,6 +23,12 @@ __webshipAjaxCount === 0
23
23
 
24
24
  …or when `budget` elapses, whichever comes first.
25
25
 
26
+ The probe is polled from Node (`page.evaluate` in a loop), never from a timer
27
+ inside the page. A poll that ran on the page's own `setTimeout` would be counted
28
+ in `__webshipPendingTimers` like any other timer, so the wait would see its own
29
+ next poll and never find the page quiet. `When I wait until pending timers settle`
30
+ reads the count the same way.
31
+
26
32
  ### How the budget is shared
27
33
 
28
34
  Each phase is best-effort — a phase that times out is not a failure — and each
@@ -705,8 +705,8 @@ This index lists every public step grouped by source file, with one Gherkin exam
705
705
  - *^(I |we )*wait for (\d+) seconds? for AJAX to finish$* · Example: `When I wait for 1 second for AJAX to finish`
706
706
  - *^(I |we )*wait (\d+)( second| seconds|s)?$* · Example: `When I wait 1 second`
707
707
  - *^(I |we )*wait max of (\d+)( second| seconds|s)?$* · Example: `When I wait max of 1 second`
708
- - *^(I |we )*wait (\d+)( minute| minutes|m)?$* · Example: `When I wait 1 minute`
709
- - *^(I |we )*wait max of (\d+)( minute| minutes|m)?$* · Example: `When I wait max of 1 minute`
708
+ - *^(I |we )*wait (\d+)( minute| minutes|m)$* · Example: `When I wait 1 minute`
709
+ - *^(I |we )*wait max of (\d+)( minute| minutes|m)$* · Example: `When I wait max of 1 minute`
710
710
  - *^(I |we )*wait until( the)* page( is)* loaded*$* · Example: `When I wait until the page is loaded`
711
711
  - *^(I |we )*wait for AJAX to finish$* · Example: `When I wait for AJAX to finish`
712
712
  - *^(I |we )*wait for( the)* modal( dialog)* to (appear|disappear)$* · Example: `When I wait for the modal to appear`
@@ -1,6 +1,13 @@
1
1
  # API Testing
2
2
 
3
- Webship-js scenarios can talk to an HTTP API directly without leaving the cucumber-js runtime. The browser context's cookie jar is shared, so a UI login can be followed by REST-level assertions in the same scenario.
3
+ Webship-js scenarios can talk to an HTTP API directly without leaving the cucumber-js runtime. Every request is sent with Playwright's request API and follows the HTTPS setting of the browser context (`ignoreHTTPSErrors` in `playwright.config.ts`), so a site served with a self-signed or locally issued certificate answers these steps the same way it answers the browser.
4
+
5
+ There are two families of steps, and they differ in one point:
6
+
7
+ | Steps | Sent | Cookies of the browser |
8
+ | --- | --- | --- |
9
+ | `I send a REST "<method>" request to "<url>"` (`rest.steps.js`) | through the browser context | shared: a UI login can be followed by REST-level assertions in the same scenario |
10
+ | `I send a <METHOD> request to "<endpoint>"` (`api.steps.js`) | outside the browser session | not sent, and none comes back into the browser: the request carries only the base URL, the authentication and the headers the scenario set |
4
11
 
5
12
  ## Setting headers and base URL
6
13
 
@@ -96,7 +103,7 @@ Given the basic authentication with the username "admin" and the password "secre
96
103
 
97
104
  ## Short-form REST steps
98
105
 
99
- A parallel short-form lives in `rest.steps.js` for quick smoke tests:
106
+ A parallel short-form lives in `rest.steps.js` for quick smoke tests. A path is joined to the launch URL, an absolute URL is requested as written, and the request goes through the browser context: it shares the session cookies and the HTTPS setting of the page.
100
107
 
101
108
  ```gherkin
102
109
  Given a REST header "Authorization" with value "Bearer abc123"
@@ -118,6 +118,27 @@ contextOptions: {
118
118
  }
119
119
  ```
120
120
 
121
+ ## Reading a failure
122
+
123
+ The text, element, link, CSS and response assertions and the targeted waits fail with one shape: what was looked for and for how long, what was found where that helps, the address of the page, and a hint.
124
+
125
+ ```
126
+ ✖ Then I should see "Completely different words" in the "h1" element
127
+ The element "h1" does not contain "Completely different words".
128
+ Found: "About Us"
129
+ Page: http://localhost:8080/about-us.html
130
+ Hint: check the spelling and the letter case; for a field the step reads its value.
131
+ ```
132
+
133
+ ```
134
+ ✖ When I wait for the text "Never arrives" to appear
135
+ The text "Never arrives" did not appear within 10 seconds.
136
+ Page: http://localhost:8080/about-us.html
137
+ Hint: check the spelling and the letter case; the step reads the visible text of the page.
138
+ ```
139
+
140
+ `tests/must-fail/` holds scenarios that must fail, each with the message it must fail with (`Fails with: …` in its description). `npm run test:must-fail` runs them against the `examples/` pages and checks the message, the page and the hint; CI runs it before the suite. A step whose failure message changes gets its must-fail scenario updated in the same change.
141
+
121
142
  ## Common diagnoses
122
143
 
123
144
  | Symptom | Likely cause | Fix |
@@ -209,7 +209,9 @@ When asked to add a custom step:
209
209
  4. Add a JSDoc block with at least 5 `Example #N:` Gherkin lines that
210
210
  match the step pattern.
211
211
  5. Use plain English in the step text. No camelCase identifiers.
212
- 6. Run the audit: every example must match its step pattern.
212
+ 6. Run the audit: `npm run test:examples`. It fails when a definition has
213
+ no JSDoc description or no example, when a step line of an example
214
+ matches no definition or more than one, and when a feature step does.
213
215
 
214
216
  ### Recipe AI-3: Maintain tests after a UI change
215
217