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

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

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.

3.7 KiB Raw Blame History