# Studio E2E Testing Architecture
<!-- wiki:featured -->
**Version:** v1.1.0  
**Last updated:** 2026-10-06  
**Status:** Production

## Overview
A 7-layer pipeline that runs only the tests that matter, catches visual regressions, and blocks bad merges automatically.

## Architecture

| Layer | Name | What it does | Key files |
|-------|------|-------------|-----------|
| L0 | Git worktrees | `develop` + `main` run side-by-side. Compare live at `/shell-dev/` vs `/shell/` | `~/studio-dev`, `~/studio-prod` |
| L1 | Governance | AGENTS.md is single source of truth. RuleSync auto-generates all tool configs. Blocks merge if out of sync. | `AGENTS.md`, `scripts/ruleSync.js` |
| L2 | Change-aware selection | Parses git diff, traces TS imports, maps FastAPI routes via route-map. Only impacted specs run. | `scripts/selectTests.js`, `scripts/syncRouteMap.js`, `.github/e2e-route-map.json` |
| L3 | Test authoring | Playwright Codegen + Cursor Pro. No custom AI generator. | `.cursor/mcp.json` |
| L4 | Knowledge graph | Graphify (18k nodes). Max 2 hops, 20 node cap. Playwright MCP for live browser control. | `graphify-out/graph.json`, `scripts/graphify-mcp-proxy.js` |
| L5 | Test runner | Playwright v1.62.1 pinned in Docker. Phase 1: hard block on failure. Phase 2: healer suggests fix, human approves. | `docker-compose.yml`, `tests/e2e/` |
| L6 | Visual regression | Argos CI (free tier). Git-based baselines. Timestamps + avatars masked globally. | `playwright.config.ts`, argos-ci.com |

## Operational notes
- `api/` changes → full suite fallback while route-map bridge matures
- `playwright.config`, `scripts/`, `tests/e2e/` changes → always trigger full suite
- `npm run check:route-map` blocks merge if route map out of sync
- 3 spec types per app: `routing` / `app` / `shell`
- `context.route()` mocks all backend — zero real LLM calls in tests
- `PLAYWRIGHT_BASE_URL` env var — never hardcode ports
- Docker: `docker compose --profile e2e run --rm playwright`
- Argos token: stored in `.env` as `ARGOS_TOKEN`

## Current state
- CI gate: **Gate 11** via `scripts/run-studio-e2e-guards.sh` (same script post-promote)
- Apps covered: nous, blueprint, athena, studio-shell, prophunt
- **Process:** Block 1 (PR CI) + Block 3 (`promote-batch` / `promote-product`) both fire Gate 11 — no manual e2e step
- **Gate 12 (inventory):** `scripts/validate-inventory-gate.sh` / CI job `inventory-gate` — merge blocker (not e2e); see `docs/tech-stack/README.md`

## Changelog
| Version | Date | Changes |
|---------|------|---------|
| v1.1.0 | 2026-10-06 | blueprint.app + blueprint.shell added to CI gate (13 green), syncRouteMap CI check added |
| v1.0.0 | 2026-10-06 | Initial architecture — L0-L6 fully implemented |