codes

Purpose

TESTING_DOM_CODES is the package-local error code registry for @suaveplan/testing-dom. All codes share the TESTING_DOM. namespace so consumers can match on the prefix to spot testing-library failures in aggregated logs. The registry is hand-built here rather than going through defineCodes from @suaveplan/error because this package has zero @suaveplan/* deps by design.

Features

Frozen record of TESTING_DOM.* code strings
TestingDomCode type alias for the discriminated union
Stable — new codes append; removal requires a deprecation cycle
Structural twin of the defineCodes output used by Layer 1 packages

Usage: Basic Example

import { TESTING_DOM_CODES } from "@suaveplan/testing-dom";

TESTING_DOM_CODES.RENDER_FAILED; // "TESTING_DOM.RENDER.FAILED"

Usage: Advanced Example

import {
    TestingDomError,
    TESTING_DOM_CODES,
    type TestingDomCode,
} from "@suaveplan/testing-dom";

function classify(err: TestingDomError): "retry" | "fail" {
    switch (err.code) {
        case TESTING_DOM_CODES.USER_EVENT_INIT_FAILED:
            return "retry";
        case TESTING_DOM_CODES.RENDER_FAILED:
        case TESTING_DOM_CODES.QUERY_FAILED:
            return "fail";
    }
}

function isTestingDomError(err: unknown): err is TestingDomError {
    return err instanceof TestingDomError;
}

API Reference

`TESTING_DOM_CODES`

Frozen record of reason → fully-qualified code string.

`type TestingDomCode`

Union of every TESTING_DOM_CODES[K] value.

Implementation Notes

The runtime record is built by hand (Object.freeze({ ... })) rather than via defineCodes to maintain the zero-workspace-dep constraint. Adding a new code: append to the record, append to the union type, and keep existing entries unchanged. The package's own test suite verifies that every entry carries a TESTING_DOM. prefix and that no two entries share a value.

Registry Layout

Codes live under the TESTING.DOM namespace and are produced by defineCodes — same pattern as every other Suaveplan package. Current codes cover render host mount failures, query helper missing-element errors, matcher setup failures, and polyfill double-install attempts. The TestingDomCode union is the canonical parameter type for catch blocks and error-helper signatures.

Stability

Adding a new code is append-only: no renumbering, no migrations. Consumers that type-narrow on code get a compile error when a new code is added without a matching branch only if they use the TestingDomCode union exhaustively (e.g. in a switch with never check).

2.6 KiB Raw Blame History