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.
- package/.github/ISSUE_TEMPLATE/issue.md +37 -0
- package/.github/PULL_REQUEST_TEMPLATE.md +24 -0
- package/.github/workflows/github-actions.yml +56 -4
- package/CLAUDE.md +5 -2
- package/README.md +13 -1
- package/bin/generate-reports.js +51 -7
- package/bin/init-webship.js +85 -17
- package/cucumber.js +29 -1
- package/docs/00-quick-start.md +30 -7
- package/docs/02-bbr-smart-waits.md +6 -0
- package/docs/04-step-reference.md +2 -2
- package/docs/09-api-testing.md +9 -2
- package/docs/11-debugging.md +21 -0
- package/docs/12-ai-agent-guide.md +3 -1
- package/docs/13-faq.md +3 -0
- package/docs/15-tag-conventions.md +4 -1
- package/docs/16-ci-cd.md +29 -13
- package/docs/api-step-definitions.md +13 -2
- package/docs/global-settings.md +2 -2
- package/docs/install-webship-js/ddev-webship-js.md +3 -0
- package/docs/install-webship-js.md +14 -2
- package/examples/a11y-legacy-widget.html +34 -0
- package/examples/auth-state.html +42 -0
- package/examples/clock.html +33 -0
- package/examples/downloads/webship-archive.zip +0 -0
- package/examples/downloads/webship-notes.txt +4 -0
- package/examples/downloads/webship-report.csv +4 -0
- package/examples/downloads.html +16 -0
- package/examples/element-viewport.html +42 -0
- package/examples/field-types.html +98 -0
- package/examples/iframe-newsletter.html +29 -0
- package/examples/iframe-order.html +26 -0
- package/examples/iframe.html +21 -0
- package/examples/javascript-errors.html +35 -0
- package/examples/links.html +1 -0
- package/examples/metatags.html +18 -0
- package/examples/mouse-and-pointer.html +83 -0
- package/examples/native-dialogs.html +8 -0
- package/examples/network.html +83 -0
- package/examples/scroll-horizontal.html +50 -0
- package/examples/selectors-position.html +29 -0
- package/examples/storage.html +57 -0
- package/examples/viewport-size.html +24 -0
- package/examples/wait-conditions.html +69 -0
- package/examples/web-first.html +99 -0
- package/package.json +9 -2
- package/tests/assets/catalog.xml +19 -0
- package/tests/assets/feed-namespaced.xml +13 -0
- package/tests/assets/sitemap.xml +14 -0
- package/tests/assets/webship-site-expected.yaml +21 -0
- package/tests/assets/webship-site.schema.json +46 -0
- package/tests/assets/webship-site.yaml +21 -0
- package/tests/check-examples.js +235 -0
- package/tests/check-must-fail.js +84 -0
- package/tests/check-paths.js +82 -0
- package/tests/check-report.js +119 -0
- package/tests/check-scaffold.js +211 -0
- package/tests/features/a11y.feature +18 -0
- package/tests/features/auth-state.feature +32 -0
- package/tests/features/clock.feature +27 -0
- package/tests/features/cookie.feature +9 -0
- package/tests/features/dialog.feature +27 -0
- package/tests/features/element.feature +47 -0
- package/tests/features/field.feature +104 -0
- package/tests/features/file-download.feature +64 -0
- package/tests/features/iframe.feature +83 -0
- package/tests/features/javascript.feature +47 -0
- package/tests/features/link.feature +11 -0
- package/tests/features/metatag.feature +38 -0
- package/tests/features/mouse-and-pointer.feature +86 -0
- package/tests/features/network-mocking.feature +80 -0
- package/tests/features/responsive.feature +27 -0
- package/tests/features/rest-and-api-requests.feature +120 -0
- package/tests/features/scroll-horizontal.feature +55 -0
- package/tests/features/selectors-position.feature +41 -0
- package/tests/features/storage.feature +98 -0
- package/tests/features/test--then--i-see-locator.feature +13 -0
- package/tests/features/test--then--i-should--see-text-in-element.feature +9 -1
- package/tests/features/test--then--the-field-should-contain-value.feature +8 -0
- package/tests/features/video.feature +1 -0
- package/tests/features/wait.feature +89 -0
- package/tests/features/web-first.feature +100 -0
- package/tests/features/xml.feature +96 -0
- package/tests/features/yaml.feature +75 -0
- package/tests/must-fail/assertions.feature +96 -0
- package/tests/must-fail/waits.feature +51 -0
- package/tests/reports/README.md +2 -2
- package/tests/step-definitions/a11y.steps.js +12 -8
- package/tests/step-definitions/api.steps.js +18 -45
- package/tests/step-definitions/assertion.steps.js +235 -61
- package/tests/step-definitions/dialog.steps.js +2 -2
- package/tests/step-definitions/element.steps.js +3 -1
- package/tests/step-definitions/field.steps.js +152 -22
- package/tests/step-definitions/file-download.steps.js +74 -10
- package/tests/step-definitions/rest.steps.js +23 -12
- package/tests/step-definitions/screenshot.steps.js +1 -1
- package/tests/step-definitions/selectors.steps.js +9 -3
- package/tests/step-definitions/storage.steps.js +3 -3
- package/tests/step-definitions/wait.steps.js +129 -39
- package/tests/step-definitions/webship.js +211 -3
- package/tests/step-definitions/xml.steps.js +76 -14
- 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:
|
|
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@
|
|
32
|
+
uses: actions/checkout@v7
|
|
16
33
|
|
|
17
34
|
- name: Set up Node.js
|
|
18
|
-
uses: actions/setup-node@
|
|
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:
|
|
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,
|
|
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
|
|
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`.
|
package/bin/generate-reports.js
CHANGED
|
@@ -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}`);
|
package/bin/init-webship.js
CHANGED
|
@@ -8,7 +8,32 @@ const { spawnSync } = require('child_process');
|
|
|
8
8
|
|
|
9
9
|
const packagePath = path.join(__dirname, '..');
|
|
10
10
|
|
|
11
|
-
const CUCUMBER_JS =
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
275
|
-
const
|
|
276
|
-
|
|
277
|
-
|
|
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
|
-
|
|
321
|
-
|
|
322
|
-
|
|
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',
|
package/docs/00-quick-start.md
CHANGED
|
@@ -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
|
-
|
|
45
|
-
|
|
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)
|
|
709
|
-
- *^(I |we )*wait max of (\d+)( minute| minutes|m)
|
|
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`
|
package/docs/09-api-testing.md
CHANGED
|
@@ -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.
|
|
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"
|
package/docs/11-debugging.md
CHANGED
|
@@ -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:
|
|
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
|
|