diff --git a/README.md b/README.md index b88b5aa..d133ac7 100644 --- a/README.md +++ b/README.md @@ -4,29 +4,7 @@ A portable GitHub Action and lightweight framework for running Playwright agains It keeps the application repository in control of its tests and services while providing a consistent CI engine: deterministic runner images, smart reuse, SUT lifecycle management, test filtering, Playwright reports, traces, portable artifacts, and a fail-closed result. -```text -pull request / main / manual - | - validate e2e/ci.yml - | - hash E2E runner inputs - | - +------+------+ - | | - validated cache cache miss - | build runner - +------+------+ - | - start Dockerized SUT - | - Playwright projects + tags - | - results + traces - | - HTML report + report image - | - E2E Gate -``` +![E2E delivery flow from pull request, main, or manual trigger through runner reuse, Dockerized SUT testing, reports, and the required gate](docs/diagrams/e2e-flow.svg) ## Start from the template @@ -86,19 +64,7 @@ The action fails at the end when tests fail or infrastructure is incomplete. A c The caller keeps these files: -```text -. -+-- compose.e2e.yml -+-- e2e/ -| +-- ci.yml -| +-- Dockerfile -| +-- runner-entrypoint.mjs -| +-- package.json -| +-- pnpm-lock.yaml -| +-- playwright.config.ts -| +-- tests/ -+-- sut/ # example only; use your real services -``` +![Repository contract showing the root Compose file, E2E configuration and tests, and replaceable system services](docs/diagrams/repository-contract.svg) `e2e/ci.yml` is the CI contract: diff --git a/docs/diagrams/e2e-flow.svg b/docs/diagrams/e2e-flow.svg new file mode 100644 index 0000000..6426346 --- /dev/null +++ b/docs/diagrams/e2e-flow.svg @@ -0,0 +1,128 @@ + + Playwright E2E delivery flow + A change enters CI, configuration and runner inputs are validated, a cached runner is reused or rebuilt, the Dockerized system is tested, and results and reports feed the E2E gate. + + + + + + + + + + + + + + + + + E2E DELIVERY FLOW + One portable action from change detection to a required test result + + + + Change enters CI + + PR + + main + + manual + + + + + + + Validate config + profile · paths · filters + + + + + + + Hash runner inputs + tests · config · dependencies + + + + + + + Resolve the Playwright runner + Content hash chooses validated reuse or a clean build + + + + + + + + Cache hit + Validate archive + image ID + + + + Cache miss + Build image + + + + + + + + Portable runner + exact image for this run + + + + + + + Start the SUT + Compose build · health wait + + + + + + Run Playwright + projects × tags × workers + + + + + + Collect results + traces · logs · attachments + + + + + + Publish reports + HTML + portable images + + + + + + E2E Gate + pass or fail closed + + + Every path produces the same result contract and retained debugging artifacts. + diff --git a/docs/diagrams/repository-contract.svg b/docs/diagrams/repository-contract.svg new file mode 100644 index 0000000..bb4829f --- /dev/null +++ b/docs/diagrams/repository-contract.svg @@ -0,0 +1,87 @@ + + Repository contract for the Playwright E2E action + The consumer repository contains a root Compose file, an e2e directory with the execution contract and tests, and the Dockerized services under test. + + + + + + + + + + + + + + + + + REPOSITORY CONTRACT + The action is portable; the consuming repository owns these paths and their contents + + + + Consumer repository + checked out before the action runs + + + + + + + + + + ROOT + Compose topology + + compose.e2e.yml + Build, health, and service graph + + + + + + E2E DIR + Runner, policy, and tests + + + ci.yml + + Dockerfile + + runner-entrypoint + + + package.json + + pnpm-lock.yaml + + playwright.config + + + tests/ + suites · fixtures · helpers + + + + + + SUT + System services + + sut/ + Example only; use real services + + + The directory name and manifest path stay stable; implementation details remain application-owned. +