computer-playbook/docs/contributing/code/role/playwright.spec.js.md

playwright.spec.js

This page is the SPOT for role-local Playwright test specs. Use this page for runner integration, minimum coverage, and repository-wide scenario requirements. For implementation scope, selector strategy, and live review, see Agent playwright.spec.js. For the matching rendered environment contract, see Contributing playwright.env.j2.

Runner Contract

• test-e2e-playwright copies files/playwright.spec.js into the staged test project as tests/playwright.spec.js.
• The spec consumes the .env rendered from templates/playwright.env.j2.
• package.json and playwright.config.js MUST stay centralized in roles/test-e2e-playwright/files/.

Requirements

• Every Playwright-enabled role MUST verify login and logout.
• Every role with compose.services.dashboard.enabled MUST start the test flow from the dashboard.
• When the role provides both biber and administrator scenarios, login and logout for both MUST be covered.
• When role-local javascript.js or style.css is implemented or refactored, the affected user-visible behavior MUST be added to or updated in the Playwright suite.
• Assertions MUST verify real UI states and user-visible outcomes, not only URL transitions or static strings.
• The suite MUST finish in a clearly logged-out state.

Scenario Rules

• You MUST name tests after the real flow they verify, for example dashboard to app login and logout.
• You MUST keep persona-specific scenarios explicit when the role distinguishes between different user paths.
• You SHOULD add extra coverage when relevant, for example OIDC, LDAP, or dashboard-specific navigation.