---
name: saas-e2e-automation
description: SaaS E2E automation workflow for this repository. Use when Codex needs to run, plan, debug, extend, or summarize pytest + Playwright + Allure tests; inspect runtime/e2e_accounts.json; use the local saas-e2e MCP server; work with e2e/tests, e2e/pages, scripts/probe_*.py, bugs, or reports.
---

# SaaS E2E Automation

Use the repository's automation core instead of rediscovering test state manually.

## Quick Workflow

1. Inspect the target run:
   ```powershell
   .\.venv\Scripts\python.exe .\scripts\agent_e2e.py plan standalone
   ```
2. Pick the smallest profile that exercises the requested behavior.
3. Run through the agent entry:
   ```powershell
   .\.venv\Scripts\python.exe .\scripts\agent_e2e.py run main
   ```
4. On failure, inspect:
   ```powershell
   .\.venv\Scripts\python.exe .\scripts\agent_e2e.py bugs
   .\.venv\Scripts\python.exe .\scripts\agent_e2e.py summary
   ```
5. Patch Page Objects in `e2e/pages/` before patching tests when the problem is selector or navigation reuse.

## Multi-Account Browser Rule

When creating or updating E2E cases that involve more than one logged-in tenant account, use the shared Chrome dual-account fixture instead of switching accounts in one page.

- Add `dual_account_pages` to the pytest function arguments.
- Call `wanzhanggui_page, wanyouji_page = dual_account_pages.pair(wanzhanggui_phone, wanyouji_phone)` before constructing Page Objects.
- Construct each Page Object with its own page, for example `WanzhangguiOrderPage(wanzhanggui_page, ...)` and `WanyoujiFulfillmentPage(wanyouji_page, ...)`.
- Do not manually launch browsers or create contexts in tests. The fixture routes accounts to one Chrome browser with isolated BrowserContexts/windows and asserts that the contexts are distinct.
- Keep `E2E_DUAL_BROWSER` enabled. It is enabled by default; only single-account tests may opt out.

## Profiles

- `seed`: data/account creation tests.
- `standalone`: tests that can run as entry points.
- `chain`: ledger-dependent progression tests.
- `main`: full closed-loop test.
- `saas-001`, `saas-003`, `saas-004`, `auth`, `push`, `order`: focused business areas.

## MCP

Project MCP config lives at `.codex/mcp/saas-e2e.json`. The server is `scripts/mcp_saas_e2e.py` and exposes:

- `list_tests`
- `inspect_accounts`
- `latest_bugs`
- `allure_summary`
- `build_plan`
- `run_pytest`

Prefer MCP tools when available. Use `scripts/agent_e2e.py` as the shell fallback.

## References

Read `references/test-matrix.md` when choosing test order, prerequisites, or ledger expectations.
