Initial Commit

openspec/archive/2026-04-19-enterprise-testing-e2e/specs/testing-e2e/spec.md

@@ -0,0 +1,104 @@
+## ADDED Requirements
+
+### Requirement: Layer 0 dep-graph isolation
+
+The `@suaveplan/testing-e2e` `dependencies` and `peerDependencies` MUST NOT contain any `@suaveplan/*` workspace package. `devDependencies` MAY include `@suaveplan/testing` for the package's own tests.
+
+#### Scenario: Runtime closure clean
+
+- **WHEN** `bunx turbo ls --filter=@suaveplan/testing-e2e...` is run
+- **THEN** no `@suaveplan/*` package appears in the runtime closure
+
+### Requirement: Playwright primitive re-exports
+
+The package MUST re-export `test`, `expect`, `Page`, `Browser`, `BrowserContext`, `Locator`, `request` from `@playwright/test` so consumers import a single entry point.
+
+#### Scenario: Single-import consumer
+
+- **WHEN** a consumer imports `{ test, expect, Page }` from `@suaveplan/testing-e2e`
+- **THEN** the symbols are the Playwright originals (identity comparison passes)
+
+### Requirement: `createPlaywrightConfig` produces stable defaults
+
+The factory SHALL emit a `PlaywrightTestConfig` with `fullyParallel: false`, `use.trace: "on-first-retry"`, `use.screenshot: "only-on-failure"`, `use.video: "retain-on-failure"`. CI mode (detected via `process.env.CI`) MUST set `forbidOnly: true`, `retries: 2`, `workers: 1`. Caller-supplied overrides MUST take precedence.
+
+#### Scenario: Default config
+
+- **WHEN** `createPlaywrightConfig({ baseURL: "http://localhost:3000" })` is called
+- **THEN** the returned config has `fullyParallel === false` AND `use.trace === "on-first-retry"`
+
+#### Scenario: CI overrides
+
+- **WHEN** the factory runs with `process.env.CI === "1"` and no override
+- **THEN** the config has `forbidOnly === true`, `retries === 2`, `workers === 1`
+
+#### Scenario: Caller override wins
+
+- **WHEN** `createPlaywrightConfig({ retries: 5 })` is called with `process.env.CI === "1"`
+- **THEN** the config has `retries === 5`
+
+### Requirement: `PageObject` base class
+
+`PageObject` MUST be an abstract class accepting a Playwright `Page` in its constructor. It MUST expose `path: string` (abstract), `navigate(): Promise<void>`, `waitForReady(opts?): Promise<void>`, and convenience locator helpers (`findByRole`, `findByLabel`, `findByText`).
+
+#### Scenario: Subclass + navigate
+
+- **WHEN** a subclass extends `PageObject`, sets `path = "/users"`, and calls `await instance.navigate()`
+- **THEN** `page.goto("/users")` is called once
+
+#### Scenario: waitForReady aborts on signal
+
+- **WHEN** `waitForReady({ signal })` is called with a pre-aborted signal
+- **THEN** the promise rejects with `AbortedError` whose `code === "TESTING_E2E.ABORTED"`
+
+### Requirement: Helpers expose stable signatures
+
+The following helpers MUST be exported with the signatures below and SHALL throw `TestingE2eError` subclasses on failure (never plain `Error`):
+
+- `waitForNetworkIdle(page, options?): Promise<void>` — waits until the page sees `idleMs` of zero in-flight requests
+- `screenshotOnFailure(testInfo, page): Promise<void>` — captures a screenshot named after the failing test
+- `dismissDialog(page, action?): Promise<void>` — registers a one-shot dialog handler that auto-accepts (or auto-dismisses if `action === "dismiss"`)
+- `mockGeolocation(context, coords): Promise<void>` — installs a static geolocation override
+- `mockClipboard(page): Promise<void>` — installs a programmatic clipboard
+
+#### Scenario: waitForNetworkIdle resolves
+
+- **WHEN** the predicate observes zero in-flight requests for the configured `idleMs` window
+- **THEN** the promise resolves
+
+#### Scenario: waitForNetworkIdle times out
+
+- **WHEN** the network never quiets within `timeoutMs`
+- **THEN** the promise rejects with `WaitTimeoutError` whose `code === "TESTING_E2E.WAIT.TIMEOUT"`
+
+### Requirement: Structured errors with stable codes
+
+All errors thrown from `@suaveplan/testing-e2e` MUST be subclasses of `TestingE2eError extends Error` carrying `{ code, cause?, context? }`. Codes match `^TESTING_E2E\.[A-Z]+\.[A-Z_]+$`.
+
+#### Scenario: Coded error
+
+- **WHEN** any helper throws
+- **THEN** the thrown value `instanceof TestingE2eError` is true AND `err.code` matches the regex
+
+### Requirement: Coverage and docs gates
+
+Istanbul statement + branch + function + line coverage across `packages/universal/testing-e2e/src/` (excluding `*.bench.ts`, `*.schemas.ts`, barrel `index.ts` files) MUST be ≥ 95% on every dimension. Every implementation file MUST have a sibling `.md` (≥ 200 words, simple + advanced examples).
+
+#### Scenario: CI coverage gate
+
+- **WHEN** `bunx turbo test:coverage --filter=@suaveplan/testing-e2e` runs
+- **THEN** statement / branch / function / line coverage all ≥ 95%
+
+### Requirement: Test placement follows the genesis hard rule
+
+Per-feature unit tests SHALL be co-located in `src/` (named `<feature>.test.ts` next to `<feature>.ts`). Cross-cutting tests (dep-graph guard, tree-shake guard, no-disallowed grep guard) MUST live in `tests/` sibling to `src/`.
+
+#### Scenario: Per-feature co-location
+
+- **WHEN** `src/page-objects/page-object.ts` exists
+- **THEN** its unit tests live at `src/page-objects/page-object.test.ts`
+
+#### Scenario: Cross-cutting in tests/
+
+- **WHEN** a guard exercises package-level concerns (dep graph, tree-shake, lint)
+- **THEN** it lives under `tests/`