The e2e kit

Every new or re-engineered service on the platform ships with an end-to-end test and documentation generated by that test. This course teaches you to run the kit, write a service journey, capture its documentation and publish it. This first lesson explains what the kit is and what it starts on your machine.

Why end-to-end tests

Unit and integration tests prove pieces of the platform. Only an end-to-end test proves that a citizen can actually find a service, apply, pay and receive a valid document, and that each officer can do their step in the back office. For every service, the end-to-end test must cover:

• finding the service and signing in;
• applying: the form and the documents;
• paying;
• every officer step of the process, by the role the step names;
• the decision;
• the issued output: download it, verify the seal and QR code, and check the key fields.

Where the kit lives

The kit is a Playwright project in a folder named e2e. It is too big for a git repository, so the single current copy lives on the central documentation share. You copy it into your workspace, next to the three application repositories:

<workspace>/
  zcm-backend/        the API (git clone)
  back-office-ui/     the back office (git clone)
  public-portal-ui/   the citizen portal (git clone)
  e2e/                copied from the share

Clone the repositories on the branch named in e2e/START-HERE.md, and run the kit from your own disk, not from a mapped network drive. Take a fresh copy of the kit before each new piece of work, so you never overwrite a colleague's newer files.

What you need once

• Node 20 or later, Git and Google Chrome (the kit uses the system Chrome).
• PostgreSQL with PostGIS on localhost:5433, local only.
• LibreOffice, so issued documents are rendered with their real layout. Without it, a text-only stand-in is used and

  documentation made from it is not published.

Then, in e2e/:

npm install
npm run setup

npm run setup creates a worktree of each application repository (<repo>/.worktrees/e2e) on a snapshot branch. The kit runs the applications from these worktrees and never edits application code. npm run setup -- --refresh re-creates them from the base branch to pick up merged changes.

What npm run e2e starts

npm run e2e starts the whole platform, runs the journeys and stops everything again. The stack is:

1. A fresh database. zcm_e2e is dropped and re-created on every run, PostGIS enabled, the backend's own

   migrations applied, and the kit's seed run through the backend's models: ministries, an office, staff accounts, two citizens, an example service with a form, a document, a fee and a validity, and a shop service with products.

2. The two web applications. Production builds of the portal and the back office, cached and rebuilt only when

   the worktree changes.

3. The provider test doubles (below).
4. The API, with jobs off, a random session secret, and a network guard that refuses every outgoing call to a

   host that is not local.

Nothing leaves your machine. E-mail is unconfigured and AI is off.

Provider test doubles

The platform depends on external providers. In tests, each is replaced by a local double from zcm-backend/test/fixtures/providers/, so the e2e kit, the backend's contract suites and its integration tests share one faithful set:

Double	Replaces	What journeys use it for
ZamPay (behind ZamConnect)	Payment	Pay an invoice, fail or expire one, send receipt callbacks to the API
ZamPass	Citizen sign-in (OpenID Connect)	Choose a persona, sign in with PKCE, log out
SMS capture	SMS provider	Read every text the platform sent
Government gateway	Legacy verification source	Verification look-ups
Register source	An external register's sync API	Register synchronisation
Development PKI	CA, time-stamp authority, OCSP	Certificates and time-stamps for seals
Signing service	Sealing	Seal issued permits

Each double has a /__control API that the kit's helpers use, for example to mark an invoice as paid with a given payment method. Journeys must never call real ZamPay, ZamPass, SMS or signing services.

Sign-in in the journeys

Citizens sign in with ZamPass only. One journey signs in through the ZamPass double for real. The others, for speed, create the session the same way the API does and then use the real application from there. Staff sign in through the back office's real e-mail and password form with the seeded test accounts, which exist only in the kit's test seed.

Reading the results

Where	What
.stack/last-summary.txt	One line per test; each failure's first line with its screenshot and trace
npx playwright show-report	The HTML report
test-results/	Screenshots and traces of failures
.stack/logs/	The API log and the doubles' logs

A failing test stays failing when the application is wrong; do not weaken a test to make it pass. A test is parked as a known gap only while its fix sits on an unmerged branch, and it re-enables itself when the fix is merged.

Check your understanding

• Which six parts of a service's life must its end-to-end test cover?
• Where does the single current copy of the kit live, and where do you run it from?
• What does npm run setup create, and why does the kit never edit application code?
• What happens to the zcm_e2e database at the start of each run?
• Why can no journey reach a real provider?
• Which double would you use to mark an invoice as paid?