playwright.spec.js agent procedure

This page covers the agent procedure when generating or updating a role-local playwright.spec.js. It does NOT restate what the file must contain. Those rules are authoritative in Contributing playwright.spec.js and MUST be consulted before every task.

For framework and runner mechanics, see Playwright Tests. For the matching environment contract, see Role playwright.env.j2.

Procedure

  1. Read the contributor SPOT and treat every MUST there as a non-negotiable acceptance criterion for the generated spec.

  2. Inspect the role’s meta/services.yml (and the matching meta/server.yml / meta/rbac.yml) and defaults/main.yml to determine the supported entry point (dashboard vs. direct app), enabled integrations (OIDC, LDAP, messaging, etc.), and active personas.

  3. Read or author the role’s templates/playwright.env.j2 first and keep every variable name aligned with the generated spec.

  4. Draft scenarios from the live running stack, not from assumptions. Use Playwright codegen or playwright-recorder (see the framework SPOT) as a starting point when the DOM structure is unknown.

  5. Deploy the role and run the spec inside the shared test-e2e-playwright runner until every MUST in the contributor SPOT passes and the browser console is free of unhandled errors.

  6. When the change was triggered by an update to role-local style.css or javascript.js, verify the new visible behavior is covered before reporting the task complete.

Live Review

Before reporting the task complete, you MUST verify the spec against a running stack, not against file contents alone. Static file review misses navigation and auth bugs that only surface in the browser.

  • You MUST drive the scenarios through a real browser session against the deployed role. A green local file-lint does not satisfy this step.

  • You MUST inspect the start page AND the login page of the role as part of the end-to-end run. These two pages surface most navigation, authentication, and first-load regressions that later assertions would only catch indirectly.

  • You MUST open the browser console during runs that depend on injected JavaScript and confirm it is free of unhandled errors before reporting success.

Reporting

  • Report which MUSTs in the contributor SPOT were verified end to end and which were covered only by a static check, if any.

  • Reference the deploy log path when the run surfaced any anomaly the reviewer should see.