webship-js 2.0.11 → 2.0.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (168) hide show
  1. package/.circleci/config.yml +10 -1
  2. package/.drone.yml +7 -7
  3. package/.github/workflows/github-actions.yml +45 -0
  4. package/.gitlab-ci.yml +9 -4
  5. package/.harness/webship-js-pipeline.yml +5 -6
  6. package/.semaphore/semaphore.yml +6 -9
  7. package/.teamcity/settings.kts +7 -6
  8. package/.travis.yml +6 -1
  9. package/AGENTS.md +1 -1
  10. package/CLAUDE.md +65 -23
  11. package/Jenkinsfile +5 -3
  12. package/azure-pipelines.yml +17 -8
  13. package/bamboo-specs/bamboo.yml +9 -15
  14. package/bin/init-webship.js +44 -8
  15. package/bitbucket-pipelines.yml +5 -1
  16. package/buildspec.yml +6 -7
  17. package/cloudbuild.yaml +28 -12
  18. package/codefresh.yml +6 -6
  19. package/cucumber.js +17 -10
  20. package/docs/00-quick-start.md +8 -0
  21. package/docs/02-bbr-smart-waits.md +15 -10
  22. package/docs/03-selector-registry.md +24 -0
  23. package/docs/04-step-reference.md +51 -25
  24. package/docs/05-web-first-assertions.md +6 -0
  25. package/docs/07-auth-state.md +1 -1
  26. package/docs/08-clock-mocking.md +21 -2
  27. package/docs/09-api-testing.md +40 -2
  28. package/docs/10-accessibility.md +2 -0
  29. package/docs/11-debugging.md +3 -1
  30. package/docs/12-ai-agent-guide.md +5 -0
  31. package/docs/13-faq.md +72 -1
  32. package/docs/14-recipes-cookbook.md +2 -0
  33. package/docs/15-tag-conventions.md +2 -1
  34. package/docs/16-ci-cd.md +140 -119
  35. package/docs/README.md +5 -5
  36. package/docs/advanced-screenshots.md +3 -1
  37. package/docs/api-step-definitions.md +16 -2
  38. package/docs/global-settings.md +69 -17
  39. package/docs/install-webship-js.md +2 -0
  40. package/docs/step-definitions/then-i-should-see.md +14 -1
  41. package/docs/step-definitions/then-item-checkbox.md +2 -0
  42. package/docs/step-definitions/when-i-fill.md +4 -0
  43. package/docs/step-definitions/when-i-select-option-select-list.md +2 -0
  44. package/examples/choice-controls.html +29 -0
  45. package/examples/datetime-fields.html +52 -0
  46. package/examples/element-selector-hint.html +16 -0
  47. package/examples/field-states.html +27 -0
  48. package/examples/fill-in-empty.html +26 -0
  49. package/examples/fill-unreachable.html +27 -0
  50. package/examples/iframe-inner.html +20 -0
  51. package/examples/iframe-nested.html +16 -0
  52. package/examples/iframe-outer.html +15 -0
  53. package/examples/multi-value-fields.html +54 -0
  54. package/examples/registered-names.html +15 -0
  55. package/examples/select-by-label.html +33 -0
  56. package/examples/settle-budget.html +21 -0
  57. package/examples/sorted-tables.html +38 -0
  58. package/examples/text-matching.html +48 -0
  59. package/examples/text-order.html +25 -0
  60. package/examples/touch.html +22 -0
  61. package/examples/viewport-top.html +36 -0
  62. package/package.json +16 -1
  63. package/playwright.config.ts +3 -1
  64. package/tests/check-api-launch-url.js +106 -0
  65. package/tests/check-assets.js +103 -0
  66. package/tests/check-attachments.js +105 -0
  67. package/tests/check-breakpoints.js +117 -0
  68. package/tests/check-clock.js +143 -0
  69. package/tests/check-config.js +90 -0
  70. package/tests/check-context.js +215 -0
  71. package/tests/check-dry-run.js +104 -0
  72. package/tests/check-examples.js +10 -4
  73. package/tests/check-exit-report.js +141 -0
  74. package/tests/check-javascript-errors.js +105 -0
  75. package/tests/check-must-fail.js +5 -4
  76. package/tests/check-scaffold.js +36 -1
  77. package/tests/check-screenshots.js +117 -0
  78. package/tests/check-settle-verbs.js +137 -0
  79. package/tests/check-time-limit.js +104 -0
  80. package/tests/check-video.js +156 -0
  81. package/tests/check-world.js +167 -0
  82. package/tests/features/api-base-url.feature +25 -0
  83. package/tests/features/api-form-data.feature +18 -0
  84. package/tests/features/api-json-paths.feature +24 -0
  85. package/tests/features/api-response-contains.feature +21 -0
  86. package/tests/features/api-response-header-presence.feature +17 -0
  87. package/tests/features/api-response-header.feature +17 -0
  88. package/tests/features/api-saved-placeholders.feature +37 -0
  89. package/tests/features/api-step-definitions-individual.feature +1 -1
  90. package/tests/features/api-tables.feature +40 -0
  91. package/tests/features/breakpoints.feature +25 -0
  92. package/tests/features/choice-controls.feature +35 -0
  93. package/tests/features/complete-api-testing-examples.feature +1 -1
  94. package/tests/features/datetime-field-lookup.feature +29 -0
  95. package/tests/features/element-selector-hint.feature +14 -0
  96. package/tests/features/field-state.feature +21 -0
  97. package/tests/features/fill-in-empty-value.feature +41 -0
  98. package/tests/features/fill-reachable.feature +13 -0
  99. package/tests/features/iframe-nested.feature +43 -0
  100. package/tests/features/javascript-tolerated-errors.feature +20 -0
  101. package/tests/features/modal-open.feature +13 -0
  102. package/tests/features/multi-value-field-lookup.feature +30 -0
  103. package/tests/features/registered-names.feature +14 -0
  104. package/tests/features/select-by-label.feature +31 -0
  105. package/tests/features/selector-files.feature +14 -0
  106. package/tests/features/selectors-table-header.feature +35 -0
  107. package/tests/features/settle-budget.feature +11 -0
  108. package/tests/features/sorted-tables.feature +19 -0
  109. package/tests/features/storage-quoted-values.feature +26 -0
  110. package/tests/features/text-matching.feature +38 -0
  111. package/tests/features/text-order.feature +14 -0
  112. package/tests/features/touch.feature +21 -0
  113. package/tests/features/viewport-top.feature +13 -0
  114. package/tests/features/xml-namespaces.feature +34 -0
  115. package/tests/must-fail/api-json-paths.feature +21 -0
  116. package/tests/must-fail/api-response-contains.feature +23 -0
  117. package/tests/must-fail/api-response-header-presence.feature +17 -0
  118. package/tests/must-fail/api-response-header.feature +21 -0
  119. package/tests/must-fail/api-without-base-url.feature +11 -0
  120. package/tests/must-fail/breakpoints.feature +15 -0
  121. package/tests/must-fail/choice-controls.feature +25 -0
  122. package/tests/must-fail/clock.feature +11 -0
  123. package/tests/must-fail/datetime-field.feature +10 -0
  124. package/tests/must-fail/element-selector-hint.feature +17 -0
  125. package/tests/must-fail/field-state.feature +20 -0
  126. package/tests/must-fail/fill-field.feature +30 -0
  127. package/tests/must-fail/iframe-text.feature +17 -0
  128. package/tests/must-fail/modal-open.feature +26 -0
  129. package/tests/must-fail/multi-value-field.feature +18 -0
  130. package/tests/must-fail/registered-names.feature +25 -0
  131. package/tests/must-fail/select-list.feature +15 -0
  132. package/tests/must-fail/selector-files.feature +10 -0
  133. package/tests/must-fail/sorted-tables.feature +20 -0
  134. package/tests/must-fail/storage-before-a-page.feature +13 -0
  135. package/tests/must-fail/text-matching.feature +16 -0
  136. package/tests/must-fail/text-order.feature +15 -0
  137. package/tests/must-fail/viewport-top.feature +20 -0
  138. package/tests/must-fail/yaml-numbers.feature +48 -0
  139. package/tests/step-definitions/a11y.steps.js +24 -15
  140. package/tests/step-definitions/action.steps.js +22 -8
  141. package/tests/step-definitions/api.steps.js +349 -67
  142. package/tests/step-definitions/assertion.steps.js +100 -10
  143. package/tests/step-definitions/auth.steps.js +15 -18
  144. package/tests/step-definitions/clock.steps.js +22 -0
  145. package/tests/step-definitions/debug.steps.js +8 -0
  146. package/tests/step-definitions/dialog.steps.js +7 -0
  147. package/tests/step-definitions/element.steps.js +132 -17
  148. package/tests/step-definitions/field.steps.js +409 -96
  149. package/tests/step-definitions/form.steps.js +76 -29
  150. package/tests/step-definitions/iframe.steps.js +89 -29
  151. package/tests/step-definitions/input.steps.js +26 -7
  152. package/tests/step-definitions/javascript.steps.js +64 -22
  153. package/tests/step-definitions/modal.steps.js +79 -13
  154. package/tests/step-definitions/navigation.steps.js +14 -0
  155. package/tests/step-definitions/network.steps.js +15 -5
  156. package/tests/step-definitions/response.steps.js +6 -4
  157. package/tests/step-definitions/responsive.steps.js +26 -33
  158. package/tests/step-definitions/screenshot.steps.js +25 -8
  159. package/tests/step-definitions/scroll.steps.js +20 -0
  160. package/tests/step-definitions/selectors.steps.js +95 -48
  161. package/tests/step-definitions/storage.steps.js +38 -13
  162. package/tests/step-definitions/table.steps.js +81 -6
  163. package/tests/step-definitions/video.steps.js +52 -55
  164. package/tests/step-definitions/wait.steps.js +88 -23
  165. package/tests/step-definitions/web-first.steps.js +69 -35
  166. package/tests/step-definitions/webship.js +681 -143
  167. package/tests/step-definitions/xml.steps.js +49 -15
  168. package/tests/step-definitions/yaml.steps.js +45 -20
@@ -2,7 +2,7 @@ version: 2.1
2
2
 
3
3
  defaults: &defaults
4
4
  docker:
5
- - image: cimg/node:20.20
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, so
4
- # chromium + every apt dependency are pre-installed. Anyone running a Drone
5
- # server can drop the repo in: enable in the UI and push.
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.58.2-jammy
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:20
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. The free
4
- # Developer plan includes 90 build credits/day on hosted Linux x86 builds —
5
- # enough for ~9 runs of the 9-minute suite per day. After signup, point a
6
- # Git Sync connector at this repo and pick `.harness/webship-js-pipeline.yml`
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/cucumber_report.{html,pdf,json}
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")>
@@ -1,7 +1,7 @@
1
1
  # Semaphore CI for webship-js.
2
2
  #
3
- # Free tier: 1,300 build-minutes per month on `e1-standard-2` (2 vCPU, 4 GB).
4
- # Open-source projects qualify for additional minutes via the Startup plan.
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 20
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/cucumber_report.html --expire-in 30d || true
54
- - artifact push job tests/reports/cucumber_report.pdf --expire-in 30d || true
55
- - artifact push job tests/reports/cucumber_report.json --expire-in 30d || true
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
@@ -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
- // Free tier: 600 build-minutes / month + 1 build agent + 100 build configs.
15
- // The 9-minute suite fits ~66 runs / month.
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.2-jammy"
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/cucumber_report.html
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
- - "20"
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/` — 417 steps across 36
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_*`, `WEBSHIP_SELECTORS_OFFSET`,
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
- * **The init script** installed via `context.addInitScript()` in
98
- `openBrowser()` — monkey-patches `fetch`, `XMLHttpRequest.send`,
99
- `setTimeout`/`clearTimeout` and attaches a `MutationObserver` to
100
- maintain `window.__webshipAjaxCount`, `__webshipPendingTimers`,
101
- `__webshipLastMutation`. This is the substrate the whole wait policy
102
- stands on. **Never strip it.**
103
- * **Hooks** — `Before({order:5})` opens the browser (merging
104
- `recordVideo` context options when video is on); `After({order:5})`
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
- (`WEBSHIP_FILTER_HOOK_LINES=off` to disable), and a `process.on('exit')`
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
- 417 built-in steps across 36 step files. Cucumber auto-loads every
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 (22) # REST long form — base URL, headers, query, body, JSON Pointer
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 (19) # focus / scroll-to / dispatch / count / position
278
- ├── field.steps.js (27) # field, checkbox, radio, select-list state assertions
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/ # 73 .feature files
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 text matches `STATE_MUTATING_STEP` (click / press / fill /
335
- select / check / attach / reload / navigate / …). This is what makes
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 so chromium + all apt deps are baked in.
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.58.2-jammy'
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/cucumber_report.html,tests/reports/cucumber_report.pdf,tests/reports/cucumber_report.json,screenshots/**/*',
52
+ archiveArtifacts artifacts: 'tests/reports/**/*,screenshots/**/*,videos/**/*',
51
53
  allowEmptyArchive: true
52
54
  }
53
55
  }
@@ -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. Free tier for
4
- # public projects: 10 parallel jobs, unlimited minutes. Free tier for private
5
- # projects: 1 job, 1,800 minutes / month.
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: '20.x'
39
- displayName: 'Install Node 20'
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: failed()
78
+ condition: always()
79
+ continueOnError: true
79
80
  inputs:
80
81
  pathToPublish: 'screenshots'
81
- artifactName: 'failure-screenshots'
82
- displayName: 'Publish failure screenshots'
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'
@@ -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 self-hosted instance.
4
- # (Bamboo Cloud was retired by Atlassian on 2024-02-15; the YAML below
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.58.2-jammy
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-html
65
- pattern: tests/reports/cucumber_report.html
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