docs(e2e): add dev-docs/e2e.md engineering reference #355

Merged

nrupard merged 1 commit from docs/PMS-492-e2e-kb into main

2026-06-24 20:21:11 +02:00

nrupard commented

2026-06-24 20:17:41 +02:00

Owner

What

Adds dev-docs/e2e.md, a standalone engineering reference for the mokosh-server Playwright E2E suite, satisfying the "Update documentation" task of PMS-492. The matching YouTrack knowledge-base article was created as PMS-A-1 ("mokosh-server E2E suite: how it works, running it, and troubleshooting"); this doc is its repo-side twin and the two are kept in sync.

Why

E2E had detailed but scattered docs (e2e/README.md, inline comments in global.setup.ts, the workflow header, and two project memories). New contributors hitting a red E2E run had no single page explaining how the suite is wired or which failure is which. This consolidates the mental model and the real failure modes into one reference, mirroring the sibling layout in the bunyip repo (dev-docs/e2e.md + a KB article).

The doc covers: what the suite is (runs against a deployed staging target, not a CI artifact), the preflight/setup/auth-ui/api project model and why it is serialised on the 5/min/email login cap, the two auth paths (captured bearer vs replayed OP cookies) and why a direct API login is impossible, the dual token-capture strategy and the mokosh-apps #84 OIDC-loop it defends against, module gating, configuration + CI naming, one-time staging provisioning (admin role, MOKOSH_DEMO_SEED=false), running locally, CI triggers/gates/concurrency, the quarantined auth/oidc specs and their blockers (PMS-148, PMS-435/BUNYIP-146), the test-data/teardown policy, and a troubleshooting section enumerating the failure modes that actually bite (login rate limit, setup token timeout, the deploy-gate deadlock, gated-module 404s, admin-403s, OIDC cookie-domain bounce, demo-seed pollution, the OpenSUSE runner npm/corepack quirks, and the wait-for-deploy SHA-walk self-heal).

Docs-only change; no code touched.

## What Adds `dev-docs/e2e.md`, a standalone engineering reference for the mokosh-server Playwright E2E suite, satisfying the "Update documentation" task of PMS-492. The matching YouTrack knowledge-base article was created as `PMS-A-1` ("mokosh-server E2E suite: how it works, running it, and troubleshooting"); this doc is its repo-side twin and the two are kept in sync. ## Why E2E had detailed but scattered docs (`e2e/README.md`, inline comments in `global.setup.ts`, the workflow header, and two project memories). New contributors hitting a red E2E run had no single page explaining how the suite is wired or which failure is which. This consolidates the mental model and the real failure modes into one reference, mirroring the sibling layout in the bunyip repo (`dev-docs/e2e.md` + a KB article). ## Contents The doc covers: what the suite is (runs against a deployed staging target, not a CI artifact), the `preflight`/`setup`/`auth-ui`/`api` project model and why it is serialised on the 5/min/email login cap, the two auth paths (captured bearer vs replayed OP cookies) and why a direct API login is impossible, the dual token-capture strategy and the mokosh-apps #84 OIDC-loop it defends against, module gating, configuration + CI naming, one-time staging provisioning (admin role, `MOKOSH_DEMO_SEED=false`), running locally, CI triggers/gates/concurrency, the quarantined `auth`/`oidc` specs and their blockers (PMS-148, PMS-435/BUNYIP-146), the test-data/teardown policy, and a troubleshooting section enumerating the failure modes that actually bite (login rate limit, setup token timeout, the deploy-gate deadlock, gated-module 404s, admin-403s, OIDC cookie-domain bounce, demo-seed pollution, the OpenSUSE runner npm/corepack quirks, and the wait-for-deploy SHA-walk self-heal). Docs-only change; no code touched.

nrupard added 1 commit

2026-06-24 20:17:41 +02:00

docs(e2e): add dev-docs/e2e.md engineering reference

E2E / Playwright against staging (pull_request) Successful in 1m4s

Details

Check / fmt + clippy + build + tests (pull_request) Successful in 3m28s

Details

Create release / Create release from merged PR (pull_request) Successful in 3s

Details

Integration / integration tests (pull_request) Successful in 7m35s

Details

df31fd6d9b

Adds a standalone E2E engineering doc covering how the suite works (deployed-target model, the preflight/setup/auth-ui/api project layout, the two auth paths, token capture, module gating), running it locally, CI triggers and gates, quarantined specs, the test-data policy, and a troubleshooting section enumerating the real failure modes (login rate limit, setup token-capture timeout, the deploy-gate deadlock, gated-module 404s, admin-403s, OIDC cookie-domain bounce, demo-seed pollution, the OpenSUSE runner npm/corepack quirks, and the wait-for-deploy SHA-walk self-heal). This is the repo-side twin of the PMS-A-1 YouTrack knowledge-base article and links back to e2e/README.md, playwright.config.ts, global.setup.ts, and the e2e workflow.

#PMS-492

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

nrupard scheduled this pull request to auto merge when all checks succeed

2026-06-24 20:19:16 +02:00