@nage-api/testing 1.0.0-beta.2

package/dist/containers/harness.d.ts

@@ -0,0 +1,123 @@
+/**
+ * The Testcontainers harness (PLAN.md §19, §24 Phase 9 risk: "flaky containers —
+ * pin images, retry, parallelize").
+ *
+ * The point of this file is to make integration tests *skip* cleanly rather than
+ * fail when no container runtime is available, and to make the three
+ * flakiness-mitigations the plan names structural rather than remembered:
+ *
+ *  - **pinned images.** A tag like `postgres:16` moves. `IMAGES` pins digests-in-
+ *    spirit by pinning exact patch versions, and the table is the only place a
+ *    version appears, so an upgrade is one edit rather than a grep.
+ *  - **retry.** Container startup fails transiently — a port race, a slow pull.
+ *    `start` retries with backoff before giving up.
+ *  - **parallel-safe.** Every container gets a unique name and an ephemeral
+ *    port, so two suites running at once cannot collide.
+ *
+ * `testcontainers` itself is **not** a dependency. This package sits at the
+ * bottom of the graph and must stay installable without Docker, so the runtime
+ * is a port: a project that wants real containers passes an adapter over
+ * `testcontainers`, and everything else gets `skipIfUnavailable`.
+ *
+ * Note for this repository: there is no container runtime in the development
+ * environment, so the adapter path is unit-tested against a fake runtime and has
+ * never been exercised against Docker. That is stated in the README rather than
+ * implied to be verified.
+ */
+/** A service an integration test can ask for. */
+export type ContainerService = 'postgres' | 'mysql' | 'mariadb' | 'mongo' | 'redis';
+/**
+ * Pinned images, one per service.
+ *
+ * Exact patch versions, not floating tags: `postgres:16` is a different image
+ * next month, and an integration suite that changes underneath you is worse than
+ * one that is out of date.
+ */
+export declare const IMAGES: Readonly<Record<ContainerService, string>>;
+/** The port each service listens on inside its container. */
+export declare const INTERNAL_PORTS: Readonly<Record<ContainerService, number>>;
+/** A started container, as the harness reports it. */
+export interface StartedContainer {
+    readonly service: ContainerService;
+    readonly host: string;
+    /** The mapped, ephemeral host port. */
+    readonly port: number;
+    /** A connection URL an application config can use directly. */
+    readonly url: string;
+    stop(): Promise<void>;
+}
+/** What the harness needs from a container runtime. */
+export interface ContainerRuntime {
+    readonly name: string;
+    /** Whether containers can actually be started right now. */
+    isAvailable(): Promise<boolean>;
+    start(request: {
+        image: string;
+        internalPort: number;
+        /** Unique per run, so parallel suites cannot collide. */
+        containerName: string;
+        environment: Readonly<Record<string, string>>;
+    }): Promise<{
+        host: string;
+        port: number;
+        stop(): Promise<void>;
+    }>;
+}
+export interface ContainerHarnessOptions {
+    readonly runtime: ContainerRuntime;
+    /** Attempts before giving up on a container that will not start. */
+    readonly maxAttempts?: number;
+    /** Delay before the first retry; doubled each time. */
+    readonly retryDelayMs?: number;
+    /** Injected so the retry backoff does not really sleep in a unit test. */
+    readonly sleep?: (ms: number) => Promise<void>;
+    /** Injected so container names are deterministic in a test. */
+    readonly nameSuffix?: () => string;
+}
+export declare class ContainerHarness {
+    #private;
+    constructor(options: ContainerHarnessOptions);
+    /**
+     * Whether containers are usable. Memoised: probing a missing Docker socket
+     * per test is slow and the answer never changes within a run.
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Start a service, retrying transient failures.
+     *
+     * @throws the last error when every attempt fails — a container that will not
+     * start is a real failure, not something to skip over.
+     */
+    start(service: ContainerService): Promise<StartedContainer>;
+    /** Stop everything this harness started. Safe to call twice. */
+    stopAll(): Promise<void>;
+    get running(): readonly StartedContainer[];
+}
+/**
+ * Register an integration suite that runs only when containers are available.
+ *
+ * Skipping is not the same as passing, so the skip is loud: the suite name says
+ * it was skipped and why, and a `requireContainers` flag turns the skip into a
+ * failure for the CI job that is supposed to have Docker.
+ */
+export interface ContainerSuiteApi {
+    describe: (name: string, fn: () => void) => void;
+    it: (name: string, fn: () => Promise<void> | void) => void;
+}
+export declare function describeWithContainers(api: ContainerSuiteApi, options: {
+    readonly name: string;
+    readonly harness: ContainerHarness;
+    /** Fail rather than skip when no runtime is available. */
+    readonly required?: boolean;
+    readonly suite: () => void;
+}): Promise<void>;
+/** The connection URL for a started service. */
+export declare function urlFor(service: ContainerService, host: string, port: number): string;
+/**
+ * A runtime that reports nothing is available.
+ *
+ * The default, so an integration suite in an environment without Docker skips
+ * rather than throwing a confusing connection error.
+ */
+export declare const unavailableRuntime: ContainerRuntime;
+//# sourceMappingURL=harness.d.ts.map

package/dist/containers/harness.js

@@ -0,0 +1,222 @@
+"use strict";
+/**
+ * The Testcontainers harness (PLAN.md §19, §24 Phase 9 risk: "flaky containers —
+ * pin images, retry, parallelize").
+ *
+ * The point of this file is to make integration tests *skip* cleanly rather than
+ * fail when no container runtime is available, and to make the three
+ * flakiness-mitigations the plan names structural rather than remembered:
+ *
+ *  - **pinned images.** A tag like `postgres:16` moves. `IMAGES` pins digests-in-
+ *    spirit by pinning exact patch versions, and the table is the only place a
+ *    version appears, so an upgrade is one edit rather than a grep.
+ *  - **retry.** Container startup fails transiently — a port race, a slow pull.
+ *    `start` retries with backoff before giving up.
+ *  - **parallel-safe.** Every container gets a unique name and an ephemeral
+ *    port, so two suites running at once cannot collide.
+ *
+ * `testcontainers` itself is **not** a dependency. This package sits at the
+ * bottom of the graph and must stay installable without Docker, so the runtime
+ * is a port: a project that wants real containers passes an adapter over
+ * `testcontainers`, and everything else gets `skipIfUnavailable`.
+ *
+ * Note for this repository: there is no container runtime in the development
+ * environment, so the adapter path is unit-tested against a fake runtime and has
+ * never been exercised against Docker. That is stated in the README rather than
+ * implied to be verified.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unavailableRuntime = exports.ContainerHarness = exports.INTERNAL_PORTS = exports.IMAGES = void 0;
+exports.describeWithContainers = describeWithContainers;
+exports.urlFor = urlFor;
+/**
+ * Pinned images, one per service.
+ *
+ * Exact patch versions, not floating tags: `postgres:16` is a different image
+ * next month, and an integration suite that changes underneath you is worse than
+ * one that is out of date.
+ */
+exports.IMAGES = {
+    postgres: 'postgres:16.4-alpine',
+    mysql: 'mysql:8.4.2',
+    mariadb: 'mariadb:11.4.3',
+    mongo: 'mongo:7.0.14',
+    redis: 'redis:7.4.0-alpine',
+};
+/** The port each service listens on inside its container. */
+exports.INTERNAL_PORTS = {
+    postgres: 5432,
+    mysql: 3306,
+    mariadb: 3306,
+    mongo: 27017,
+    redis: 6379,
+};
+const DEFAULT_MAX_ATTEMPTS = 3;
+const DEFAULT_RETRY_DELAY_MS = 1000;
+/**
+ * Monotonic, process-wide, and the only thing that makes a container name
+ * genuinely unique.
+ *
+ * The suffix alone is not enough: it is derived from a clock, so two containers
+ * of the same service started in the same millisecond — two suites running in
+ * parallel, or one suite starting a pair — get identical names, and Docker
+ * refuses the second. The counter also covers the retry case, since a
+ * half-started container from a failed attempt may still hold its name.
+ */
+let containerSequence = 0;
+/** Credentials the harness sets, and the URLs it builds from them. */
+const CREDENTIALS = { user: 'nage', password: 'nage', database: 'nage_test' };
+class ContainerHarness {
+    #runtime;
+    #maxAttempts;
+    #retryDelayMs;
+    #sleep;
+    #nameSuffix;
+    #started = [];
+    #available;
+    constructor(options) {
+        this.#runtime = options.runtime;
+        this.#maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+        this.#retryDelayMs = options.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS;
+        this.#sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+        this.#nameSuffix =
+            options.nameSuffix ?? (() => `${String(process.pid)}-${Math.trunc(performance.now())}`);
+    }
+    /**
+     * Whether containers are usable. Memoised: probing a missing Docker socket
+     * per test is slow and the answer never changes within a run.
+     */
+    async isAvailable() {
+        this.#available ??= await this.#runtime.isAvailable();
+        return this.#available;
+    }
+    /**
+     * Start a service, retrying transient failures.
+     *
+     * @throws the last error when every attempt fails — a container that will not
+     * start is a real failure, not something to skip over.
+     */
+    async start(service) {
+        let lastError;
+        for (let attempt = 1; attempt <= this.#maxAttempts; attempt += 1) {
+            try {
+                containerSequence += 1;
+                const started = await this.#runtime.start({
+                    image: exports.IMAGES[service],
+                    internalPort: exports.INTERNAL_PORTS[service],
+                    containerName: `nage-${service}-${this.#nameSuffix()}-${String(containerSequence)}`,
+                    environment: environmentFor(service),
+                });
+                const container = {
+                    service,
+                    host: started.host,
+                    port: started.port,
+                    url: urlFor(service, started.host, started.port),
+                    // Wrapped, not passed by reference: a runtime whose `stop` reads
+                    // `this` would break when the method is detached from its object.
+                    stop: () => started.stop(),
+                };
+                this.#started.push(container);
+                return container;
+            }
+            catch (error) {
+                lastError = error;
+                if (attempt < this.#maxAttempts)
+                    await this.#sleep(this.#retryDelayMs * 2 ** (attempt - 1));
+            }
+        }
+        throw new Error(`Could not start ${service} (${exports.IMAGES[service]}) after ${String(this.#maxAttempts)} attempts: ${lastError instanceof Error ? lastError.message : String(lastError)}`, { cause: lastError });
+    }
+    /** Stop everything this harness started. Safe to call twice. */
+    async stopAll() {
+        const stopping = this.#started.splice(0).map(async (container) => {
+            try {
+                await container.stop();
+            }
+            catch {
+                // A container that failed to stop must not fail the suite: the run is
+                // over, and the runtime will reap it.
+            }
+        });
+        await Promise.all(stopping);
+    }
+    get running() {
+        return this.#started;
+    }
+}
+exports.ContainerHarness = ContainerHarness;
+async function describeWithContainers(api, options) {
+    const available = await options.harness.isAvailable();
+    if (available) {
+        api.describe(options.name, options.suite);
+        return;
+    }
+    if (options.required === true) {
+        api.describe(options.name, () => {
+            api.it('should have a container runtime available', () => {
+                throw new Error('No container runtime is available, and this suite is marked required. ' +
+                    'Start Docker, or unset the flag that requires containers.');
+            });
+        });
+        return;
+    }
+    api.describe(`${options.name} (skipped: no container runtime)`, () => {
+        api.it('should be run in an environment with Docker', () => {
+            // A skipped suite that reports nothing is indistinguishable from one that
+            // passed, so it leaves a visible, passing marker instead.
+        });
+    });
+}
+function environmentFor(service) {
+    switch (service) {
+        case 'postgres':
+            return {
+                POSTGRES_USER: CREDENTIALS.user,
+                POSTGRES_PASSWORD: CREDENTIALS.password,
+                POSTGRES_DB: CREDENTIALS.database,
+            };
+        case 'mysql':
+        case 'mariadb':
+            return {
+                MYSQL_ROOT_PASSWORD: CREDENTIALS.password,
+                MYSQL_USER: CREDENTIALS.user,
+                MYSQL_PASSWORD: CREDENTIALS.password,
+                MYSQL_DATABASE: CREDENTIALS.database,
+            };
+        case 'mongo':
+            return {
+                MONGO_INITDB_ROOT_USERNAME: CREDENTIALS.user,
+                MONGO_INITDB_ROOT_PASSWORD: CREDENTIALS.password,
+            };
+        case 'redis':
+            return {};
+    }
+}
+/** The connection URL for a started service. */
+function urlFor(service, host, port) {
+    const authority = `${CREDENTIALS.user}:${CREDENTIALS.password}@${host}:${String(port)}`;
+    switch (service) {
+        case 'postgres':
+            return `postgres://${authority}/${CREDENTIALS.database}`;
+        case 'mysql':
+            return `mysql://${authority}/${CREDENTIALS.database}`;
+        case 'mariadb':
+            return `mariadb://${authority}/${CREDENTIALS.database}`;
+        case 'mongo':
+            return `mongodb://${authority}/${CREDENTIALS.database}?authSource=admin`;
+        case 'redis':
+            return `redis://${host}:${String(port)}`;
+    }
+}
+/**
+ * A runtime that reports nothing is available.
+ *
+ * The default, so an integration suite in an environment without Docker skips
+ * rather than throwing a confusing connection error.
+ */
+exports.unavailableRuntime = {
+    name: 'none',
+    isAvailable: async () => Promise.resolve(false),
+    start: async () => Promise.reject(new Error('No container runtime is configured')),
+};
+//# sourceMappingURL=harness.js.map

package/dist/doubles/index.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Doubles for the ports the framework declares (PLAN.md §19: "mock at the
+ * **port** boundary … not deep ORM internals").
+ *
+ * Every one of these is a real, complete implementation of a contract, not a
+ * stub that returns `undefined`. That distinction matters: a stub agrees with
+ * whatever the code under test does, so a test built on one passes even when the
+ * code is wrong. A real implementation disagrees.
+ *
+ * The repository double is deliberately **not** here. `@nage-api/data` already
+ * ships `MemoryRepository`, and it is the one the driver conformance suite runs
+ * against — so it is the only in-memory repository whose behaviour is proven to
+ * match a real driver's. Duplicating it in the kit would produce a second
+ * implementation with no such guarantee. (§19 lists an in-memory driver as part
+ * of this package; that is the one deviation, and it is deliberate: the kit sits
+ * below `@nage-api/data` in the dependency graph and may not import it.)
+ */
+import type { KeyValueStore, LogFields, LoggerPort, RateLimitResult, RateLimitStore, SecretProviderPort } from '@nage-api/contracts';
+/** A clock a test advances by hand, so no test ever waits. */
+export declare class FakeClock {
+    #private;
+    constructor(start?: number);
+    now(): number;
+    advance(milliseconds: number): this;
+    /** Move to an absolute instant, for testing an expiry boundary exactly. */
+    set(epochMs: number): this;
+}
+export interface CapturedLog {
+    readonly level: string;
+    readonly message: string;
+    readonly fields: LogFields;
+}
+/**
+ * A logger that records.
+ *
+ * Useful for the assertion that matters most about logging: that a credential
+ * never reaches a log line. `entries` is inspectable, so `expectNoSecrets` can
+ * be pointed straight at it.
+ */
+export declare class RecordingLogger implements LoggerPort {
+    #private;
+    readonly entries: CapturedLog[];
+    constructor(bindings?: LogFields);
+    trace(message: string, fields?: LogFields): void;
+    debug(message: string, fields?: LogFields): void;
+    info(message: string, fields?: LogFields): void;
+    warn(message: string, fields?: LogFields): void;
+    error(message: string, fields?: LogFields): void;
+    fatal(message: string, fields?: LogFields): void;
+    child(bindings: LogFields): LoggerPort;
+    /** Lines at one level. */
+    at(level: string): readonly CapturedLog[];
+    /** Everything logged, as one string — the cheapest way to assert on absence. */
+    get text(): string;
+    clear(): void;
+}
+/** A `KeyValueStore` with TTL honoured against an injectable clock. */
+export declare class MemoryKeyValueStore<TValue> implements KeyValueStore<TValue> {
+    #private;
+    constructor(clock?: {
+        now(): number;
+    });
+    get(key: string): Promise<TValue | null>;
+    set(key: string, value: TValue, ttlSeconds?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    get size(): number;
+    get keys(): readonly string[];
+}
+/**
+ * A rate-limit store a test drives.
+ *
+ * `consume` is a real fixed-window counter rather than a counter that always
+ * allows: a guard tested against a permissive double is a guard nobody has
+ * tested.
+ */
+export declare class MemoryRateLimitStore implements RateLimitStore {
+    #private;
+    readonly name = "memory-test";
+    constructor(clock?: {
+        now(): number;
+    });
+    consume(key: string, limit: number, windowMs: number): Promise<RateLimitResult>;
+    reset(key: string): Promise<void>;
+}
+/**
+ * A secret provider backed by a plain object.
+ *
+ * `require` rejects for a missing name, exactly as the env and AWS providers do
+ * — a double that returned `undefined` instead would hide every fail-fast test.
+ */
+export declare class StubSecretProvider implements SecretProviderPort {
+    #private;
+    readonly provider = "stub";
+    readonly reads: string[];
+    constructor(secrets?: Record<string, string>);
+    get(name: string): Promise<string | null>;
+    require(name: string): Promise<string>;
+    set(name: string, value: string): this;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/doubles/index.js

@@ -0,0 +1,201 @@
+"use strict";
+/**
+ * Doubles for the ports the framework declares (PLAN.md §19: "mock at the
+ * **port** boundary … not deep ORM internals").
+ *
+ * Every one of these is a real, complete implementation of a contract, not a
+ * stub that returns `undefined`. That distinction matters: a stub agrees with
+ * whatever the code under test does, so a test built on one passes even when the
+ * code is wrong. A real implementation disagrees.
+ *
+ * The repository double is deliberately **not** here. `@nage-api/data` already
+ * ships `MemoryRepository`, and it is the one the driver conformance suite runs
+ * against — so it is the only in-memory repository whose behaviour is proven to
+ * match a real driver's. Duplicating it in the kit would produce a second
+ * implementation with no such guarantee. (§19 lists an in-memory driver as part
+ * of this package; that is the one deviation, and it is deliberate: the kit sits
+ * below `@nage-api/data` in the dependency graph and may not import it.)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StubSecretProvider = exports.MemoryRateLimitStore = exports.MemoryKeyValueStore = exports.RecordingLogger = exports.FakeClock = void 0;
+/** A clock a test advances by hand, so no test ever waits. */
+class FakeClock {
+    #now;
+    constructor(start = Date.UTC(2026, 0, 1, 12, 0, 0)) {
+        this.#now = start;
+    }
+    now() {
+        return this.#now;
+    }
+    advance(milliseconds) {
+        this.#now += milliseconds;
+        return this;
+    }
+    /** Move to an absolute instant, for testing an expiry boundary exactly. */
+    set(epochMs) {
+        this.#now = epochMs;
+        return this;
+    }
+}
+exports.FakeClock = FakeClock;
+/**
+ * A logger that records.
+ *
+ * Useful for the assertion that matters most about logging: that a credential
+ * never reaches a log line. `entries` is inspectable, so `expectNoSecrets` can
+ * be pointed straight at it.
+ */
+class RecordingLogger {
+    entries = [];
+    #bindings;
+    constructor(bindings = {}) {
+        this.#bindings = bindings;
+    }
+    trace(message, fields = {}) {
+        this.#record('trace', message, fields);
+    }
+    debug(message, fields = {}) {
+        this.#record('debug', message, fields);
+    }
+    info(message, fields = {}) {
+        this.#record('info', message, fields);
+    }
+    warn(message, fields = {}) {
+        this.#record('warn', message, fields);
+    }
+    error(message, fields = {}) {
+        this.#record('error', message, fields);
+    }
+    fatal(message, fields = {}) {
+        this.#record('fatal', message, fields);
+    }
+    child(bindings) {
+        // Shares the same array, so a test can assert on everything the whole tree
+        // logged without collecting children.
+        const derived = new RecordingLogger({ ...this.#bindings, ...bindings });
+        Object.defineProperty(derived, 'entries', { value: this.entries });
+        return derived;
+    }
+    /** Lines at one level. */
+    at(level) {
+        return this.entries.filter((entry) => entry.level === level);
+    }
+    /** Everything logged, as one string — the cheapest way to assert on absence. */
+    get text() {
+        return JSON.stringify(this.entries);
+    }
+    clear() {
+        this.entries.length = 0;
+    }
+    #record(level, message, fields) {
+        this.entries.push({ level, message, fields: { ...this.#bindings, ...fields } });
+    }
+}
+exports.RecordingLogger = RecordingLogger;
+/** A `KeyValueStore` with TTL honoured against an injectable clock. */
+class MemoryKeyValueStore {
+    #entries = new Map();
+    #clock;
+    constructor(clock = { now: () => Date.now() }) {
+        this.#clock = clock;
+    }
+    async get(key) {
+        await Promise.resolve();
+        const entry = this.#entries.get(key);
+        if (entry === undefined)
+            return null;
+        if (entry.expiresAt !== undefined && entry.expiresAt <= this.#clock.now()) {
+            this.#entries.delete(key);
+            return null;
+        }
+        return entry.value;
+    }
+    async set(key, value, ttlSeconds) {
+        await Promise.resolve();
+        this.#entries.set(key, {
+            value,
+            ...(ttlSeconds === undefined ? {} : { expiresAt: this.#clock.now() + ttlSeconds * 1000 }),
+        });
+    }
+    async delete(key) {
+        await Promise.resolve();
+        this.#entries.delete(key);
+    }
+    get size() {
+        return this.#entries.size;
+    }
+    get keys() {
+        return [...this.#entries.keys()];
+    }
+}
+exports.MemoryKeyValueStore = MemoryKeyValueStore;
+/**
+ * A rate-limit store a test drives.
+ *
+ * `consume` is a real fixed-window counter rather than a counter that always
+ * allows: a guard tested against a permissive double is a guard nobody has
+ * tested.
+ */
+class MemoryRateLimitStore {
+    name = 'memory-test';
+    #windows = new Map();
+    #clock;
+    constructor(clock = { now: () => Date.now() }) {
+        this.#clock = clock;
+    }
+    async consume(key, limit, windowMs) {
+        await Promise.resolve();
+        const now = this.#clock.now();
+        const existing = this.#windows.get(key);
+        const window = existing === undefined || existing.resetAt <= now
+            ? { count: 0, resetAt: now + windowMs }
+            : existing;
+        window.count += 1;
+        this.#windows.set(key, window);
+        return {
+            allowed: window.count <= limit,
+            limit,
+            remaining: Math.max(0, limit - window.count),
+            resetAt: window.resetAt,
+            // Rounded up, so a caller told to wait 0 seconds never retries into the
+            // same window it was just refused from.
+            retryAfterSeconds: Math.max(1, Math.ceil((window.resetAt - now) / 1000)),
+        };
+    }
+    async reset(key) {
+        await Promise.resolve();
+        this.#windows.delete(key);
+    }
+}
+exports.MemoryRateLimitStore = MemoryRateLimitStore;
+/**
+ * A secret provider backed by a plain object.
+ *
+ * `require` rejects for a missing name, exactly as the env and AWS providers do
+ * — a double that returned `undefined` instead would hide every fail-fast test.
+ */
+class StubSecretProvider {
+    provider = 'stub';
+    reads = [];
+    #secrets;
+    constructor(secrets = {}) {
+        this.#secrets = { ...secrets };
+    }
+    async get(name) {
+        await Promise.resolve();
+        this.reads.push(name);
+        return this.#secrets[name] ?? null;
+    }
+    async require(name) {
+        const value = await this.get(name);
+        if (value === null)
+            throw new Error(`Required secret ${name} is not set`);
+        return value;
+    }
+    set(name, value) {
+        this.#secrets[name] = value;
+        return this;
+    }
+}
+exports.StubSecretProvider = StubSecretProvider;
+//# sourceMappingURL=index.js.map