# Command Dashboard Local E2E / Visual Smoke Harness

Use after a mock-only command-dashboard frontend is already rendering through a Store/API client and needs local end-to-end validation without touching real domain systems.

## Trigger

- User asks for local E2E/visual QA of a sensitive multi-domain dashboard.
- Need to verify real frontend ↔ mock gateway flow, responsive iPad/desktop behavior, offline/fallback states, and safety rules.
- Existing smoke test is unreliable because fixed ports may be occupied.

## Pattern

1. Keep `make verify` fast and deterministic; do **not** include browser/server E2E there.
2. Add a separate root target, usually `make e2e-local`, backed by a script such as `scripts/e2e-local-dashboard.sh`.
3. Preserve default dev ports, but let E2E find alternatives:
   - Gateway default: `8080`
   - Dashboard default: `5174`
   - Optional overrides: `JARVIS_E2E_GATEWAY_PORT`, `JARVIS_E2E_DASHBOARD_PORT`
4. Never kill foreign processes. If a port is occupied, print a warning and choose a free local port.
5. Start only mock/demo servers bound to `127.0.0.1`:
   - Gateway: `JARVIS_DEMO_MODE=1 JARVIS_ENV=development PYTHONPATH=. python3 -m uvicorn ... --host 127.0.0.1 --port <port>`
   - Dashboard: `VITE_API_BASE_URL=http://127.0.0.1:<gateway_port> VITE_JARVIS_DEMO_MODE=1 npm run dev -- --host 127.0.0.1 --port <port>`
6. Wait for `/api/healthz` and dashboard `/` before running browser tests.
7. Trap `EXIT/INT/TERM` and cleanly terminate only the child PIDs the harness started.
8. Write logs/artifacts only under ignored folders such as `.tmp/e2e/`, `test-results/`, and `playwright-report/`.

## Playwright setup

- Add `@playwright/test` as a dev dependency only.
- Add `playwright.config.ts` with `testDir: './e2e'`, `outputDir: 'test-results'`, screenshots/traces only on failure, and HTML reports under `playwright-report`.
- Exclude `e2e/**` from Vitest, otherwise `npm test` may try to execute Playwright specs and fail with `Playwright Test did not expect test() to be called here`.
- If browsers are missing, run and document: `cd apps/dashboard && npx playwright install --with-deps chromium`.

## Useful specs

- `home.spec.ts`: real mock gateway load, heading visible, attention list, module overview, max 4 cards, max 5 attention items, max 3 KPIs/card, no tables/iframes/canvas/chart SVGs.
- `navigation.spec.ts`: all routes reachable and navigation links work.
- `responsive.spec.ts`: desktop sidebar, iPad bottom nav, no horizontal scroll, important nav targets >= 44px.
- `offline.spec.ts`: demo fallback visible when API is unreachable; production/no-fallback mode shows redacted error and no fixture fallback.
- `safety.spec.ts`: rendered visible text and app DOM exclude forbidden fields/secrets/paths. Check the app root DOM, not the entire Vite dev HTML, because dev tooling can inject local paths into style metadata.

## Pitfalls

- Tailwind `lg` starts at 1024px; iPad landscape can accidentally get the desktop sidebar. For iPad-first bottom nav, prefer a larger breakpoint such as `xl` for desktop shell behavior.
- Route interception may not catch absolute API URLs compiled from `VITE_API_BASE_URL`. For offline E2E, a narrow test-only API-base override can be acceptable if restricted to `http://127.0.0.1:<port>` and documented.
- Do not commit screenshots, traces, videos, reports, `.tmp/`, `dist/`, or build caches.
- Safety scanners should use targeted allowlists for dedicated safety test files only, not broad `apps/**` or `e2e/**` allowlists.

## Verification

Run and report real output:

```bash
make dashboard-test
make dashboard-build
make test-gateway
python3 scripts/verify-repo-safety.py
make verify
make e2e-local
```

If `make e2e-local` cannot run, report the exact missing dependency or setup command; do not claim E2E passed.