webship-js 2.0.3 → 2.0.4

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 (49) hide show
  1. package/.circleci/config.yml +7 -31
  2. package/.drone.yml +68 -0
  3. package/.harness/webship-js-pipeline.yml +101 -0
  4. package/.semaphore/semaphore.yml +58 -0
  5. package/.teamcity/pom.xml +52 -0
  6. package/.teamcity/settings.kts +92 -0
  7. package/.travis.yml +24 -3
  8. package/AGENTS.md +2 -2
  9. package/CLAUDE.md +2 -2
  10. package/Jenkinsfile +54 -0
  11. package/azure-pipelines.yml +82 -0
  12. package/bamboo-specs/bamboo.yml +131 -0
  13. package/buildspec.yml +56 -0
  14. package/cloudbuild.yaml +49 -0
  15. package/codefresh.yml +77 -0
  16. package/cucumber.js +40 -3
  17. package/docs/04-step-reference.md +74 -3
  18. package/docs/16-ci-cd.md +879 -0
  19. package/docs/README.md +113 -0
  20. package/docs/global-settings.md +51 -0
  21. package/examples/video-demo.html +43 -0
  22. package/package.json +1 -1
  23. package/tests/features/video.feature +18 -0
  24. package/tests/step-definitions/a11y.steps.js +3 -1
  25. package/tests/step-definitions/action.steps.js +2 -2
  26. package/tests/step-definitions/api.steps.js +17 -16
  27. package/tests/step-definitions/assertion.steps.js +2 -2
  28. package/tests/step-definitions/auth.steps.js +3 -1
  29. package/tests/step-definitions/clock.steps.js +38 -38
  30. package/tests/step-definitions/debug.steps.js +13 -5
  31. package/tests/step-definitions/element.steps.js +47 -5
  32. package/tests/step-definitions/file-download.steps.js +38 -20
  33. package/tests/step-definitions/form.steps.js +6 -6
  34. package/tests/step-definitions/iframe.steps.js +65 -15
  35. package/tests/step-definitions/input.steps.js +47 -8
  36. package/tests/step-definitions/javascript.steps.js +195 -34
  37. package/tests/step-definitions/keyboard.steps.js +38 -4
  38. package/tests/step-definitions/modal.steps.js +39 -14
  39. package/tests/step-definitions/network.steps.js +61 -19
  40. package/tests/step-definitions/responsive.steps.js +3 -1
  41. package/tests/step-definitions/selectors.steps.js +19 -17
  42. package/tests/step-definitions/video.steps.js +178 -0
  43. package/tests/step-definitions/web-first.steps.js +3 -1
  44. package/tests/step-definitions/webship.js +234 -15
  45. package/tests/step-definitions/xml.steps.js +4 -2
  46. package/tests/step-definitions/yaml.steps.js +13 -11
  47. package/videos/README.md +32 -0
  48. package/.travis-ci.yml +0 -16
  49. package/docs/index.md +0 -104
@@ -0,0 +1,879 @@
1
+ # CI / CD setup
2
+
3
+ Webship-js ships ready-to-use config files for every major CI/CD provider. The pattern is the same everywhere: install Node 20, install Playwright's chromium with its system deps, start the fixture server on port 8080, run `npm test`. No build step — `tsx` transpiles `.ts` step files on the fly.
4
+
5
+ ## Supported providers
6
+
7
+ | Provider | File | Account needed | Badge |
8
+ | --- | --- | --- | --- |
9
+ | GitHub Actions | `.github/workflows/github-actions.yml` | GitHub | yes |
10
+ | GitLab CI | `.gitlab-ci.yml` | GitLab | yes |
11
+ | CircleCI | `.circleci/config.yml` | CircleCI | yes |
12
+ | Bitbucket Pipelines | `bitbucket-pipelines.yml` | Bitbucket | yes |
13
+ | Travis CI | `.travis.yml` | travis-ci.com | yes |
14
+ | Jenkins | `Jenkinsfile` | self-hosted | no |
15
+ | Azure Pipelines | `azure-pipelines.yml` | dev.azure.com | yes |
16
+ | AWS CodeBuild | `buildspec.yml` | aws.amazon.com | indirect (via CloudWatch) |
17
+ | Google Cloud Build | `cloudbuild.yaml` | console.cloud.google.com | indirect (via shields.io endpoint) |
18
+ | TeamCity | `.teamcity/settings.kts` (+ `pom.xml`) | jetbrains.com/teamcity | yes (shields.io endpoint) |
19
+ | Semaphore | `.semaphore/semaphore.yml` | semaphoreci.com | yes |
20
+ | Drone CI | `.drone.yml` | self-hosted | yes (shields.io endpoint) |
21
+ | Woodpecker CI | reuses `.drone.yml` | self-hosted | yes |
22
+ | Forgejo Actions | reuses `.github/workflows/*` | Forgejo/Codeberg | yes |
23
+ | Harness CI | `.harness/webship-js-pipeline.yml` | app.harness.io | yes |
24
+ | Bamboo Data Center | `bamboo-specs/bamboo.yml` | self-hosted (Atlassian) | yes |
25
+ | Codefresh | `codefresh.yml` | codefresh.io | yes |
26
+ | Octopus Deploy | (no test runner — CD only, see notes) | octopus.com | n/a |
27
+ | ~~Codeship~~ | retired 2023 — do not use | — | — |
28
+
29
+ Each provider's setup notes live in its own section below.
30
+
31
+ ---
32
+
33
+ ## GitHub Actions
34
+
35
+ **File**: `.github/workflows/github-actions.yml`.
36
+
37
+ GitHub's native CI/CD. #1 by adoption (~33% of all open-source repos according to JetBrains' 2024 Dev Ecosystem Survey). Free tier: 2,000 minutes per month for private repos, **unlimited** for public repos. Linux minutes count 1:1, macOS 10:1, Windows 2:1.
38
+
39
+ ### Setup steps — open account + connect repo
40
+
41
+ 1. **Sign up for GitHub** at <https://github.com/signup>. Free.
42
+ 2. **Fork or push the repo**. Workflows under `.github/workflows/` are picked up automatically — no UI step needed.
43
+ 3. **Enable Actions** if you forked: `repo → Settings → Actions → General → Allow all actions`. New repos have Actions enabled by default.
44
+ 4. **Add secrets** (optional, only if a step needs them): `Settings → Secrets and variables → Actions → New repository secret`. None are required for the shipped workflow.
45
+
46
+ ### Workflow contents
47
+
48
+ Single job `build` on `ubuntu-latest`:
49
+
50
+ 1. `actions/checkout@v3` — pulls the repo.
51
+ 2. `actions/setup-node@v3` — Node 20.x.
52
+ 3. `npm install`.
53
+ 4. `npx playwright install --with-deps chromium`.
54
+ 5. `npm start &` — backgrounds the fixture server.
55
+ 6. `sleep 3`.
56
+ 7. `npm test`.
57
+
58
+ `FORCE_COLOR=1` is set on the job so cucumber-js v10 emits ANSI colours.
59
+
60
+ ### Badge
61
+
62
+ Already shipped in `README.md`:
63
+
64
+ ```markdown
65
+ [![Github Actions](https://github.com/webship/webship-js/actions/workflows/github-actions.yml/badge.svg?branch=2.0.x)](https://github.com/webship/webship-js/actions)
66
+ ```
67
+
68
+ The badge follows the workflow file name and branch — no extra setup.
69
+
70
+ ### Reports
71
+
72
+ The current workflow does not upload artefacts. To add them, append:
73
+
74
+ ```yaml
75
+ - uses: actions/upload-artifact@v4
76
+ if: always()
77
+ with:
78
+ name: cucumber-report
79
+ path: |
80
+ tests/reports/cucumber_report.html
81
+ tests/reports/cucumber_report.pdf
82
+ tests/reports/cucumber_report.json
83
+ screenshots/
84
+ ```
85
+
86
+ ### Notes
87
+
88
+ - A deprecation warning fires on every run: `actions/checkout@v3` and `actions/setup-node@v3` use Node 20 internally; GitHub will force Node 24 on 2026-06-02. Bump to `@v4` (which targets Node 24) before then. We left them at `@v3` for now so existing forks do not need to rewrite YAML.
89
+ - The fixture server is a tiny `http-server` static site on port 8080 — no Docker daemon required on the runner.
90
+ - For per-browser matrix: add `strategy.matrix.browser: [chromium, firefox, webkit]` + `BROWSER: ${{ matrix.browser }}` to the env block, and replace `chromium` in the playwright install line with `${{ matrix.browser }}`.
91
+
92
+ ---
93
+
94
+ ## GitLab CI
95
+
96
+ **File**: `.gitlab-ci.yml`.
97
+
98
+ GitLab's first-party CI/CD. #3 by adoption (~19%). Free tier on GitLab.com: 400 compute-minutes per month on shared runners. Self-hosted GitLab gives unlimited minutes on your own runners.
99
+
100
+ ### Setup steps — open account + connect repo
101
+
102
+ 1. **Sign up for GitLab.com**: <https://gitlab.com/users/sign_up> (free) or stand up a self-hosted GitLab.
103
+ 2. **Push the repo** (or mirror it from GitHub via `Settings → Repository → Mirroring repositories`).
104
+ 3. **Enable CI/CD**: `repo → Settings → CI/CD → General pipelines`. On by default for new projects.
105
+ 4. **Shared runners**: enabled by default on GitLab.com. Self-hosted? Register a runner via `gitlab-runner register` against the controller URL.
106
+ 5. **Set CI/CD variables** (optional): `Settings → CI/CD → Variables`. None required for the shipped pipeline.
107
+
108
+ ### Pipeline contents
109
+
110
+ Single job `test` running on the `node:20` image:
111
+
112
+ 1. `npm install`.
113
+ 2. `npx playwright install --with-deps chromium`.
114
+ 3. `npm start &` + `sleep 3`.
115
+ 4. `npm test`.
116
+
117
+ `FORCE_COLOR: "1"` is set in the job's `variables:` block.
118
+
119
+ ### Badge
120
+
121
+ Already shipped in `README.md`:
122
+
123
+ ```markdown
124
+ [![Gitlab CI](https://gitlab.com/webship/webship-js/badges/2.0.x/pipeline.svg?job=karma&key_text=Gitlab+CI&key_width=60)](https://gitlab.com/webship/webship-js/-/pipelines)
125
+ ```
126
+
127
+ The `job=` query param targets a specific job's status; drop it to show the whole pipeline.
128
+
129
+ ### Reports
130
+
131
+ Add artefacts to any job:
132
+
133
+ ```yaml
134
+ test:
135
+ artifacts:
136
+ when: always
137
+ expire_in: 30 days
138
+ paths:
139
+ - tests/reports/cucumber_report.html
140
+ - tests/reports/cucumber_report.pdf
141
+ - tests/reports/cucumber_report.json
142
+ - screenshots/
143
+ reports:
144
+ junit: tests/reports/junit.xml # if you add --format junit:
145
+ ```
146
+
147
+ GitLab renders JUnit XML inline on the merge-request page.
148
+
149
+ ### Notes
150
+
151
+ - The `node:20` Docker image is slim — installing chromium via `--with-deps` adds ~120 MB on the first run. Use `cache:` keyed on `package-lock.json` to skip on reruns.
152
+ - Merge-request pipelines (`workflow.rules`) trigger by default; add `rules:` to scope to specific branches.
153
+ - For self-hosted runners on macOS / Windows, set `tags:` on the job and on the runner registration so the right runner picks up the work.
154
+ - Per-browser matrix: use `parallel.matrix` with `BROWSER: [chromium, firefox, webkit]`.
155
+
156
+ ---
157
+
158
+ ## Bitbucket Pipelines
159
+
160
+ **File**: `bitbucket-pipelines.yml`.
161
+
162
+ Atlassian Bitbucket's native CI/CD. Free tier: 50 build-minutes per month for private repos, **unlimited** for public repos. Linked tightly to Jira / Confluence / Trello so handy in Atlassian-stack shops.
163
+
164
+ ### Setup steps — open account + connect repo
165
+
166
+ 1. **Sign up for Bitbucket**: <https://bitbucket.org/account/signup> → email or Google / Apple / Microsoft SSO.
167
+ 2. **Create a workspace** (e.g. `webshipco`). Required — every repo lives inside a workspace.
168
+ 3. **Create or import the repo**. Bitbucket can import from GitHub directly.
169
+ 4. **Enable Pipelines**: `repo → Repository settings → Pipelines → Settings → Enable Pipelines`. Toggle is off by default until you read & accept the runner terms.
170
+ 5. **(Optional) Self-hosted runners**: `Repository settings → Pipelines → Runners → Add runner`. Skips the free-tier minute cap.
171
+
172
+ ### Pipeline contents
173
+
174
+ `bitbucket-pipelines.yml` defines a single default pipeline:
175
+
176
+ ```yaml
177
+ image: node:20
178
+ pipelines:
179
+ branches:
180
+ 2.0.x:
181
+ - step:
182
+ script:
183
+ - npm install
184
+ - npx playwright install --with-deps chromium
185
+ - npm start &
186
+ - sleep 3
187
+ - npm test
188
+ ```
189
+
190
+ `FORCE_COLOR=1` is set in the job's `variables:` block.
191
+
192
+ ### Badge
193
+
194
+ Already shipped in `README.md`:
195
+
196
+ ```markdown
197
+ [![Bitbucket Pipelines](https://img.shields.io/bitbucket/pipelines/webshipco/webship-js/2.0.x)](https://bitbucket.org/webshipco/webship-js/pipelines)
198
+ ```
199
+
200
+ Uses shields.io as a proxy because Bitbucket does not expose a native SVG endpoint. Replace `webshipco/webship-js` with your workspace + repo slug.
201
+
202
+ ### Reports
203
+
204
+ Add `artifacts:` to a step:
205
+
206
+ ```yaml
207
+ - step:
208
+ name: test
209
+ script: [ npm test ]
210
+ artifacts:
211
+ - tests/reports/cucumber_report.html
212
+ - tests/reports/cucumber_report.pdf
213
+ - tests/reports/cucumber_report.json
214
+ - screenshots/**
215
+ ```
216
+
217
+ Artefacts live for 14 days on the free tier, 30 days on paid plans. Download from the build page.
218
+
219
+ ### Notes
220
+
221
+ - Each step gets ~4 GB RAM and 2 vCPU by default — fine for the 9-minute suite. `size: 2x` bumps to 8 GB / 4 vCPU at 2× the minutes.
222
+ - `pipelines.branches.2.0.x` scopes the pipeline to that branch only; add `pull-requests:` for PR builds.
223
+ - Atlassian's Pipes (`pipe:`) catalogue covers Slack notifications, AWS deploys, Jira issue transitions, etc. — drop them into the `script:` section as named steps.
224
+ - Per-browser matrix: define three steps under `parallel:` with `BROWSER` env variations.
225
+
226
+ ---
227
+
228
+ ## CircleCI
229
+
230
+ **File**: `.circleci/config.yml`.
231
+
232
+ CircleCI ships with a free tier of 6,000 build-minutes per month on Linux x86 medium (4 GB / 2 vCPU). Fits ~666 runs of the 9-minute suite. Active badge on `webship.co`.
233
+
234
+ ### Setup steps — open account + connect repo
235
+
236
+ 1. **Sign up**: <https://circleci.com/signup/> → "Sign Up with GitHub" → authorise the CircleCI GitHub App on `webship/webship-js`.
237
+ 2. **Choose an organisation** (your GitHub org / user). CircleCI mirrors the GitHub permissions model.
238
+ 3. **Set up the project**: dashboard → `Projects → Set up project` → pick `webship-js` → "Use the .circleci/config.yml in my repo" → branch `2.0.x`.
239
+ 4. **Pick a plan**: the **Free** plan covers OSS comfortably. The **Performance** plan adds Docker layer caching and more concurrency.
240
+
241
+ ### Pipeline contents
242
+
243
+ `.circleci/config.yml` uses the `cimg/node:20.20` Docker executor (Node + npm preinstalled). Steps:
244
+
245
+ 1. `checkout`.
246
+ 2. `npm install`.
247
+ 3. `npx playwright install --with-deps chromium`.
248
+ 4. `npm start &` + `sleep 3`.
249
+ 5. `npm test`.
250
+
251
+ `FORCE_COLOR: "1"` is exported in the job environment. Filter `branches.only: /^2.0.x/` keeps feature-branch pushes off the queue.
252
+
253
+ ### Badge
254
+
255
+ Already shipped in `README.md`:
256
+
257
+ ```markdown
258
+ [![CircleCI](https://circleci.com/gh/webship/webship-js/tree/2.0.x.svg?style=svg)](https://circleci.com/gh/webship/webship-js/tree/2.0.x)
259
+ ```
260
+
261
+ `/gh/` is the legacy VCS path (still works); `/circleci/<org-slug>` is the newer form.
262
+
263
+ ### Reports + screenshots
264
+
265
+ Add `store_artifacts` to the test step:
266
+
267
+ ```yaml
268
+ - store_artifacts:
269
+ path: tests/reports
270
+ destination: cucumber-report
271
+ - store_artifacts:
272
+ path: screenshots
273
+ destination: failure-screenshots
274
+ when: on_fail
275
+ ```
276
+
277
+ Artefacts are retained for 30 days and rendered as downloadable links on the build page.
278
+
279
+ ### Notes
280
+
281
+ - `cimg/node:20.20` is CircleCI's "convenience image" — much smaller cold-start than `node:20` from Docker Hub.
282
+ - The earlier config used `cimg/base:stable-20.04` with manual `apt upgrade` and a NodeSource curl-pipe. That path hit 200-package apt upgrades and PPA 503s (issue #280) and was replaced with the slim form documented above.
283
+ - Docker layer caching is gated behind the Performance plan — toggle in the executor block with `docker_layer_caching: true` when you upgrade.
284
+ - Per-browser matrix: use a `matrix` block under `jobs:` or duplicate the job per browser.
285
+
286
+ ---
287
+
288
+ ## Jenkins
289
+
290
+ **File**: `Jenkinsfile` (declarative pipeline, at repo root).
291
+
292
+ Jenkins has no SaaS — you run a controller yourself. The shipped `Jenkinsfile` uses the official `mcr.microsoft.com/playwright:v1.58.2-jammy` Docker image so chromium and every apt dependency are already inside.
293
+
294
+ ### Setup steps
295
+
296
+ 1. **Run a Jenkins controller**. Fastest path is Docker:
297
+ ```bash
298
+ docker run -d --name jenkins \
299
+ -p 8080:8080 -p 50000:50000 \
300
+ -v jenkins_home:/var/jenkins_home \
301
+ -v /var/run/docker.sock:/var/run/docker.sock \
302
+ --group-add $(stat -c '%g' /var/run/docker.sock) \
303
+ jenkins/jenkins:lts
304
+ ```
305
+ The mount + `--group-add` are critical — the pipeline spawns a sibling container for the Playwright image and needs the host's Docker socket.
306
+ 2. **First-run unlock**: `docker logs jenkins | grep -A 1 "initialAdminPassword"` → paste at `http://localhost:8080`. Pick **Install suggested plugins**. That set already includes the Docker Pipeline plugin we rely on.
307
+ 3. **Create an admin user** when prompted.
308
+ 4. **Configure GitHub credentials**: *Manage Jenkins → Credentials → System → Global → Add* → kind `Username with password` (or `SSH Username with private key`), id `github-creds`.
309
+ 5. **New Item → Pipeline**. Name `webship-js`.
310
+ - *Build Triggers*: `Poll SCM` `H/5 * * * *` or `GitHub hook trigger`.
311
+ - *Pipeline*: `Pipeline script from SCM` → Git → repo URL → credential `github-creds` → branch `*/2.0.x` → script path `Jenkinsfile`.
312
+ 6. **Save** → **Build Now**. First run pulls the Playwright image (~1 GB) — cached afterwards.
313
+
314
+ ### Reports + screenshots
315
+
316
+ The `post { always }` block archives `tests/reports/cucumber_report.{html,pdf,json}` and any `screenshots/**`. Browse them per build in the Jenkins UI under "Build Artifacts".
317
+
318
+ ### Badge
319
+
320
+ Jenkins has no public badge endpoint by default — the controller is usually private. If you expose Jenkins publicly, use the **Embeddable Build Status** plugin which provides `BASE/buildStatus/icon?job=webship-js&style=plastic` and paste that URL in `README.md`.
321
+
322
+ ### Notes
323
+
324
+ - `args '-u root:root'` runs the container as root so `npm install` and `npx playwright install --with-deps` can touch system paths. Switch to a non-root image if you tighten security.
325
+ - The Playwright base image already has every browser dep, so `--with-deps` is a no-op — kept for symmetry with other lanes.
326
+ - Need parallelism? Wrap the `Test` stage in `parallel { stage('chromium') {...}; stage('firefox') {...} }` and switch the image to `mcr.microsoft.com/playwright` (latest) which includes all three browsers.
327
+
328
+ ---
329
+
330
+ ## Azure Pipelines
331
+
332
+ **File**: `azure-pipelines.yml` at repo root.
333
+
334
+ Microsoft's hosted CI, generous free tier for both public and private repos. Microsoft-hosted `ubuntu-latest` agents already have Node + most browser deps; the pipeline still calls `--with-deps` for safety.
335
+
336
+ ### Setup steps — open account + connect repo
337
+
338
+ 1. **Microsoft account**: if you do not already have one, create at <https://account.microsoft.com/>. Free.
339
+ 2. **Sign in to Azure DevOps**: <https://dev.azure.com> → "Start free with GitHub" *or* sign in with the Microsoft account.
340
+ 3. **Create an Organization**. Pick a unique slug (used in the URL `https://dev.azure.com/<org>/`). Example: `webship`.
341
+ 4. **Create a Project**. Name `webship-js`. Visibility:
342
+ - **Public** for open source — unlocks the free OSS tier (10 parallel jobs, unlimited minutes).
343
+ - **Private** otherwise (1 free parallel job, 1,800 min/mo).
344
+ 5. **Pipelines → Create Pipeline → GitHub**. Authorise the **Azure Pipelines** GitHub app, scope it to `webship/webship-js`.
345
+ 6. **Configure your pipeline**: choose **"Existing Azure Pipelines YAML file"** → branch `2.0.x` → path `/azure-pipelines.yml` → **Continue → Run**.
346
+ 7. **Request OSS free parallelism** (only for public projects): `Organization settings → Billing → Public project parallelism request`. Microsoft enables it manually within a day or two.
347
+
348
+ ### Badge
349
+
350
+ After the first build runs, copy the badge URL from `Pipelines → … → Status badge`:
351
+
352
+ ```markdown
353
+ [![Azure Pipelines](https://dev.azure.com/<org>/<project>/_apis/build/status/webship-js?branchName=2.0.x)](https://dev.azure.com/<org>/<project>/_build/latest?definitionId=<id>&branchName=2.0.x)
354
+ ```
355
+
356
+ Replace `<org>`, `<project>`, `<id>`. Paste into `README.md` next to the other badges.
357
+
358
+ ### Reports
359
+
360
+ The pipeline publishes two build artefacts:
361
+
362
+ - `cucumber-report` — `tests/reports/cucumber_report.{html,pdf,json}`
363
+ - `failure-screenshots` (only on failure) — every `screenshots/**/*` capture
364
+
365
+ Browse via **Pipelines → Run → Artifacts → 1 published**.
366
+
367
+ ### Caching
368
+
369
+ Two `Cache@2` tasks are configured:
370
+
371
+ | Key | Path | Effect |
372
+ | --- | --- | --- |
373
+ | `npm \| <os> \| package.json` | `$(Pipeline.Workspace)/.npm` | Cuts `npm install` to seconds when `package.json` is unchanged. |
374
+ | `playwright \| <os>` | `$(HOME)/.cache/ms-playwright` | Skips the chromium download (~120 MB) on reruns. |
375
+
376
+ ### Notes
377
+
378
+ - `trigger.tags` matches `2.0.*` so a tag push runs the pipeline once. Adjust if you tag differently.
379
+ - `pr.branches` triggers on PRs targeting `2.0.x` — Azure runs the PR head against the target branch.
380
+ - `npm start &` backgrounds the fixture server; `curl -sf` then fails fast if the bind never landed.
381
+ - If you want a per-browser matrix, replace `steps:` with `jobs:` + `strategy.matrix: { chromium: {BROWSER: chromium}, firefox: {BROWSER: firefox} }` and add `--with-deps $(BROWSER)`.
382
+
383
+ ---
384
+
385
+ ## AWS CodeBuild
386
+
387
+ **File**: `buildspec.yml` at repo root.
388
+
389
+ AWS-managed build service. Free tier: 100 build-minutes per month on the `general1.small` compute class indefinitely. The 9-minute suite fits roughly 11 free runs / month — beyond that, each minute costs ~$0.005.
390
+
391
+ ### Setup steps — open account + create project
392
+
393
+ 1. **Create an AWS account** at <https://aws.amazon.com/>. Requires a credit card, phone verification, and an email confirmation. The 12-month free tier and the always-free CodeBuild tier both apply.
394
+ 2. **Sign in to the AWS Console** → switch to a region close to you (e.g. `us-east-1`, `eu-west-1`).
395
+ 3. **IAM → Roles → Create role**:
396
+ - Trusted entity: **AWS service** → **CodeBuild**.
397
+ - Permissions: attach `AmazonS3FullAccess` (artefact upload) and `CloudWatchLogsFullAccess`.
398
+ - Name: `webship-js-codebuild-role`.
399
+ 4. **S3 → Create bucket** for artefacts (e.g. `webship-js-reports`). Region must match the CodeBuild region.
400
+ 5. **CodeBuild → Create build project**:
401
+ - Project name: `webship-js`.
402
+ - Source provider: **GitHub** → "Connect using OAuth" → authorise the AWS CodeBuild GitHub app → pick `webship/webship-js` → branch `2.0.x`.
403
+ - Webhook: tick "Rebuild every time a code change is pushed".
404
+ - Environment: **Managed image** → operating system **Ubuntu** → runtime **Standard** → image `aws/codebuild/standard:7.0` → privileged unchecked.
405
+ - Service role: pick the existing `webship-js-codebuild-role` you just created.
406
+ - Build spec: **Use a buildspec file** → buildspec name `buildspec.yml` (default).
407
+ - Artifacts: **Amazon S3** → bucket `webship-js-reports` → name `webship-js-report-$(date)`.
408
+ - Logs: tick CloudWatch Logs → group `/aws/codebuild/webship-js`.
409
+ 6. **Create build project → Start build**.
410
+
411
+ ### Badge
412
+
413
+ CodeBuild has no native badge endpoint. Two common patterns:
414
+
415
+ 1. **GitHub commit status**: CodeBuild posts the build status to the GitHub commit, so the GitHub UI shows pass / fail next to each commit.
416
+ 2. **shields.io custom badge**: write a tiny Lambda that polls CodeBuild's `BatchGetBuilds` API and exposes a JSON endpoint; shields.io renders it via `https://img.shields.io/endpoint?url=https://...`.
417
+
418
+ ### Reports
419
+
420
+ `buildspec.yml` declares artefacts:
421
+
422
+ ```
423
+ tests/reports/cucumber_report.html
424
+ tests/reports/cucumber_report.pdf
425
+ tests/reports/cucumber_report.json
426
+ screenshots/**/*
427
+ ```
428
+
429
+ They land in the configured S3 bucket. Grant pre-signed URLs or make the bucket public if you want links you can share.
430
+
431
+ ### Caching
432
+
433
+ `cache.paths` lists `node_modules`, `/root/.cache/ms-playwright`, and the npm cache. Enable caching in the CodeBuild project: **Artifacts → Additional configuration → Cache type → Local → Custom cache**. Skips most of `npm install` and the chromium download on reruns.
434
+
435
+ ### Notes
436
+
437
+ - 9-min suite × $0.005/min ≈ $0.045 per build past the free tier — cheap unless you push hundreds of builds.
438
+ - For multi-AZ or multi-region resilience, place the buildspec in `aws-codebuild/buildspec.yml` and point the CodeBuild project at that path — the file is just a relative source path.
439
+ - CodeBuild can run inside a VPC if your dev server needs private network access — toggle in **VPC configuration** before starting the first build.
440
+
441
+ ---
442
+
443
+ ## Google Cloud Build
444
+
445
+ **File**: `cloudbuild.yaml` at repo root.
446
+
447
+ Google's managed CI inside GCP. First $300 of usage is free for new accounts (90-day trial); after that the always-free tier covers ~120 build-minutes per day on the default `e2-standard-2` machine — about 13 runs of the 9-min suite per day.
448
+
449
+ ### Setup steps — open account + connect repo
450
+
451
+ 1. **Create a Google Cloud account** at <https://console.cloud.google.com/>. Sign in with a Google account, accept the terms, claim the $300 / 90-day credit (a card is required for verification but is not charged).
452
+ 2. **Create a Project**: top bar → "Select a project" → "New project" → name `webship-js`. Note the project ID — Cloud Build references it implicitly.
453
+ 3. **Enable billing** on the project: `Billing → Link a billing account`. Required even for free-tier-only usage.
454
+ 4. **Enable the Cloud Build API**: `APIs & Services → Library → Cloud Build API → Enable`. Wait ~30 s.
455
+ 5. **Create the artefact bucket**: `Cloud Storage → Buckets → Create` → name `webship-js-reports` (must be globally unique — prepend your project ID if taken) → region matching your build region.
456
+ 6. **Grant Cloud Build write to the bucket**: bucket → `Permissions → Grant access` → principal `<project-number>@cloudbuild.gserviceaccount.com` → role `Storage Object Creator`.
457
+ 7. **Connect GitHub**: `Cloud Build → Triggers → Manage repositories → Connect Repository` → GitHub (Cloud Build GitHub App) → install on `webship/webship-js`.
458
+ 8. **Create a Trigger**:
459
+ - Name `webship-js-2-0-x`.
460
+ - Event: **Push to a branch**.
461
+ - Source: select the GitHub repo + branch regex `^2\.0\.x$`.
462
+ - Configuration: **Cloud Build configuration file (yaml or json)** → location `Repository` → `/cloudbuild.yaml`.
463
+ - Service account: leave default (`<project-number>@cloudbuild.gserviceaccount.com`).
464
+ - Substitution variables (optional): override `_ARTIFACT_BUCKET` if your bucket differs.
465
+ - **Create**.
466
+ 9. **Test**: `Run trigger` → first build pulls the Playwright image (~1 GB, cached on the build pool afterwards).
467
+
468
+ ### Badge
469
+
470
+ Cloud Build has no native badge. Two workarounds:
471
+
472
+ 1. **Custom shields.io endpoint**: deploy a Cloud Function that calls `builds.list` filtered by the trigger ID + branch, returns shields.io JSON, then embed `https://img.shields.io/endpoint?url=https://<region>-<project>.cloudfunctions.net/buildBadge`.
473
+ 2. **Workflow Run badge via mirror**: if you mirror to GitHub Actions, the GH Actions badge already covers green/red status.
474
+
475
+ ### Reports
476
+
477
+ The `artifacts.objects` section uploads the HTML / PDF / JSON to `gs://webship-js-reports/<BUILD_ID>/` on every run. Browse via Cloud Storage UI or share pre-signed URLs.
478
+
479
+ ### Caching
480
+
481
+ Cloud Build does not have a first-class cache step. Common patterns:
482
+
483
+ 1. **Kaniko image cache** for Docker-based builds (not what this pipeline does).
484
+ 2. **Volume cache via `dir` + GCS sync**: copy `node_modules` and `~/.cache/ms-playwright` to GCS at the end of each build, restore at the start. Adds two extra steps but cuts a hot rerun from ~9 min to ~5 min.
485
+
486
+ ### Notes
487
+
488
+ - `options.logging: CLOUD_LOGGING_ONLY` skips the legacy log bucket — saves a few cents per build and avoids the IAM warning Cloud Build prints by default.
489
+ - `timeout: 1800s` matches the 30-minute cap from other lanes; the suite finishes in ~9 min headless.
490
+ - `_BRANCH_NAME` and `_ARTIFACT_BUCKET` are substitution variables — override per-trigger to point at a different bucket without forking the YAML.
491
+ - For per-browser parallelism, replace the single `step` with three steps, each setting `BROWSER=chromium/firefox/webkit` — `--with-deps` will fetch the matching browser deps inside the container.
492
+
493
+ ---
494
+
495
+ ## TeamCity Cloud
496
+
497
+ **Files**: `.teamcity/settings.kts` + `.teamcity/pom.xml` at repo root.
498
+
499
+ JetBrains' CI server, available as Cloud (SaaS, no install) or self-hosted. Cloud free tier: 600 build-minutes / month + 1 build agent + 100 build configs forever. The 9-minute suite fits ~66 runs / month.
500
+
501
+ ### Setup steps — open account + connect repo
502
+
503
+ 1. **JetBrains account**: <https://account.jetbrains.com/> → sign up (free, OAuth via GitHub / Google / Microsoft also works).
504
+ 2. **Start TeamCity Cloud trial**: <https://www.jetbrains.com/teamcity/cloud/> → "Start free trial" → confirm the JetBrains-issued instance URL (e.g. `https://webship.teamcity.com`). The trial collapses into the free tier when it ends.
505
+ 3. **Create a Project**: top bar `Administration → Projects → Create project`. Pick "From a repository URL" → paste the GitHub HTTPS URL → "Proceed". TeamCity creates a VCS root.
506
+ 4. **Authorise GitHub OAuth**: TeamCity asks for GitHub credentials the first time it touches the repo. Use a Personal Access Token with `repo` scope or the OAuth flow.
507
+ 5. **Enable Versioned Settings**: open the project → `Versioned Settings → Synchronization enabled → Kotlin DSL`. TeamCity will offer to scan the repo for `.teamcity/settings.kts` — point it at the file we shipped. Commit any generated config UUIDs back to the repo so the next clone is identical.
508
+ 6. **Add the GitHub token credential**: `Project → Connections → Add → GitHub.com` (used by the `commitStatusPublisher` feature). Name the credential `webship-js-github-token` to match the DSL reference.
509
+ 7. **First build**: open the **Test** build configuration → **Run**. TeamCity pulls the Playwright Docker image (~1 GB once) and runs the script step.
510
+
511
+ ### Badge
512
+
513
+ TeamCity has no native public badge. Common patterns:
514
+
515
+ 1. **shields.io endpoint** wrapping `app/rest/builds/buildType:WebshipJsTest/status.json`.
516
+ 2. **GitHub commit status** (already wired by the `commitStatusPublisher` feature in the DSL) — the GitHub UI shows pass / fail next to each commit.
517
+
518
+ ### Reports
519
+
520
+ `artifactRules` archives `tests/reports/cucumber_report.{html,pdf,json}` plus any `screenshots/**` capture. Browse per build under `Artifacts` in the TeamCity UI.
521
+
522
+ ### Notes
523
+
524
+ - `dockerImage = "mcr.microsoft.com/playwright:v1.58.2-jammy"` runs the script inside the official Playwright image — chromium and every apt dep are already there.
525
+ - `dockerRunParameters = "--user root:root --network host"` keeps the steps simple (no `sudo`, the local fixture server on `localhost:8080` is reachable without port mapping).
526
+ - `pom.xml` exists only so IntelliJ can resolve `configs-dsl-kotlin` types and give completion / inspections in the IDE. TeamCity Cloud ignores it at build time.
527
+ - Kotlin DSL version `2024.03` matches TeamCity Cloud at time of writing — TeamCity warns and offers an auto-upgrade when the server version moves past it.
528
+ - For per-browser matrix, wrap the `script` step in a `buildType.dependencies` chain or define three `BuildType` objects sharing a common parent — Kotlin DSL favours composition over YAML-style matrix.
529
+
530
+ ---
531
+
532
+ ## Semaphore
533
+
534
+ **File**: `.semaphore/semaphore.yml`.
535
+
536
+ Hosted CI with a developer-friendly UI and one of the fastest cold-build queues. Free tier: 1,300 build-minutes / month on `e1-standard-2` (2 vCPU, 4 GB). The 9-minute suite fits ~144 free runs / month. Open-source maintainers can request the Startup plan for additional minutes.
537
+
538
+ ### Setup steps — open account + connect repo
539
+
540
+ 1. **Sign up**: <https://semaphoreci.com/> → "Sign up with GitHub" → authorise the Semaphore GitHub App on `webship/webship-js`.
541
+ 2. **Pick a plan**: the default "Free" plan is fine. Public OSS repos qualify for the Startup tier (more minutes + parallel jobs) — apply via `Account → Billing → Open source program`.
542
+ 3. **Create project**: dashboard → "Create new project" → pick `webship-js` → branch `2.0.x` (Semaphore can auto-detect other branches later).
543
+ 4. **Choose pipeline source**: select "Customise the workflow" → "I have a configuration file in my repository" → point at `.semaphore/semaphore.yml`. Semaphore validates the YAML and shows a graph preview.
544
+ 5. **Add the project** → Semaphore queues the first run on a fresh worker. The `--with-deps` step pulls chromium apt deps; the cache stores `node_modules` + `~/.cache/ms-playwright` so reruns are fast.
545
+
546
+ ### Badge
547
+
548
+ Open the project → `Settings → Badge`. Semaphore emits the markdown directly:
549
+
550
+ ```markdown
551
+ [![Build Status](https://<org>.semaphoreci.com/badges/webship-js/branches/2.0.x.svg)](https://<org>.semaphoreci.com/projects/webship-js)
552
+ ```
553
+
554
+ Replace `<org>` with the organisation slug you picked at signup. Paste in `README.md`.
555
+
556
+ ### Reports
557
+
558
+ `epilogue.always` uploads `cucumber_report.{html,pdf,json}` to the per-job artefact store (`Artifacts` tab in the UI). `epilogue.on_failure` adds the `screenshots/` capture. `--expire-in 30d` keeps storage costs down by purging after a month — bump to `90d` or `--retain` for longer retention.
559
+
560
+ ### Caching
561
+
562
+ Two cache slots are populated in the `Install` block and restored in `prologue` for every job:
563
+
564
+ | Key | Path |
565
+ | --- | --- |
566
+ | `node-modules-$(checksum package.json)` | `node_modules` |
567
+ | `ms-playwright` | `~/.cache/ms-playwright` |
568
+
569
+ `checksum` busts the cache automatically when `package.json` changes.
570
+
571
+ ### Notes
572
+
573
+ - `sem-version node 20` is Semaphore's runtime switcher — preinstalled on every `os_image: ubuntu2204` agent.
574
+ - `agent.machine.type: e1-standard-2` is the free-tier default; bumping to `e2-standard-4` halves wall time but costs more minutes.
575
+ - `nohup npm start > /tmp/srv.log 2>&1 &` keeps the fixture server alive after the `commands` block exits; `curl -sf` is the same ready-probe as the other lanes.
576
+ - Add a `promotions` block (e.g. tag release, deploy to staging) once the test pipeline is stable — see Semaphore docs for the `auto_promote` shape.
577
+ - For per-browser matrix, add three jobs under the `Test` task and parameterise via env (`BROWSER=chromium` etc.) — Semaphore runs them in parallel within the free-tier concurrency limit.
578
+
579
+ ---
580
+
581
+ ## Drone CI
582
+
583
+ **File**: `.drone.yml` at repo root.
584
+
585
+ Open-source CI/CD that pipelines via simple YAML and runs steps in Docker containers. Drone Cloud (drone.io) moved to a paid model in 2023, so the open-source path is **self-host**. The shipped `.drone.yml` is provider-agnostic — anyone running a Drone server can enable the repo and go.
586
+
587
+ ### Setup steps — open account + bring up a server
588
+
589
+ There is **no SaaS sign-up** for the free version. You have two routes:
590
+
591
+ #### Route A — self-host Drone (recommended for OSS)
592
+
593
+ 1. Pick a host with Docker + a TLS-terminated domain (e.g. `ci.example.com`).
594
+ 2. Create a GitHub OAuth App at <https://github.com/settings/developers> →
595
+ New OAuth App → Homepage `https://ci.example.com` →
596
+ Authorization callback `https://ci.example.com/login`.
597
+ Save the Client ID and Client Secret.
598
+ 3. Generate a shared secret: `openssl rand -hex 16`.
599
+ 4. Run the server:
600
+ ```bash
601
+ docker run -d \
602
+ -e DRONE_GITHUB_CLIENT_ID=... \
603
+ -e DRONE_GITHUB_CLIENT_SECRET=... \
604
+ -e DRONE_RPC_SECRET=... \
605
+ -e DRONE_SERVER_HOST=ci.example.com \
606
+ -e DRONE_SERVER_PROTO=https \
607
+ -p 80:80 -p 443:443 \
608
+ -v /var/lib/drone:/data \
609
+ --restart=always --name=drone drone/drone:2
610
+ ```
611
+ 5. Run at least one runner (Docker is the common choice):
612
+ ```bash
613
+ docker run -d \
614
+ -e DRONE_RPC_PROTO=https \
615
+ -e DRONE_RPC_HOST=ci.example.com \
616
+ -e DRONE_RPC_SECRET=... \
617
+ -e DRONE_RUNNER_CAPACITY=2 \
618
+ -v /var/run/docker.sock:/var/run/docker.sock \
619
+ --restart=always --name=drone-runner drone/drone-runner-docker:1
620
+ ```
621
+ 6. Visit `https://ci.example.com` → sign in with GitHub → **Activate** `webship/webship-js`. Drone reads `.drone.yml` on the next push.
622
+
623
+ #### Route B — Drone Cloud (paid)
624
+
625
+ <https://drone.io> → "Sign up" → pick a paid plan. Then point at the same `.drone.yml`. No further config differences.
626
+
627
+ ### Badge
628
+
629
+ ```markdown
630
+ [![Build Status](https://ci.example.com/api/badges/webship/webship-js/status.svg?branch=2.0.x)](https://ci.example.com/webship/webship-js)
631
+ ```
632
+
633
+ Replace `ci.example.com` with your server hostname.
634
+
635
+ ### Reports
636
+
637
+ The `archive-reports` step tars `tests/reports/` + `screenshots/` into `/var/lib/drone/artifacts/cucumber-report-<build>.tar.gz` on the host. Serve the directory via a static file server (e.g. `python3 -m http.server` behind nginx) or copy to S3/GCS via an extra step.
638
+
639
+ ### Notes
640
+
641
+ - Pull-request runs are filtered out by `trigger.ref.exclude: refs/pull/**` — flip to allow forks once you have secret management figured out.
642
+ - The `archive-reports` step uses a host-mounted volume; if your runner is ephemeral (e.g. Kubernetes), swap the volume for an `s3` plugin or `drone/s3-cache`.
643
+ - `DRONE_BUILD_NUMBER` is provided by the server. Other handy vars: `DRONE_COMMIT_SHA`, `DRONE_BRANCH`, `DRONE_TAG`.
644
+ - Per-browser matrix: duplicate the `test` step three times with different `BROWSER` env values, or use the `matrix` keyword (Drone 1.x style).
645
+
646
+ ---
647
+
648
+ ## Woodpecker CI
649
+
650
+ **File**: reuses `.drone.yml`.
651
+
652
+ Woodpecker is a community-driven fork of Drone 0.8 that preserves the original Apache-2 licence. The pipeline syntax is a near-superset of `.drone.yml` — most files (ours included) run unchanged. Self-hosted only.
653
+
654
+ ### Setup steps
655
+
656
+ 1. Self-host Woodpecker: <https://woodpecker-ci.org/docs/administration/getting-started>. The Docker Compose example takes ~5 minutes to bring up.
657
+ 2. Enable the repo in the Woodpecker UI and trigger a build.
658
+ 3. If Woodpecker complains about Drone-specific keys, rename `.drone.yml` → `.woodpecker.yml` (or `.woodpecker/*.yml` for split pipelines). Most projects keep both as symlinks.
659
+
660
+ ### Badge
661
+
662
+ ```markdown
663
+ [![Build Status](https://ci.example.com/api/badges/webship/webship-js/status.svg?branch=2.0.x)](https://ci.example.com/repos/webship/webship-js)
664
+ ```
665
+
666
+ ### Notes
667
+
668
+ - Woodpecker reads the same `trigger`, `steps`, `image`, `commands` keys we already use.
669
+ - `when:` syntax matches Drone 1.x.
670
+ - For maximum compatibility, prefer `.woodpecker.yml`; some Drone-only keywords (e.g. `kind: pipeline` is optional in Woodpecker but tolerated).
671
+
672
+ ---
673
+
674
+ ## Forgejo Actions
675
+
676
+ **Files**: reuses `.github/workflows/*.yml`.
677
+
678
+ Forgejo is a hard fork of Gitea (used by Codeberg.org and many self-hosted shops). It implements a GitHub Actions-compatible runner via the [act_runner](https://forgejo.org/docs/latest/admin/actions/) project, so the existing `.github/workflows/github-actions.yml` runs without modification.
679
+
680
+ ### Setup steps
681
+
682
+ 1. Push the repo to a Forgejo instance (e.g. <https://codeberg.org/> for OSS — sign up with email).
683
+ 2. Enable Actions: `Repo Settings → Actions → Enable Repository Actions`.
684
+ 3. Make sure at least one `act_runner` is registered against the instance. Codeberg provides shared runners for OSS; self-hosted instances need a manual `act_runner register` step (see Forgejo docs).
685
+ 4. Push to branch `2.0.x` — the existing GitHub workflow YAML runs on the Forgejo runner.
686
+
687
+ ### Badge
688
+
689
+ ```markdown
690
+ [![Build Status](https://codeberg.org/webship/webship-js/badges/workflows/github-actions.yml/badge.svg?branch=2.0.x)](https://codeberg.org/webship/webship-js/actions)
691
+ ```
692
+
693
+ Adjust to your Forgejo host.
694
+
695
+ ### Notes
696
+
697
+ - `uses: actions/checkout@v3` and friends are pulled from the public GitHub registry by default — Forgejo proxies them. If you need to pin actions to a private registry, set `ACTIONS_RUNNER_HOOK_*` env vars on the runner.
698
+ - Forgejo does not run reusable workflows (`workflow_call`) yet (as of Forgejo 7) — split shared logic into shell scripts under `scripts/` and call them from the YAML if you need portability.
699
+ - Secret handling, matrix builds, and concurrency groups all work the same way as on GitHub.
700
+
701
+ ---
702
+
703
+ ## Harness CI
704
+
705
+ **File**: `.harness/webship-js-pipeline.yml`.
706
+
707
+ Harness ships an enterprise Software Delivery Platform; Harness CI is the build/test module. The Developer (free) plan covers 90 build credits per day on hosted Linux-x86 builders — fits ~9 runs of the 9-minute suite.
708
+
709
+ ### Setup steps — open account + connect repo
710
+
711
+ 1. **Sign up**: <https://app.harness.io/auth/#/signup> → email or Google/Microsoft SSO → confirm via email.
712
+ 2. **Onboarding wizard**: choose **Continuous Integration** as the first module. Harness creates a Project + Org with the names you pick. Record both IDs — they replace `<ORG_ID>` and `<PROJECT_ID>` in the shipped pipeline file.
713
+ 3. **GitHub connector**: `Project Setup → Connectors → Create Connector → GitHub` → "Github App" or "OAuth" → install the **Harness GitHub App** on `webship/webship-js`. Save the connector ID and replace `<GITHUB_CONNECTOR_ID>` in the pipeline.
714
+ 4. **Optional Docker / S3 connectors** (only if you want artefact upload):
715
+ - `Connectors → Docker Registry → Docker Hub anonymous` (used by `plugins/s3`).
716
+ - `Secrets → Add Encrypted Text → aws_access_key`, `aws_secret_key`.
717
+ 5. **Import the pipeline**:
718
+ - `Pipelines → New Pipeline → Import from Git`.
719
+ - Repo `webship/webship-js`, branch `2.0.x`, file path `.harness/webship-js-pipeline.yml`.
720
+ - Harness validates the YAML and renders the visual graph.
721
+ 6. **Trigger**:
722
+ - `Triggers → New Trigger → Webhook → GitHub → On Push`.
723
+ - Branch regex `^2\.0\.x$`. Save.
724
+ - First push runs the pipeline.
725
+
726
+ ### Badge
727
+
728
+ Public dashboards are an Enterprise feature. For the free plan, expose status via the GitHub commit status that the Harness GitHub App posts automatically, or write a tiny shields.io endpoint backed by the Harness REST API (`GET /pipeline/api/pipelines/execution`).
729
+
730
+ ### Reports
731
+
732
+ The shipped pipeline includes an optional `Upload report artefacts` step that uses the `plugins/s3` connector. Replace the secret IDs and bucket name; or rip the step out entirely and pull reports from Harness's built-in **CI Insights** tab (test logs are retained per-build).
733
+
734
+ ### Notes
735
+
736
+ - `runtime.type: Cloud` uses Harness-hosted infra (no agents to manage). For self-hosted runners, switch to `runtime.type: KubernetesCluster` and point at a connector.
737
+ - Placeholders to fill before first run: `<ORG_ID>`, `<PROJECT_ID>`, `<GITHUB_CONNECTOR_ID>`, `<DOCKER_CONNECTOR_ID>`. Harness's UI does the substitution if you start from "Import from Git".
738
+ - `step.type: Background` is the Harness equivalent of `nohup ... &` — keeps `npm start` alive across following steps.
739
+ - The `reports.type: JUnit` block expects a junit XML; cucumber-js can emit one with `--format junit:tests/reports/junit.xml`. Add to a CI-only `WEBSHIP_REPORT_ARGS` env if you want it.
740
+
741
+ ---
742
+
743
+ ## Bamboo Data Center
744
+
745
+ **File**: `bamboo-specs/bamboo.yml`.
746
+
747
+ Atlassian's on-prem CI/CD. **Atlassian retired Bamboo Cloud on 2024-02-15** — only the self-hosted **Bamboo Data Center 9.x** remains. The shipped YAML targets the official YAML Specs format introduced in Bamboo 7+.
748
+
749
+ ### Setup steps — open account + connect repo
750
+
751
+ There is no Atlassian-hosted Bamboo any more. You bring your own server.
752
+
753
+ 1. **Buy a Bamboo Data Center licence** at <https://www.atlassian.com/software/bamboo/pricing>, or use the 30-day evaluation. Free starter tier was discontinued.
754
+ 2. **Install Bamboo Data Center**:
755
+ - Recommended path: official Docker image `atlassian/bamboo` on a host with at least 4 GB RAM and a persistent volume.
756
+ - Database: PostgreSQL 13+ or MySQL 8+ is supported; SQLite for tiny installs.
757
+ - Follow the Atlassian "Installing Bamboo" guide for your platform.
758
+ 3. **Sign in as admin** at `https://bamboo.example.com` → run the setup wizard → activate the licence.
759
+ 4. **Link the GitHub repository**: `Bamboo administration → Linked repositories → Add → Git`. Use HTTPS + a Personal Access Token, or SSH with a deploy key. Name the linked repo `webship-js`.
760
+ 5. **Enable Bamboo Specs scanning** on that repo: `Bamboo administration → Specs → Repositories → Add`. Bamboo reads `bamboo-specs/bamboo.yml` on every push, recreating plan + permissions from the file.
761
+ 6. **Build agent**: at least one Docker-capable agent must be online. The plan runs inside `mcr.microsoft.com/playwright:v1.58.2-jammy`, so the host needs Docker installed and the Bamboo agent needs the Docker plugin enabled.
762
+
763
+ ### Badge
764
+
765
+ Bamboo emits chat-style status webhooks (Slack, MS Teams) but no native badge image. Two options:
766
+
767
+ 1. **GitHub commit status** — install the *Bamboo for GitHub* add-on: `<https://marketplace.atlassian.com/apps/1214095/bamboo-for-github>`. Posts pass/fail on every build.
768
+ 2. **shields.io endpoint** — wrap Bamboo's `/rest/api/latest/result/<key>-latest` REST call in a tiny proxy and embed `https://img.shields.io/endpoint?url=...`.
769
+
770
+ ### Reports
771
+
772
+ `Cucumber.artifacts` declares four shared artefacts:
773
+
774
+ - `cucumber-report-html` → `tests/reports/cucumber_report.html`
775
+ - `cucumber-report-pdf` → `tests/reports/cucumber_report.pdf`
776
+ - `cucumber-report-json` → `tests/reports/cucumber_report.json`
777
+ - `screenshots` → `screenshots/**` (failure captures)
778
+
779
+ Browse per build under `Plan Result → Artifacts`. The `shared: true` flag makes them available to downstream plans and to the Bamboo REST API.
780
+
781
+ ### Notes
782
+
783
+ - The YAML uses Bamboo's *two-document* format: the first document is the plan, the second is the plan permissions. Both are required by the Specs scanner.
784
+ - `docker.image` + `docker-run-arguments` runs every script task inside the Playwright image — no need to install Node or chromium on the agent itself.
785
+ - `triggers.polling` is used instead of webhook triggers; webhooks are also supported but need network access from GitHub to the Bamboo server.
786
+ - `branches.create: manually` and `delete: never` keep branch hygiene strict — flip if you want feature-branch builds.
787
+ - For per-browser matrix, duplicate the `Cucumber` job under `stages.Test.jobs` and override `BROWSER` per copy.
788
+
789
+ ---
790
+
791
+ ## Codefresh
792
+
793
+ **File**: `codefresh.yml` at repo root.
794
+
795
+ Kubernetes-native CI/CD. The Classic pipeline format reads `codefresh.yml` from the repo. Free tier: 100 build-minutes / month on shared infrastructure — fits ~11 runs of the 9-minute suite. Public OSS repos can apply for the Community plan for more capacity.
796
+
797
+ ### Setup steps — open account + connect repo
798
+
799
+ 1. **Sign up**: <https://g.codefresh.io/signup> → "Sign up with GitHub" → authorise the Codefresh GitHub App on `webship/webship-js`.
800
+ 2. **Pick a runtime**: dashboard prompts you to "Add Runtime" → pick **Codefresh Hosted** for the managed free tier. (Self-hosted runtimes via `cf-runtime install` are also available but out of scope here.)
801
+ 3. **Create a pipeline**:
802
+ - `Pipelines → New Pipeline → From Git`.
803
+ - Repository `webship/webship-js`, branch `2.0.x`.
804
+ - Choose **"Inline YAML from repository"** → path `codefresh.yml`.
805
+ 4. **Add a trigger**:
806
+ - `Triggers → Git → push events on branch ^2\.0\.x$`.
807
+ - First push runs the pipeline.
808
+
809
+ ### Badge
810
+
811
+ ```markdown
812
+ [![Codefresh build status](https://g.codefresh.io/api/badges/pipeline/<account>/webship-js?type=cf-1)](https://g.codefresh.io/pipelines/edit/new/builds?id=<pipeline-id>)
813
+ ```
814
+
815
+ Replace `<account>` with the Codefresh account slug picked at signup and `<pipeline-id>` with the value from the URL of the pipeline editor.
816
+
817
+ ### Reports
818
+
819
+ The `upload_reports` step copies `cucumber_report.{html,pdf,json}` + `screenshots/` to `/codefresh/volume/cucumber-report/` — a Codefresh-managed shared volume that persists across pipeline runs. From there you can:
820
+
821
+ 1. Mount the same volume in a follow-up step that uploads to S3/GCS.
822
+ 2. Browse via the **Codefresh storage browser** (Pro+ plans only).
823
+ 3. Pipe to the built-in **Test Reports** feature by emitting JUnit XML — add a `--format junit:tests/reports/junit.xml` argument to the cucumber-js call.
824
+
825
+ ### Notes
826
+
827
+ - `type: git-clone` + `working_directory: ${{main_clone}}` is the canonical Codefresh pattern; the variable expands to the path of the cloned repo on the runtime.
828
+ - Both `freestyle` steps reuse the Playwright base image to skip apt installs entirely.
829
+ - `successOnly` / `failureToo` inside `when.condition.any` is Codefresh's way of saying "always" — keeps the upload step running even when tests fail so artefacts are still collected.
830
+ - For per-browser matrix, replace `test_suite` with a parallel `steps` block (Codefresh 1.0 spec supports `mode: parallel`) and parameterise `BROWSER`.
831
+ - Codefresh's GitOps platform (Argo Workflows / Argo CD) reads a different format (`csdp` workflow definitions). This file is for the Classic pipeline runtime — the more common path.
832
+
833
+ ---
834
+
835
+ ## Octopus Deploy
836
+
837
+ **Files**: none — Octopus is **Continuous Deployment only**.
838
+
839
+ Octopus Deploy is a release-orchestration tool. It does not run unit / integration test suites — its job starts after a build artefact exists. Webship-js therefore does not ship an Octopus config file, but you can wire any of the CI lanes above to call Octopus once tests pass.
840
+
841
+ ### When you might use Octopus alongside webship-js
842
+
843
+ - The webship-js test suite is part of a larger product release flow.
844
+ - You already use Octopus for production deployments and want a single pane of glass for release tracking.
845
+ - You need release approvals, audit logs, or environment-promotion gates that the CI tools above do not provide.
846
+
847
+ ### Setup steps — open account
848
+
849
+ 1. **Octopus Cloud** (SaaS): <https://octopus.com/start> → sign in with email or Google → free for 10 deployment targets. Trial covers everything; the always-free tier covers small teams.
850
+ 2. **Octopus Server** (self-hosted): download the Windows / Linux installer from <https://octopus.com/downloads>. Free up to 10 deployment targets.
851
+
852
+ ### Wire any CI lane into Octopus
853
+
854
+ After a webship-js CI build passes:
855
+
856
+ 1. Package the report bundle (or the entire repo) as a NuGet / zip artefact.
857
+ 2. Push it to Octopus's built-in repository or to an S3 / Azure Blob / Artifactory feed Octopus polls.
858
+ 3. Trigger a release via the Octopus REST API or CLI:
859
+ ```bash
860
+ octo create-release \
861
+ --project webship-js \
862
+ --packageVersion $CI_BUILD_NUMBER \
863
+ --server https://octopus.example.com \
864
+ --apiKey API-XXXXXXXXXXXX \
865
+ --deployTo Production
866
+ ```
867
+
868
+ Plug that snippet into any of the YAML files we ship — Octopus does not care which CI triggered it.
869
+
870
+ ### Why webship-js does not ship `.octopus/` configs
871
+
872
+ - The test-runner phase is done by the time Octopus picks up. Octopus reads its own `OctopusProjectFile` / `process.ocl` configs from a different repo (the "Octopus Project") in most installations — it is not driven by a YAML in the application repo.
873
+ - Even when Octopus Config-as-Code is enabled, the OCL files live in a project-scoped repo, not the application repo.
874
+
875
+ ---
876
+
877
+ ## Codeship
878
+
879
+ **Service retired by CloudBees on 2023-09-30.** Do not add a Codeship config. Existing `codeship-steps.yml` / `codeship-services.yml` files on the internet are dead. If a tutorial references Codeship, treat it as Tier-1 advice for **Travis** or **CircleCI** instead — both ship the same `npm test` pattern.