# End-to-End Suite (e2e)

Owns Playwright-based end-to-end verification of the desktop product. Tests boot the real Electron application against the real signaling server and exercise user-visible flows across chat, voice, screen-share, settings, plugins, and auth.

> **Format reference:**
> - **Vocabulary** — bold term, one-sentence definition, aliases to avoid.
> - **Relationships** — bullets with bold terms and cardinality.
> - **Boundaries / IO** — what this subdomain exposes and consumes.
> - **Invariants** — rules that always hold.
> - **Flagged ambiguities** — terms in dispute with proposed resolutions.
>
> See `agents-docs/AGENTS_CONTEXT.md` for the contract. Update in the same turn a trigger fires (see `agents-docs/AGENT_WORKFLOW.md` § CONTEXT.md upkeep).

## Vocabulary

| Term | Definition | Aliases to avoid |
|------|------------|------------------|
| **Feature area** | A top-level folder under `tests/` (`auth/`, `chat/`, `voice/`, `screen-share/`, `settings/`, `plugins/`) corresponding to a slice of user-visible behavior. | "category", "section" |
| **Page object** | A test-side abstraction over a screen or panel that exposes user-intent methods rather than raw selectors. | "page model" |
| **Fixture** | A Playwright `test.extend(...)` setup that prepares one or more user/app instances before a test runs. | "helper" |
| **Pair test** | An E2E test that boots two Electron instances simultaneously to verify P2P flows (calls, screen-share, transfers). | "multi-client test" |

## Relationships

- A **Feature area** owns one or more `*.spec.ts` files plus its own **Page objects** and **Fixtures**.
- A **Pair test** depends on the **server** subdomain being reachable — both clients connect to the same signaling server.
- **Page objects** depend only on the rendered DOM produced by **toju-app**; if a selector changes, only the page object should need updating.
- The suite as a whole depends on **electron** (built via `npm run build:electron`) and a usable **server** (`npm run server:dev` or `npm run dev`).

## Boundaries / IO

- **Exposes:** test results (HTML report at `test-results/html-report`, JUnit/JSON output on CI). No production surface.
- **Consumes:**
  - The built product (toju-app + electron) — typically launched via Playwright's Electron support.
  - The signaling server (started before the suite runs).
  - System resources: audio devices for voice tests, screen-capture for screen-share tests. The `.agents/skills/playwright-e2e/SKILL.md` documents how the suite handles the multi-client setup.

## Invariants

- Tests interact only through **Page objects** and **Fixtures** — no raw `page.click('.css-class-name')` scattered across specs.
- Tests must clean up state between runs — a flaky run that leaves cruft in the local database or signaling server is a bug, not an environment issue.
- The suite must run headless on CI (`npm run test:e2e`); the `ui` and `debug` variants exist for local development only.

## Flagged ambiguities

- _None recorded yet — add entries when a test concept (e.g. "pair test" vs "multi-client test") resists clean definition._

---

*Agent-procedural rules (TDD, lint) live in `/AGENTS.md`. Practical patterns for writing Playwright tests on this project live in `.agents/skills/playwright-e2e/SKILL.md`. This file is the bounded-context domain artefact for the E2E suite.*