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.
- package/.circleci/config.yml +10 -1
- package/.drone.yml +7 -7
- package/.github/workflows/github-actions.yml +45 -0
- package/.gitlab-ci.yml +9 -4
- package/.harness/webship-js-pipeline.yml +5 -6
- package/.semaphore/semaphore.yml +6 -9
- package/.teamcity/settings.kts +7 -6
- package/.travis.yml +6 -1
- package/AGENTS.md +1 -1
- package/CLAUDE.md +65 -23
- package/Jenkinsfile +5 -3
- package/azure-pipelines.yml +17 -8
- package/bamboo-specs/bamboo.yml +9 -15
- package/bin/init-webship.js +44 -8
- package/bitbucket-pipelines.yml +5 -1
- package/buildspec.yml +6 -7
- package/cloudbuild.yaml +28 -12
- package/codefresh.yml +6 -6
- package/cucumber.js +17 -10
- package/docs/00-quick-start.md +8 -0
- package/docs/02-bbr-smart-waits.md +15 -10
- package/docs/03-selector-registry.md +24 -0
- package/docs/04-step-reference.md +51 -25
- package/docs/05-web-first-assertions.md +6 -0
- package/docs/07-auth-state.md +1 -1
- package/docs/08-clock-mocking.md +21 -2
- package/docs/09-api-testing.md +40 -2
- package/docs/10-accessibility.md +2 -0
- package/docs/11-debugging.md +3 -1
- package/docs/12-ai-agent-guide.md +5 -0
- package/docs/13-faq.md +72 -1
- package/docs/14-recipes-cookbook.md +2 -0
- package/docs/15-tag-conventions.md +2 -1
- package/docs/16-ci-cd.md +140 -119
- package/docs/README.md +5 -5
- package/docs/advanced-screenshots.md +3 -1
- package/docs/api-step-definitions.md +16 -2
- package/docs/global-settings.md +69 -17
- package/docs/install-webship-js.md +2 -0
- package/docs/step-definitions/then-i-should-see.md +14 -1
- package/docs/step-definitions/then-item-checkbox.md +2 -0
- package/docs/step-definitions/when-i-fill.md +4 -0
- package/docs/step-definitions/when-i-select-option-select-list.md +2 -0
- package/examples/choice-controls.html +29 -0
- package/examples/datetime-fields.html +52 -0
- package/examples/element-selector-hint.html +16 -0
- package/examples/field-states.html +27 -0
- package/examples/fill-in-empty.html +26 -0
- package/examples/fill-unreachable.html +27 -0
- package/examples/iframe-inner.html +20 -0
- package/examples/iframe-nested.html +16 -0
- package/examples/iframe-outer.html +15 -0
- package/examples/multi-value-fields.html +54 -0
- package/examples/registered-names.html +15 -0
- package/examples/select-by-label.html +33 -0
- package/examples/settle-budget.html +21 -0
- package/examples/sorted-tables.html +38 -0
- package/examples/text-matching.html +48 -0
- package/examples/text-order.html +25 -0
- package/examples/touch.html +22 -0
- package/examples/viewport-top.html +36 -0
- package/package.json +16 -1
- package/playwright.config.ts +3 -1
- package/tests/check-api-launch-url.js +106 -0
- package/tests/check-assets.js +103 -0
- package/tests/check-attachments.js +105 -0
- package/tests/check-breakpoints.js +117 -0
- package/tests/check-clock.js +143 -0
- package/tests/check-config.js +90 -0
- package/tests/check-context.js +215 -0
- package/tests/check-dry-run.js +104 -0
- package/tests/check-examples.js +10 -4
- package/tests/check-exit-report.js +141 -0
- package/tests/check-javascript-errors.js +105 -0
- package/tests/check-must-fail.js +5 -4
- package/tests/check-scaffold.js +36 -1
- package/tests/check-screenshots.js +117 -0
- package/tests/check-settle-verbs.js +137 -0
- package/tests/check-time-limit.js +104 -0
- package/tests/check-video.js +156 -0
- package/tests/check-world.js +167 -0
- package/tests/features/api-base-url.feature +25 -0
- package/tests/features/api-form-data.feature +18 -0
- package/tests/features/api-json-paths.feature +24 -0
- package/tests/features/api-response-contains.feature +21 -0
- package/tests/features/api-response-header-presence.feature +17 -0
- package/tests/features/api-response-header.feature +17 -0
- package/tests/features/api-saved-placeholders.feature +37 -0
- package/tests/features/api-step-definitions-individual.feature +1 -1
- package/tests/features/api-tables.feature +40 -0
- package/tests/features/breakpoints.feature +25 -0
- package/tests/features/choice-controls.feature +35 -0
- package/tests/features/complete-api-testing-examples.feature +1 -1
- package/tests/features/datetime-field-lookup.feature +29 -0
- package/tests/features/element-selector-hint.feature +14 -0
- package/tests/features/field-state.feature +21 -0
- package/tests/features/fill-in-empty-value.feature +41 -0
- package/tests/features/fill-reachable.feature +13 -0
- package/tests/features/iframe-nested.feature +43 -0
- package/tests/features/javascript-tolerated-errors.feature +20 -0
- package/tests/features/modal-open.feature +13 -0
- package/tests/features/multi-value-field-lookup.feature +30 -0
- package/tests/features/registered-names.feature +14 -0
- package/tests/features/select-by-label.feature +31 -0
- package/tests/features/selector-files.feature +14 -0
- package/tests/features/selectors-table-header.feature +35 -0
- package/tests/features/settle-budget.feature +11 -0
- package/tests/features/sorted-tables.feature +19 -0
- package/tests/features/storage-quoted-values.feature +26 -0
- package/tests/features/text-matching.feature +38 -0
- package/tests/features/text-order.feature +14 -0
- package/tests/features/touch.feature +21 -0
- package/tests/features/viewport-top.feature +13 -0
- package/tests/features/xml-namespaces.feature +34 -0
- package/tests/must-fail/api-json-paths.feature +21 -0
- package/tests/must-fail/api-response-contains.feature +23 -0
- package/tests/must-fail/api-response-header-presence.feature +17 -0
- package/tests/must-fail/api-response-header.feature +21 -0
- package/tests/must-fail/api-without-base-url.feature +11 -0
- package/tests/must-fail/breakpoints.feature +15 -0
- package/tests/must-fail/choice-controls.feature +25 -0
- package/tests/must-fail/clock.feature +11 -0
- package/tests/must-fail/datetime-field.feature +10 -0
- package/tests/must-fail/element-selector-hint.feature +17 -0
- package/tests/must-fail/field-state.feature +20 -0
- package/tests/must-fail/fill-field.feature +30 -0
- package/tests/must-fail/iframe-text.feature +17 -0
- package/tests/must-fail/modal-open.feature +26 -0
- package/tests/must-fail/multi-value-field.feature +18 -0
- package/tests/must-fail/registered-names.feature +25 -0
- package/tests/must-fail/select-list.feature +15 -0
- package/tests/must-fail/selector-files.feature +10 -0
- package/tests/must-fail/sorted-tables.feature +20 -0
- package/tests/must-fail/storage-before-a-page.feature +13 -0
- package/tests/must-fail/text-matching.feature +16 -0
- package/tests/must-fail/text-order.feature +15 -0
- package/tests/must-fail/viewport-top.feature +20 -0
- package/tests/must-fail/yaml-numbers.feature +48 -0
- package/tests/step-definitions/a11y.steps.js +24 -15
- package/tests/step-definitions/action.steps.js +22 -8
- package/tests/step-definitions/api.steps.js +349 -67
- package/tests/step-definitions/assertion.steps.js +100 -10
- package/tests/step-definitions/auth.steps.js +15 -18
- package/tests/step-definitions/clock.steps.js +22 -0
- package/tests/step-definitions/debug.steps.js +8 -0
- package/tests/step-definitions/dialog.steps.js +7 -0
- package/tests/step-definitions/element.steps.js +132 -17
- package/tests/step-definitions/field.steps.js +409 -96
- package/tests/step-definitions/form.steps.js +76 -29
- package/tests/step-definitions/iframe.steps.js +89 -29
- package/tests/step-definitions/input.steps.js +26 -7
- package/tests/step-definitions/javascript.steps.js +64 -22
- package/tests/step-definitions/modal.steps.js +79 -13
- package/tests/step-definitions/navigation.steps.js +14 -0
- package/tests/step-definitions/network.steps.js +15 -5
- package/tests/step-definitions/response.steps.js +6 -4
- package/tests/step-definitions/responsive.steps.js +26 -33
- package/tests/step-definitions/screenshot.steps.js +25 -8
- package/tests/step-definitions/scroll.steps.js +20 -0
- package/tests/step-definitions/selectors.steps.js +95 -48
- package/tests/step-definitions/storage.steps.js +38 -13
- package/tests/step-definitions/table.steps.js +81 -6
- package/tests/step-definitions/video.steps.js +52 -55
- package/tests/step-definitions/wait.steps.js +88 -23
- package/tests/step-definitions/web-first.steps.js +69 -35
- package/tests/step-definitions/webship.js +681 -143
- package/tests/step-definitions/xml.steps.js +49 -15
- package/tests/step-definitions/yaml.steps.js +45 -20
package/.circleci/config.yml
CHANGED
|
@@ -2,7 +2,7 @@ version: 2.1
|
|
|
2
2
|
|
|
3
3
|
defaults: &defaults
|
|
4
4
|
docker:
|
|
5
|
-
- image: cimg/node:
|
|
5
|
+
- image: cimg/node:24
|
|
6
6
|
environment:
|
|
7
7
|
FORCE_COLOR: "1"
|
|
8
8
|
|
|
@@ -27,6 +27,15 @@ jobs:
|
|
|
27
27
|
- run:
|
|
28
28
|
name: Test
|
|
29
29
|
command: npm test
|
|
30
|
+
- store_artifacts:
|
|
31
|
+
path: tests/reports
|
|
32
|
+
destination: cucumber-report
|
|
33
|
+
- store_artifacts:
|
|
34
|
+
path: screenshots
|
|
35
|
+
destination: screenshots
|
|
36
|
+
- store_artifacts:
|
|
37
|
+
path: videos
|
|
38
|
+
destination: videos
|
|
30
39
|
|
|
31
40
|
workflows:
|
|
32
41
|
version: 2
|
package/.drone.yml
CHANGED
|
@@ -1,8 +1,10 @@
|
|
|
1
1
|
# Drone CI for webship-js.
|
|
2
2
|
#
|
|
3
|
-
# Runs the full BDD suite inside the official Playwright container
|
|
4
|
-
# chromium + every apt dependency are
|
|
5
|
-
#
|
|
3
|
+
# Runs the full BDD suite inside the official Playwright container of the
|
|
4
|
+
# version the install brings, so chromium + every apt dependency are
|
|
5
|
+
# pre-installed; `npx playwright install` gets the browser of a newer
|
|
6
|
+
# Playwright release when there is one. Anyone running a Drone server can
|
|
7
|
+
# drop the repo in: enable in the UI and push.
|
|
6
8
|
#
|
|
7
9
|
# Setup (full walkthrough in docs/16-ci-cd.md → "Drone CI"):
|
|
8
10
|
# 1. Self-host Drone:
|
|
@@ -16,8 +18,6 @@
|
|
|
16
18
|
# --restart=always --name=drone drone/drone:2
|
|
17
19
|
# Plus at least one runner (docker runner is the common choice).
|
|
18
20
|
# 2. Sign in at https://ci.example.com → activate webship-js.
|
|
19
|
-
#
|
|
20
|
-
# Drone Cloud (drone.io) is paid as of 2023 — self-host is the OSS path.
|
|
21
21
|
|
|
22
22
|
kind: pipeline
|
|
23
23
|
type: docker
|
|
@@ -35,7 +35,7 @@ trigger:
|
|
|
35
35
|
|
|
36
36
|
steps:
|
|
37
37
|
- name: test
|
|
38
|
-
image: mcr.microsoft.com/playwright:v1.
|
|
38
|
+
image: mcr.microsoft.com/playwright:v1.65.1-noble
|
|
39
39
|
environment:
|
|
40
40
|
FORCE_COLOR: "1"
|
|
41
41
|
LAUNCH_URL: "http://localhost:8080"
|
|
@@ -57,7 +57,7 @@ steps:
|
|
|
57
57
|
- failure
|
|
58
58
|
commands:
|
|
59
59
|
- apk add --no-cache tar
|
|
60
|
-
- tar czf /artifacts/cucumber-report-${DRONE_BUILD_NUMBER}.tar.gz tests/reports screenshots || true
|
|
60
|
+
- tar czf /artifacts/cucumber-report-${DRONE_BUILD_NUMBER}.tar.gz tests/reports screenshots videos || true
|
|
61
61
|
volumes:
|
|
62
62
|
- name: artifacts
|
|
63
63
|
path: /artifacts
|
|
@@ -47,12 +47,57 @@ jobs:
|
|
|
47
47
|
- name: Install Playwright browsers
|
|
48
48
|
run: npx playwright install --with-deps chromium
|
|
49
49
|
|
|
50
|
+
- name: Check that a dry run prints no line for each skipped step
|
|
51
|
+
run: npm run test:dry-run
|
|
52
|
+
|
|
53
|
+
- name: Check that the relative API base URL follows the launch URL
|
|
54
|
+
run: npm run test:api-launch-url
|
|
55
|
+
|
|
50
56
|
- name: Check the step examples and the feature steps
|
|
51
57
|
run: npm run test:examples
|
|
52
58
|
|
|
59
|
+
- name: Check that a wait runs for the time the scenario gives it
|
|
60
|
+
run: npm run test:time-limit
|
|
61
|
+
|
|
53
62
|
- name: Check that a feature named on the command line runs alone
|
|
54
63
|
run: npm run test:paths
|
|
55
64
|
|
|
65
|
+
- name: Check that the print steps attach what they print to the report
|
|
66
|
+
run: npm run test:attachments
|
|
67
|
+
|
|
68
|
+
- name: Check that each JavaScript-error check counts its own kind
|
|
69
|
+
run: npm run test:js-errors
|
|
70
|
+
|
|
71
|
+
- name: Check that only a failed step leaves a failure screenshot
|
|
72
|
+
run: npm run test:screenshots
|
|
73
|
+
|
|
74
|
+
- name: Check that a step reads a file from the tests/assets of the project
|
|
75
|
+
run: npm run test:assets
|
|
76
|
+
|
|
77
|
+
- name: Check that a configuration with only the launch URL runs
|
|
78
|
+
run: npm run test:config
|
|
79
|
+
|
|
80
|
+
- name: Check the HTML report built at the end of a run
|
|
81
|
+
run: npm run test:exit-report
|
|
82
|
+
|
|
83
|
+
- name: Check that every step and tag reads one breakpoint registry
|
|
84
|
+
run: npm run test:breakpoints
|
|
85
|
+
|
|
86
|
+
- name: Check that a replaced browser context keeps what the scenario set up
|
|
87
|
+
run: npm run test:context
|
|
88
|
+
|
|
89
|
+
- name: Check the video files of the three recording modes
|
|
90
|
+
run: npm run test:video
|
|
91
|
+
|
|
92
|
+
- name: Check that a project extends the World and settles its own steps
|
|
93
|
+
run: npm run test:world
|
|
94
|
+
|
|
95
|
+
- name: Check the smart waits under a fake clock
|
|
96
|
+
run: npm run test:clock
|
|
97
|
+
|
|
98
|
+
- name: Check that a project step with a page-changing verb is followed by the settle
|
|
99
|
+
run: npm run test:settle-verbs
|
|
100
|
+
|
|
56
101
|
- name: Start virtual server
|
|
57
102
|
run: npm start &
|
|
58
103
|
|
package/.gitlab-ci.yml
CHANGED
|
@@ -1,12 +1,9 @@
|
|
|
1
|
-
image: node:
|
|
1
|
+
image: node:24
|
|
2
2
|
|
|
3
3
|
variables:
|
|
4
4
|
FORCE_COLOR: "1"
|
|
5
5
|
|
|
6
6
|
before_script:
|
|
7
|
-
- apt-get update -qq
|
|
8
|
-
- apt-get upgrade -qqy
|
|
9
|
-
- apt-get install -yqq vim links lynx git diffutils htop curl wget p7zip-full unzip zip sed gcc g++ make libfreetype6-dev libaio1 libaio-dev libonig-dev libpng-dev
|
|
10
7
|
- npm install
|
|
11
8
|
- npx playwright install --with-deps chromium
|
|
12
9
|
|
|
@@ -19,6 +16,14 @@ webship-js-test:
|
|
|
19
16
|
- npm start &
|
|
20
17
|
- sleep 3
|
|
21
18
|
- npm test
|
|
19
|
+
artifacts:
|
|
20
|
+
name: cucumber-report
|
|
21
|
+
when: always
|
|
22
|
+
expire_in: 14 days
|
|
23
|
+
paths:
|
|
24
|
+
- tests/reports/
|
|
25
|
+
- screenshots/
|
|
26
|
+
- videos/
|
|
22
27
|
|
|
23
28
|
only:
|
|
24
29
|
refs:
|
|
@@ -1,10 +1,9 @@
|
|
|
1
1
|
# Harness CI pipeline for webship-js (Pipeline-as-Code).
|
|
2
2
|
#
|
|
3
|
-
# Harness CI is part of the Harness Software Delivery Platform.
|
|
4
|
-
#
|
|
5
|
-
#
|
|
6
|
-
#
|
|
7
|
-
# as the pipeline definition.
|
|
3
|
+
# Harness CI is part of the Harness Software Delivery Platform. For the free
|
|
4
|
+
# plan and its build credits, see the Harness pricing page: they change over
|
|
5
|
+
# time. After signup, point a Git Sync connector at this repo and pick
|
|
6
|
+
# `.harness/webship-js-pipeline.yml` as the pipeline definition.
|
|
8
7
|
#
|
|
9
8
|
# Full walkthrough: docs/16-ci-cd.md → "Harness CI".
|
|
10
9
|
|
|
@@ -92,7 +91,7 @@ pipeline:
|
|
|
92
91
|
image: plugins/s3
|
|
93
92
|
settings:
|
|
94
93
|
bucket: webship-js-reports
|
|
95
|
-
source: tests/reports
|
|
94
|
+
source: "{tests/reports,screenshots,videos}/**"
|
|
96
95
|
target: harness/$DRONE_BUILD_NUMBER/
|
|
97
96
|
access_key: <+secrets.getValue("aws_access_key")>
|
|
98
97
|
secret_key: <+secrets.getValue("aws_secret_key")>
|
package/.semaphore/semaphore.yml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# Semaphore CI for webship-js.
|
|
2
2
|
#
|
|
3
|
-
#
|
|
4
|
-
#
|
|
3
|
+
# For the free tier and the plans, see the Semaphore pricing page: they change
|
|
4
|
+
# over time.
|
|
5
5
|
#
|
|
6
6
|
# Setup (full walkthrough in docs/16-ci-cd.md → "Semaphore"):
|
|
7
7
|
# 1. semaphoreci.com → sign up with GitHub.
|
|
@@ -22,7 +22,7 @@ global_job_config:
|
|
|
22
22
|
- { name: LAUNCH_URL, value: "http://localhost:8080" }
|
|
23
23
|
prologue:
|
|
24
24
|
commands:
|
|
25
|
-
- sem-version node
|
|
25
|
+
- sem-version node 24
|
|
26
26
|
- checkout
|
|
27
27
|
- cache restore node-modules-$(checksum package.json)
|
|
28
28
|
- cache restore ms-playwright
|
|
@@ -50,9 +50,6 @@ blocks:
|
|
|
50
50
|
epilogue:
|
|
51
51
|
always:
|
|
52
52
|
commands:
|
|
53
|
-
- artifact push job tests/reports
|
|
54
|
-
- artifact push job
|
|
55
|
-
- artifact push job
|
|
56
|
-
on_failure:
|
|
57
|
-
commands:
|
|
58
|
-
- artifact push job screenshots --expire-in 30d || true
|
|
53
|
+
- artifact push job tests/reports --expire-in 30d || true
|
|
54
|
+
- artifact push job screenshots --expire-in 30d || true
|
|
55
|
+
- artifact push job videos --expire-in 30d || true
|
package/.teamcity/settings.kts
CHANGED
|
@@ -11,8 +11,8 @@
|
|
|
11
11
|
// TeamCity will offer to generate this file the first time; we ship
|
|
12
12
|
// a hand-crafted version below.
|
|
13
13
|
//
|
|
14
|
-
//
|
|
15
|
-
//
|
|
14
|
+
// For the free tier of TeamCity Cloud and its limits, see the TeamCity
|
|
15
|
+
// pricing page: they change over time.
|
|
16
16
|
|
|
17
17
|
import jetbrains.buildServer.configs.kotlin.v2019_2.*
|
|
18
18
|
import jetbrains.buildServer.configs.kotlin.v2019_2.buildSteps.script
|
|
@@ -55,7 +55,7 @@ object WebshipJsTest : BuildType({
|
|
|
55
55
|
curl -sf http://localhost:8080/ > /dev/null
|
|
56
56
|
npm test
|
|
57
57
|
""".trimIndent()
|
|
58
|
-
dockerImage = "mcr.microsoft.com/playwright:v1.
|
|
58
|
+
dockerImage = "mcr.microsoft.com/playwright:v1.65.1-noble"
|
|
59
59
|
dockerPull = true
|
|
60
60
|
dockerRunParameters = "--user root:root --network host"
|
|
61
61
|
}
|
|
@@ -80,11 +80,12 @@ object WebshipJsTest : BuildType({
|
|
|
80
80
|
}
|
|
81
81
|
|
|
82
82
|
artifactRules = """
|
|
83
|
-
tests/reports/
|
|
84
|
-
tests/reports/cucumber_report.pdf
|
|
85
|
-
tests/reports/cucumber_report.json
|
|
83
|
+
tests/reports/** => tests/reports
|
|
86
84
|
screenshots/** => screenshots
|
|
85
|
+
videos/** => videos
|
|
87
86
|
""".trimIndent()
|
|
87
|
+
// Keep the report of a failed run too.
|
|
88
|
+
publishArtifacts = PublishMode.ALWAYS
|
|
88
89
|
|
|
89
90
|
requirements {
|
|
90
91
|
contains("os.name", "Linux")
|
package/.travis.yml
CHANGED
|
@@ -3,7 +3,7 @@ os: linux
|
|
|
3
3
|
dist: jammy
|
|
4
4
|
|
|
5
5
|
node_js:
|
|
6
|
-
- "
|
|
6
|
+
- "24"
|
|
7
7
|
|
|
8
8
|
env:
|
|
9
9
|
global:
|
|
@@ -32,6 +32,11 @@ before_script:
|
|
|
32
32
|
script:
|
|
33
33
|
- npm test
|
|
34
34
|
|
|
35
|
+
# Travis CI keeps no build artifacts of its own: the report, the screenshots
|
|
36
|
+
# and the videos (tests/reports/, screenshots/, videos/) stay in the build
|
|
37
|
+
# log only. To keep them, upload them to storage of your own in an
|
|
38
|
+
# after_script step, or use another provider of docs/16-ci-cd.md.
|
|
39
|
+
|
|
35
40
|
notifications:
|
|
36
41
|
email:
|
|
37
42
|
on_success: never
|
package/AGENTS.md
CHANGED
|
@@ -109,7 +109,7 @@ step definitions. Critical takeaways:
|
|
|
109
109
|
|
|
110
110
|
## Source map
|
|
111
111
|
|
|
112
|
-
Step definitions: `tests/step-definitions/` —
|
|
112
|
+
Step definitions: `tests/step-definitions/` — 428 steps across 36
|
|
113
113
|
`*.steps.js` files, all auto-loaded. The `webship.js` file there is the
|
|
114
114
|
single canonical entry point — World, hooks, init script, and shared
|
|
115
115
|
helpers (`smartSettle`, `waitForPageLoad`, `buildSelector`, `gotoUrl`,
|
package/CLAUDE.md
CHANGED
|
@@ -38,9 +38,26 @@ 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. |
|
|
41
|
+
| `npm run test:examples` | No browser: every step definition is documented with at least five `Example #n:` blocks that use it, every `Example #n:` step and every feature step resolves to exactly one definition. |
|
|
42
|
+
| `npm run test:attachments` | Needs browsers, no server: the steps that print what they found (the accessibility print steps) attach the same text to their step in the JSON report. |
|
|
42
43
|
| `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`. |
|
|
44
|
+
| `npm run test:api-launch-url` | Needs browsers, no server of its own: the relative API base URL (`Given the API base URL is "/"`) is joined to `worldParameters.launchUrl`. |
|
|
43
45
|
| `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. |
|
|
46
|
+
| `npm run test:settle-verbs` | A project's own step whose words carry a page-changing verb (add, log out, enter, open, delete, save) is followed by the settle; `wait for ajax to finish` reads in lower case. |
|
|
47
|
+
| `npm run test:config` | A `cucumber.js` whose `worldParameters` carry only the launch URL runs a scenario green and the run ends by itself. |
|
|
48
|
+
| `npm run test:exit-report` | Needs browsers, no server: the HTML report built at the end of a run is built once with `--parallel`, from a JSON report written elsewhere, and says so in one line when there is none. |
|
|
49
|
+
| `npm run test:world` | A project World that extends `PlaywrightWorld` keeps the viewport tag and `this.smartSettle()`; a World that replaces it is reported. |
|
|
50
|
+
| `npm run test:clock` | Under a fake clock a navigation and a press settle when the page is quiet; a clock step on a clock nobody installed says so. |
|
|
51
|
+
| `npm run test:video` | The video files of the `on`, `on-failure` and `off` modes: final names in lower case, no temporary file left, the printed path is the saved one, reserved names kept, stopped recordings named by the pattern. |
|
|
52
|
+
| `npm run test:context` | A step that replaces the browser context (restore an auth state, start / stop a video) keeps the viewport, the smart waits, the cookies, JavaScript-error capture and the request log. |
|
|
53
|
+
| `npm run test:breakpoints` | The `@mobile` / `@desktop` tags, `set the viewport to the "…" breakpoint` and `viewing the site on a … screen` read one breakpoint registry (config, `WEBSHIP_SELECTORS_BREAKPOINTS`, `default: true`). |
|
|
54
|
+
| `npm run test:report` | No server: generates an HTML report from a small JSON and checks it — no third-party icon, the project's own version, the place of execution. |
|
|
55
|
+
| `npm run test:dry-run` | No server: a dry run with the pretty formatter prints the steps, `? undefined` and the summary, with no `- skipped` line for each hook or step. |
|
|
56
|
+
| `npm run test:time-limit` | No server: the waits that take a length and the web-first `within N seconds` matchers run past `WEBSHIP_STEP_TIMEOUT` and pass, or fail with their own message. |
|
|
57
|
+
| `npm run test:js-errors` | No server: with warnings captured, the errors check counts errors only and the warnings check warnings only; what a check did not read is reported at the end of the scenario. |
|
|
58
|
+
| `npm run test:assets` | No server: in a project of its own, the attach, XML-file and YAML-file steps read its `tests/assets/` and paths from its root; a missing file fails plainly. |
|
|
59
|
+
| `npm run test:screenshots` | No server: only a failed step leaves a failure screenshot (a skipped or pending one does not). |
|
|
60
|
+
| `npm run test:scaffold` | Scaffolds a new project, runs its first `npm test` and one feature named on the command line. |
|
|
44
61
|
| `npm run generate-reports` | HTML (+ optional PDF) report from `tests/reports/cucumber_report.json`. |
|
|
45
62
|
|
|
46
63
|
Targeting a subset:
|
|
@@ -56,10 +73,9 @@ HEADLESS=false SLOW_MO=800 npx cucumber-js tests/features/x.feature # watch a
|
|
|
56
73
|
```
|
|
57
74
|
|
|
58
75
|
Env vars: `LAUNCH_URL`, `BROWSER`, `HEADLESS`, `SLOW_MO`, `FORCE_COLOR`,
|
|
59
|
-
`WEBSHIP_AUTO_SETTLE`, `WEBSHIP_STEP_TIMEOUT`, `WEBSHIP_REPORT_DISABLE`, `WEBSHIP_REPORT_ARGS`,
|
|
76
|
+
`WEBSHIP_AUTO_SETTLE`, `WEBSHIP_STEP_TIMEOUT`, `WEBSHIP_REPORT_DISABLE`, `WEBSHIP_REPORT_ARGS`, `WEBSHIP_REPORT_JSON`,
|
|
60
77
|
`WEBSHIP_FILTER_HOOK_LINES`, `WEBSHIP_SCREENSHOT_*`, `WEBSHIP_VIDEO*`,
|
|
61
|
-
`WEBSHIP_JS_ERROR_*`, `
|
|
62
|
-
`WEBSHIP_SELECTORS_BREAKPOINTS`, `DIFFY_*`. Every one of them mirrors a
|
|
78
|
+
`WEBSHIP_JS_ERROR_*`, `WEBSHIP_SELECTORS_BREAKPOINTS`, `DIFFY_*`. Every one of them mirrors a
|
|
63
79
|
`worldParameters` key in `cucumber.js` — that file is the annotated
|
|
64
80
|
reference; read it before inventing a new knob.
|
|
65
81
|
|
|
@@ -94,18 +110,38 @@ Everything shared lives here; every `*.steps.js` does
|
|
|
94
110
|
Playwright's 30 s default so locator timeouts reach our try/catch
|
|
95
111
|
wrappers and testers see a friendly message, not "function timed out".
|
|
96
112
|
The 45 s in `cucumber.js` exists for the same reason; keep them aligned.
|
|
97
|
-
|
|
98
|
-
`
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
`
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
`
|
|
113
|
+
A step whose length the scenario gives (`I wait 2 minutes`, `within N
|
|
114
|
+
seconds`) takes `OWN_LENGTH` from `wait.steps.js` (no cucumber limit)
|
|
115
|
+
and bounds itself with `withinTimeLimit` instead.
|
|
116
|
+
* **The init script** (`smartWaitProbes`) installed via
|
|
117
|
+
`context.addInitScript()` in `openContext()` — monkey-patches `fetch`,
|
|
118
|
+
`XMLHttpRequest.send`, `setTimeout`/`clearTimeout` and attaches a
|
|
119
|
+
`MutationObserver` to maintain `window.__webshipAjaxCount`,
|
|
120
|
+
`__webshipPendingTimers`, `__webshipLastMutation`. This is the substrate
|
|
121
|
+
the whole wait policy stands on. **Never strip it.**
|
|
122
|
+
* **One way to open a browser context** — `openBrowser()` launches the
|
|
123
|
+
browser and calls `openContext()`, which applies the context options,
|
|
124
|
+
the scenario's viewport tag and video recording, the init script, and
|
|
125
|
+
every setup registered with `onNewPage()` (JavaScript-error listeners,
|
|
126
|
+
the response tracker, the request log, a pending dialog handler). A step
|
|
127
|
+
that needs a new context (restore an auth state, start or stop a video)
|
|
128
|
+
calls `replaceContext()`, never `browser.newContext()` directly — or the
|
|
129
|
+
new page silently loses the smart waits, the viewport and the listeners.
|
|
130
|
+
* **Hooks** — they run in the order they are registered (cucumber-js has
|
|
131
|
+
no `order` option; After hooks run in reverse), and `webship.js` is
|
|
132
|
+
loaded before any other hook is registered (every step file with hooks
|
|
133
|
+
requires it at its top): its `Before` opens the browser (merging
|
|
134
|
+
`recordVideo` context options when video is on) before any other
|
|
135
|
+
`Before`; its `After`
|
|
105
136
|
captures the video path *before* closing the context, saves/deletes per
|
|
106
137
|
mode, then closes the browser; `BeforeStep` resolves `[relative:…]` date
|
|
107
138
|
tokens in step text, doc strings, and data-table cells; `AfterStep`
|
|
108
139
|
runs the auto-settle.
|
|
140
|
+
* **`PlaywrightWorld` is exported** so a project extends it
|
|
141
|
+
(`setWorldConstructor(class extends PlaywrightWorld { … })`) instead of
|
|
142
|
+
replacing it; a World that does not extend it is reported once at the
|
|
143
|
+
start of the run. Its `smartSettle(budget = 1500)` method is the settle a
|
|
144
|
+
custom step calls after changing the page.
|
|
109
145
|
* **Shared helpers** (exported): `smartSettle`, `waitForPageLoad`,
|
|
110
146
|
`buildSelector`, `gotoUrl`, `fillField`, `getLocatorText`, `pad`,
|
|
111
147
|
the modal probes (`getModalSelector`, `getModalLocator`,
|
|
@@ -113,11 +149,15 @@ Everything shared lives here; every `*.steps.js` does
|
|
|
113
149
|
helpers (`resolveRelativeDate`, `parseRelativeOffset`,
|
|
114
150
|
`formatRelativeDate`), and the error builders (`friendly`, `humanize`).
|
|
115
151
|
* **Two process-level side effects**: a stdout/stderr filter that strips
|
|
116
|
-
noisy `✔ Before # …` hook lines from cucumber's failure dump
|
|
117
|
-
(`
|
|
152
|
+
noisy `✔ Before # …` hook lines from cucumber's failure dump, and in a
|
|
153
|
+
dry run (`--dry-run`, `-d`) the pretty formatter's `- skipped` line for
|
|
154
|
+
every hook and step (`WEBSHIP_FILTER_HOOK_LINES=off` to disable), and a `process.on('exit')`
|
|
118
155
|
hook that auto-generates the HTML report via `bin/generate-reports`
|
|
119
156
|
(`WEBSHIP_REPORT_DISABLE=1` to disable, `WEBSHIP_REPORT_ARGS` to pass
|
|
120
|
-
flags).
|
|
157
|
+
flags). It runs only in the process that runs cucumber-js, never in a
|
|
158
|
+
`--parallel` worker, and reads the JSON report the run wrote
|
|
159
|
+
(`WEBSHIP_REPORT_JSON`, else the `json:` formatter of the command line or
|
|
160
|
+
of `cucumber.js`, else `tests/reports/cucumber_report.json`).
|
|
121
161
|
|
|
122
162
|
### 2.3 Config layering
|
|
123
163
|
|
|
@@ -259,7 +299,7 @@ Some pairs look similar but cover different domains. NEVER merge:
|
|
|
259
299
|
|
|
260
300
|
## 5. File organisation
|
|
261
301
|
|
|
262
|
-
|
|
302
|
+
428 built-in steps across 36 step files. Cucumber auto-loads every
|
|
263
303
|
`*.steps.js` in `tests/step-definitions/`.
|
|
264
304
|
|
|
265
305
|
```
|
|
@@ -267,15 +307,15 @@ tests/step-definitions/
|
|
|
267
307
|
├── webship.js # World, hooks, init script, shared helpers — see §2.2. Not a steps file.
|
|
268
308
|
├── a11y.steps.js (30) # axe-core WCAG audits + POUR hygiene probes (axe loaded lazily)
|
|
269
309
|
├── action.steps.js (7) # press / click / follow / attach file (actOrExplain lives here)
|
|
270
|
-
├── api.steps.js (
|
|
310
|
+
├── api.steps.js (24) # REST long form — base URL, headers, query, body, JSON Pointer
|
|
271
311
|
├── assertion.steps.js (14) # see / not see, in row, in element, response, count
|
|
272
312
|
├── auth.steps.js (3) # storageState save / restore / clear
|
|
273
313
|
├── clock.steps.js (7) # page.clock — install / advance / pause / set
|
|
274
314
|
├── cookie.steps.js (12) # cookie exists / equals / contains
|
|
275
315
|
├── debug.steps.js (2) # print URL / last response
|
|
276
316
|
├── dialog.steps.js (8) # native alert / confirm / prompt handlers
|
|
277
|
-
├── element.steps.js (
|
|
278
|
-
├── field.steps.js (
|
|
317
|
+
├── element.steps.js (20) # focus / scroll-to / dispatch / count / position
|
|
318
|
+
├── field.steps.js (35) # field, checkbox, radio, select-list state assertions
|
|
279
319
|
├── file-download.steps.js (8) # download capture + filename / mime / path assertions
|
|
280
320
|
├── form.steps.js (13) # fill / select / additionally select / check / uncheck / radio
|
|
281
321
|
├── iframe.steps.js (10) # frameLocator switch + frame-scoped interactions
|
|
@@ -302,7 +342,7 @@ tests/step-definitions/
|
|
|
302
342
|
├── xml.steps.js (20) # XPath equals / contains / count / attr
|
|
303
343
|
└── yaml.steps.js (38) # multi-doc, types, numerics, JSON Schema, diff
|
|
304
344
|
|
|
305
|
-
tests/features/ #
|
|
345
|
+
tests/features/ # 122 .feature files
|
|
306
346
|
tests/selectors/ # 26 JSON presets + _canonical-keys.json
|
|
307
347
|
tests/assets/ # upload fixtures (pdf, png)
|
|
308
348
|
examples/ # static HTML fixtures served by `npm start`
|
|
@@ -331,8 +371,10 @@ Conditions 4/5/6 are evaluated atomically in one `waitForFunction`, so a
|
|
|
331
371
|
late-firing `setTimeout` that mutates the DOM re-arms the wait.
|
|
332
372
|
|
|
333
373
|
Auto-settle hook: `AfterStep` runs `smartSettle(page, 1500)` after every
|
|
334
|
-
step whose
|
|
335
|
-
|
|
374
|
+
step whose own words (quoted arguments left out) match
|
|
375
|
+
`STATE_MUTATING_STEP` (click / press / fill / select / check / attach /
|
|
376
|
+
reload / navigate, and the verbs projects use: add / open / delete / save /
|
|
377
|
+
enter / log in / log out / …). This is what makes
|
|
336
378
|
`When I click "X" Then I should see "Y"` work without an explicit wait.
|
|
337
379
|
Disable per-run with `WEBSHIP_AUTO_SETTLE=off`. If a wait is flaky only in
|
|
338
380
|
CI, raise the budget — never add a static sleep.
|
|
@@ -396,7 +438,7 @@ into one reference. Internalise these:
|
|
|
396
438
|
|
|
397
439
|
Tag conventions live in `docs/15-tag-conventions.md` — `@critical`,
|
|
398
440
|
`@smoke`, `@auth`, `@security`, `@a11y`, `@i18n`, `@perf`, `@flaky`,
|
|
399
|
-
`@wip`, `@desktop`/`@mobile`, `@external`, `@auth-setup`, plus the
|
|
441
|
+
`@wip`, `@desktop`/`@mobile`, `@touch`, `@external`, `@auth-setup`, plus the
|
|
400
442
|
recording tags `@video` / `@no-video` and the JS-error tags `@js-fail` /
|
|
401
443
|
`@js-warn` / `@js-off`.
|
|
402
444
|
|
package/Jenkinsfile
CHANGED
|
@@ -1,7 +1,9 @@
|
|
|
1
1
|
// Jenkins declarative pipeline for webship-js.
|
|
2
2
|
//
|
|
3
3
|
// Runs the full BDD suite against an http-server fixture on port 8080.
|
|
4
|
-
// Uses the official Playwright image
|
|
4
|
+
// Uses the official Playwright image of the version the install brings, so
|
|
5
|
+
// chromium + all apt deps are baked in; `npx playwright install` below gets
|
|
6
|
+
// the browser of a newer Playwright release when there is one.
|
|
5
7
|
//
|
|
6
8
|
// Requirements on the Jenkins controller:
|
|
7
9
|
// - Docker Pipeline plugin (built into the "suggested plugins" install)
|
|
@@ -13,7 +15,7 @@
|
|
|
13
15
|
pipeline {
|
|
14
16
|
agent {
|
|
15
17
|
docker {
|
|
16
|
-
image 'mcr.microsoft.com/playwright:v1.
|
|
18
|
+
image 'mcr.microsoft.com/playwright:v1.65.1-noble'
|
|
17
19
|
args '-u root:root'
|
|
18
20
|
}
|
|
19
21
|
}
|
|
@@ -47,7 +49,7 @@ pipeline {
|
|
|
47
49
|
}
|
|
48
50
|
post {
|
|
49
51
|
always {
|
|
50
|
-
archiveArtifacts artifacts: 'tests/reports
|
|
52
|
+
archiveArtifacts artifacts: 'tests/reports/**/*,screenshots/**/*,videos/**/*',
|
|
51
53
|
allowEmptyArchive: true
|
|
52
54
|
}
|
|
53
55
|
}
|
package/azure-pipelines.yml
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
# Azure DevOps Pipelines for webship-js.
|
|
2
2
|
#
|
|
3
|
-
# Runs the full BDD suite on a Microsoft-hosted Ubuntu agent.
|
|
4
|
-
#
|
|
5
|
-
#
|
|
3
|
+
# Runs the full BDD suite on a Microsoft-hosted Ubuntu agent. For the free
|
|
4
|
+
# parallel jobs and minutes of public and private projects, see the Azure
|
|
5
|
+
# DevOps pricing and parallel-jobs pages: they change over time.
|
|
6
6
|
#
|
|
7
7
|
# Setup:
|
|
8
8
|
# 1. dev.azure.com → sign in → create Organization → create Project.
|
|
@@ -35,8 +35,8 @@ variables:
|
|
|
35
35
|
steps:
|
|
36
36
|
- task: NodeTool@0
|
|
37
37
|
inputs:
|
|
38
|
-
versionSpec: '
|
|
39
|
-
displayName: 'Install Node
|
|
38
|
+
versionSpec: '24.x'
|
|
39
|
+
displayName: 'Install Node 24'
|
|
40
40
|
|
|
41
41
|
- task: Cache@2
|
|
42
42
|
inputs:
|
|
@@ -75,8 +75,17 @@ steps:
|
|
|
75
75
|
displayName: 'Publish HTML / PDF / JSON report'
|
|
76
76
|
|
|
77
77
|
- task: PublishBuildArtifacts@1
|
|
78
|
-
condition:
|
|
78
|
+
condition: always()
|
|
79
|
+
continueOnError: true
|
|
79
80
|
inputs:
|
|
80
81
|
pathToPublish: 'screenshots'
|
|
81
|
-
artifactName: '
|
|
82
|
-
displayName: 'Publish
|
|
82
|
+
artifactName: 'screenshots'
|
|
83
|
+
displayName: 'Publish screenshots'
|
|
84
|
+
|
|
85
|
+
- task: PublishBuildArtifacts@1
|
|
86
|
+
condition: always()
|
|
87
|
+
continueOnError: true
|
|
88
|
+
inputs:
|
|
89
|
+
pathToPublish: 'videos'
|
|
90
|
+
artifactName: 'videos'
|
|
91
|
+
displayName: 'Publish videos'
|
package/bamboo-specs/bamboo.yml
CHANGED
|
@@ -1,9 +1,7 @@
|
|
|
1
1
|
# Atlassian Bamboo YAML Specs for webship-js.
|
|
2
2
|
#
|
|
3
|
-
# Runs the full BDD suite on a Bamboo Data Center
|
|
4
|
-
#
|
|
5
|
-
# targets Bamboo Data Center 9.x — which is the only flavour still
|
|
6
|
-
# supported.)
|
|
3
|
+
# Runs the full BDD suite on a self-hosted Bamboo Data Center instance:
|
|
4
|
+
# Atlassian offers Bamboo as Data Center only, there is no hosted Bamboo.
|
|
7
5
|
#
|
|
8
6
|
# Setup (full walkthrough in docs/16-ci-cd.md → "Bamboo Data Center"):
|
|
9
7
|
# 1. Bamboo admin → Linked repositories → add the GitHub repo.
|
|
@@ -30,7 +28,7 @@ stages:
|
|
|
30
28
|
Cucumber:
|
|
31
29
|
key: CUC
|
|
32
30
|
docker:
|
|
33
|
-
image: mcr.microsoft.com/playwright:v1.
|
|
31
|
+
image: mcr.microsoft.com/playwright:v1.65.1-noble
|
|
34
32
|
docker-run-arguments:
|
|
35
33
|
- --user=root:root
|
|
36
34
|
- --network=host
|
|
@@ -61,22 +59,18 @@ Cucumber:
|
|
|
61
59
|
scripts:
|
|
62
60
|
- npm test
|
|
63
61
|
artifacts:
|
|
64
|
-
- name: cucumber-report
|
|
65
|
-
pattern: tests/reports
|
|
66
|
-
shared: true
|
|
67
|
-
required: false
|
|
68
|
-
- name: cucumber-report-pdf
|
|
69
|
-
pattern: tests/reports/cucumber_report.pdf
|
|
70
|
-
shared: true
|
|
71
|
-
required: false
|
|
72
|
-
- name: cucumber-report-json
|
|
73
|
-
pattern: tests/reports/cucumber_report.json
|
|
62
|
+
- name: cucumber-report
|
|
63
|
+
pattern: tests/reports/**
|
|
74
64
|
shared: true
|
|
75
65
|
required: false
|
|
76
66
|
- name: screenshots
|
|
77
67
|
pattern: screenshots/**
|
|
78
68
|
shared: true
|
|
79
69
|
required: false
|
|
70
|
+
- name: videos
|
|
71
|
+
pattern: videos/**
|
|
72
|
+
shared: true
|
|
73
|
+
required: false
|
|
80
74
|
requirements:
|
|
81
75
|
- os: Linux
|
|
82
76
|
|