Initial Commit

packages/testkit/testing/testing-e2e/src/errors/testing-e2e-error.md

@@ -0,0 +1,94 @@
+# testing-e2e-error
+
+## Purpose
+
+`TestingE2eError` is the structured error class thrown by every helper, fixture, and page object in `@suaveplan/testing-e2e`. Its shape mirrors `SuaveplanError` — `{ code, cause?, context? }` — but it does NOT extend it, because testing-infrastructure packages must stay free of any `@suaveplan/*` workspace dependency (rule #8 in `CLAUDE.md`).
+
+## Features
+
+- `code` narrowed to `TestingE2eCode` (the literal union of `TESTING_E2E.*` strings)
+- Named subclasses (`ConfigError`, `NavigationError`, `WaitTimeoutError`, `FixtureError`, `AbortedError`) for targeted `instanceof` checks
+- Preserves `cause` via ES2022 `Error.cause`
+- Optional `context` for structured diagnostic fields
+
+## Usage: Basic Example
+
+```ts
+import { WaitTimeoutError, TESTING_E2E_ERROR_CODES } from "@suaveplan/testing-e2e";
+
+throw new WaitTimeoutError(
+    TESTING_E2E_ERROR_CODES.WAIT_TIMEOUT,
+    "waitForNetworkIdle: network did not settle within 30000ms"
+);
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+    WaitTimeoutError,
+    NavigationError,
+    TestingE2eError,
+    TESTING_E2E_ERROR_CODES,
+} from "@suaveplan/testing-e2e";
+
+async function safeNavigate(url: string, page: Page): Promise<void> {
+    try {
+        await page.goto(url, { timeout: 10_000 });
+    } catch (cause) {
+        throw new NavigationError(
+            TESTING_E2E_ERROR_CODES.NAVIGATION_FAILED,
+            `navigation to ${url} failed`,
+            { cause, context: { url } }
+        );
+    }
+}
+
+try {
+    await safeNavigate("https://example.com", page);
+} catch (err) {
+    if (err instanceof TestingE2eError) {
+        console.error(err.code, err.context, err.cause);
+    }
+    throw err;
+}
+```
+
+## API Reference
+
+### `class TestingE2eError extends Error`
+
+- `readonly code: TestingE2eCode`
+- `readonly context?: Readonly<Record<string, unknown>>`
+- `cause?: unknown` (from `Error.cause`)
+
+### Subclasses
+
+- `ConfigError` — config-factory rejections
+- `NavigationError` — `page.goto` / routing failures
+- `WaitTimeoutError` — helper wait timeouts
+- `FixtureError` — fixture setup/teardown failures
+- `AbortedError` — signal-driven cancellations
+- `CloakLaunchError` — `cloakbrowser` launcher failures (binary
+  missing, proxy invalid, generic launch failure)
+
+### Cloak helpers
+
+- `classifyCloakError(err) → TestingE2eErrorCode` — pure synchronous
+  classifier mapping raw errors thrown by `cloakbrowser` to one of the
+  three `TESTING_E2E.CLOAK.*` codes. Returns `LAUNCH_FAILED` for any
+  error the classifier does not specifically recognise.
+- `wrapCloakError(err, context?) → CloakLaunchError` — convenience
+  wrapper used by every cloakbrowser-backed fixture. Classifies the
+  raw error, appends a remediation hint where applicable
+  (`npx cloakbrowser install` for binary issues, proxy verification
+  for proxy errors), and preserves the original error via
+  `Error.cause`.
+
+## Implementation Notes
+
+The subclasses exist so callers can write `catch (err instanceof WaitTimeoutError)` in hot paths without a `switch` on `code`. They all share the same structural shape — the subclass is purely a type-narrowing aid, not a behavioural difference. The base class deliberately does not extend `SuaveplanError` — if the project ever relaxes the testing-infra dep rule, swapping the base is a one-line change and no caller breaks.
+
+### Subclass Index
+
+`TestingE2eError` is the base class. Subclasses cover `ClipboardMockError`, `GeolocationMockError`, `PageObjectTimeoutError`, and `DialogDismissalError`. Every subclass sets its own code from `TESTING_E2E_CODES`, overrides `name`, and inherits wire-serialisation + OTel span-event behaviour from `SuaveplanError` so Playwright trace viewers see a consistent error shape.