computer-playbook/roles/test-e2e-playwright/README.md

Test: E2E Playwright Runner

Description

This Ansible role provides a generic, reusable Playwright end-to-end (E2E) test runner for the Infinito.Nexus ecosystem.

It automatically discovers roles that ship a Playwright test project under:

• roles/<application_id>/templates/playwright.env.j2
• roles/<application_id>/files/playwright/playwright.spec.js

A role is considered Playwright-enabled if it provides:

• roles/<application_id>/templates/playwright.env.j2

The role then stages the Playwright project to a local staging directory, renders a .env file from templates/playwright.env.j2, optionally waits until the application is reachable, and executes Playwright inside a Docker image derived from the central Playwright package version.

Overview

This role:

• Discovers Playwright-enabled roles by scanning roles/*/templates/playwright.env.j2
• Supports allow-/deny-lists via test_e2e_playwright_only_roles and test_e2e_playwright_skip_roles
• Stages each Playwright project into TEST_E2E_PLAYWRIGHT_STAGE_BASE_DIR/<application_id>
• Renders the central package.json template into each staged project and injects the central playwright.config.js
• Copies every role-specific files/playwright/*.js (the playwright.spec.js aggregator plus its test-*.js scenario modules) into the staged tests/ directory, and stages files/playwright/fixtures/ (binary assets such as sample images/videos) alongside them
• Renders .env from templates/playwright.env.j2 using Ansible variables (application_id, domains, users, applications)
• Optionally waits until the application responds with HTTP 200 or 302
• Injects CA trust automatically for TLS_MODE=self_signed (via CA_TRUST.*), so Playwright accepts self-signed cert chains
• Runs Playwright in Docker with stable browser settings (--ipc=host, --shm-size=1g)
• Stores per-role reports/artifacts under TEST_E2E_PLAYWRIGHT_REPORTS_BASE_DIR/<application_id>

Features

• Automated provisioning: Configured by Ansible without manual steps.

Purpose

The purpose of this role is to provide a central E2E test primitive that can be executed at the end of a deployment (for example, as a post task), without hardcoding tests in the runner itself.

Each application role stays responsible for its own Playwright tests and configuration. This role only provides the execution framework.

Role contract (what application roles must provide)

A Playwright-enabled role must provide:

roles/<application_id>/
    templates/playwright.env.j2
    files/playwright/playwright.spec.js

For the file-level contract, use Contributing playwright.env.j2 and Contributing playwright.spec.js.

package.json and playwright.config.js are provided centrally by this role:

• roles/test-e2e-playwright/templates/package.json.j2 (rendered per-deploy; pins @playwright/test from meta/services.yml.playwright.version)
• roles/test-e2e-playwright/files/playwright.config.js (copied as-is)

Included files

This role ships central Playwright defaults:

• templates/package.json.j2: @playwright/test version derived from meta/services.yml.playwright.version
• files/playwright.config.js: shared Playwright configuration

Both are used as central defaults for every app role.

Variables

Staging & reports

• TEST_E2E_PLAYWRIGHT_STAGE_BASE_DIR (default: /tmp/test-e2e-playwright)
• TEST_E2E_PLAYWRIGHT_REPORTS_BASE_DIR (default: /var/lib/infinito/logs/test-e2e-playwright)

Playwright runtime

• TEST_E2E_PLAYWRIGHT_IMAGE (resolved in vars/main.yml from meta/services.yml.playwright.image + .version via lookup('config', 'test-e2e-playwright', 'services.playwright.image|version'))
• TEST_E2E_PLAYWRIGHT_IMAGE_DISTRO (default: noble)
• TEST_E2E_PLAYWRIGHT_COMMAND (default: npm install --no-fund --no-audit && npx playwright test)

Discovery filters

• test_e2e_playwright_only_roles (default: lookup('deployment').running, every role the round deploys, dependencies included)
• test_e2e_playwright_skip_roles (default: [])

Design notes

• The runner is intentionally test-agnostic at runtime: it executes only tests provided by application roles.
• playwright.version in meta/services.yml is the single source of truth for the default Playwright version; the central templates/package.json.j2 pins it via the image_version filter.
• templates/playwright.env.j2 acts as the stable marker for discovery and as the source of environment configuration.
• Playwright is executed in Docker for reproducibility and consistent browser dependencies.
• In TLS_MODE=self_signed, the role requires CA_TRUST.cert_host, CA_TRUST.wrapper_host, and CA_TRUST.trust_name and fails early if cert/wrapper files are missing.

How to use

1. Add the two app-specific files:
   • roles/<application_id>/templates/playwright.env.j2
   • roles/<application_id>/files/playwright/playwright.spec.js Follow Contributing playwright.env.j2 and Contributing playwright.spec.js while creating them.
2. Deploy a round that includes your app (e.g. make compose-deploy apps=<application_id>); its specs run with those of every other role the round deploys.
3. Keep package.json and playwright.config.js centralized in roles/test-e2e-playwright/ (templates/package.json.j2 and files/playwright.config.js).

Example override for running only one spec:

-e TEST_E2E_PLAYWRIGHT_COMMAND='npm install --no-fund --no-audit && npx playwright test tests/login.spec.js'

Recording

For interactive Playwright recording, use the external repository:

playwright-recorder

This role no longer ships its own local recording wrapper.