@dudousxd/nestjs-durable-testing 0.3.0 → 0.4.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Davide Carvalho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -1,6 +1,130 @@
-export * from './assertions';
-export * from './harness';
-export * from './replay';
-export * from './steps';
-export * from './transport-conformance';
-//# sourceMappingURL=index.d.ts.map
+import { StateStore, RunStatus, WorkflowEngine, InMemoryStateStore, InMemoryTransport, RunResult, WorkflowRef, StartOptions, WorkflowRun, StepCheckpoint, Transport } from '@dudousxd/nestjs-durable-core';
+
+declare function assertRunStatus(store: StateStore, runId: string, status: RunStatus): Promise<void>;
+declare function assertOutput(store: StateStore, runId: string, expected: unknown): Promise<void>;
+/** The names of the steps that have run, in order. */
+declare function recordedSteps(store: StateStore, runId: string): Promise<string[]>;
+/** Assert every named step ran (in any order). */
+declare function assertStepsRan(store: StateStore, runId: string, names: string[]): Promise<void>;
+/** Assert a step ran exactly the given number of attempts (e.g. to verify retries). */
+declare function assertStepAttempts(store: StateStore, runId: string, name: string, attempts: number): Promise<void>;
+
+/** A clock you control, for testing durable sleeps without real time. */
+declare class MutableClock {
+    private current;
+    constructor(current?: number);
+    readonly now: () => number;
+    set(ms: number): void;
+    advance(ms: number): void;
+}
+interface TestEngine {
+    engine: WorkflowEngine;
+    store: InMemoryStateStore;
+    transport: InMemoryTransport;
+    clock: MutableClock;
+    /** Advance the clock by `ms` and resume any durable sleeps now due. */
+    tick(ms: number): Promise<RunResult[]>;
+    /**
+     * Enqueue a run and wait for it to settle (terminal or suspended). `engine.start` only enqueues
+     * now (dispatch model), so use this when a test needs the outcome synchronously.
+     */
+    run(workflow: WorkflowRef, input: unknown, runId: string, opts?: StartOptions): Promise<RunResult>;
+}
+/**
+ * A self-contained engine wired to in-memory store + transport and a controllable clock — run a
+ * whole workflow in a unit test, with no Postgres, no Redis, and no real time.
+ */
+declare function createTestEngine(): TestEngine;
+
+interface RunHistory {
+    run: WorkflowRun;
+    checkpoints: StepCheckpoint[];
+}
+/**
+ * Replay a recorded run's history against the CURRENT workflow code and throw if they diverged.
+ *
+ * Capture a real (ideally in-flight or representative) run from production —
+ * `{ run: await store.getRun(id), checkpoints: await store.listCheckpoints(id) }` — commit it as a
+ * fixture, and assert here in CI. If a code change renamed/reordered/removed a step at a position the
+ * history already recorded, the engine raises a `NonDeterminismError` on replay and this rethrows it,
+ * catching the break *before* it reaches an in-flight run on deploy (the moment you'd otherwise
+ * silently replay the wrong checkpoint into the wrong step). Register the workflow exactly as the app
+ * does:
+ *
+ * ```ts
+ * await assertReplayable((engine) => engine.register('pipeline', '1', pipeline.run), fixture);
+ * ```
+ */
+declare function assertReplayable(register: (engine: WorkflowEngine) => void, history: RunHistory): Promise<void>;
+
+/**
+ * A freshly provisioned, empty {@link StateStore} plus a `cleanup` to release its resources (close
+ * the connection, drop the schema, etc.). The conformance suite asks for one before each test so
+ * every case starts from a clean slate — exactly like the per-store specs that build a `:memory:` DB.
+ */
+interface StateStoreContext {
+    store: StateStore;
+    cleanup: () => Promise<void>;
+    /**
+     * Whether the store's optional `transaction` can run an ASYNC work callback. Defaults to `true`.
+     * Set `false` only for a driver that genuinely can't — e.g. Drizzle on the SYNCHRONOUS
+     * `better-sqlite3` driver, whose `transaction()` rejects a promise-returning callback ("Transaction
+     * function cannot return a promise"). The same Drizzle adapter on an async driver (libSQL) works,
+     * and the contract still asserts `transaction` for every other store, so this never hides drift.
+     */
+    supportsAsyncTransaction?: boolean;
+    /**
+     * Whether the store can filter `listRuns({ tag })`. Defaults to `true`. Set `false` ONLY for
+     * Prisma-on-SQLite: the Prisma adapter filters tags with the `array_contains` JSON predicate, which
+     * Prisma supports on its real targets (Postgres + MySQL) but NOT on SQLite. SQLite is only the
+     * adapter's local TEST database, so the tag case is skipped there; every other store (and Prisma on
+     * a real engine) still asserts it, so this doesn't hide drift in the supported configurations.
+     */
+    supportsTagFilter?: boolean;
+}
+/** Builds a fresh, empty store for one test. Called once per `it` (in `beforeEach`). */
+type StateStoreFactory = () => Promise<StateStoreContext>;
+/**
+ * Thrown by a {@link StateStoreFactory} to SKIP the contract for an unavailable backend instead of
+ * failing it — e.g. a testcontainers DB spec when Docker isn't running. Every contract case catches
+ * it, logs once, and returns (a no-op pass), so `pnpm test:db` is green-with-skips off a dev box
+ * without Docker rather than red.
+ */
+declare class StateStoreUnavailableError extends Error {
+    readonly isStateStoreUnavailable = true;
+    constructor(message: string);
+}
+/**
+ * The SHARED behavioral contract every `StateStore` must satisfy — in-memory and each ORM adapter
+ * alike. Registered as a vitest `describe`; pass a `name` and a {@link StateStoreFactory} that builds
+ * a fresh, empty store. The same assertions run against SQLite/in-memory under `pnpm test` and
+ * against real Postgres/MySQL (via testcontainers) under `pnpm test:db`, so any drift between an
+ * adapter and the canonical (in-memory) semantics — especially the search-attribute side-table
+ * pushdown, which is implemented per-store — fails here instead of silently in production.
+ *
+ * Each adapter's own spec keeps its dialect-specific tests (DDL/longtext/EXISTS-SQL/JSON-tolerance);
+ * this suite owns the cross-store behavior so those never drift apart.
+ */
+declare function runStateStoreContract(name: string, makeStore: StateStoreFactory): void;
+
+/** A step body that throws once, then returns `value` — drives a retry, or a crash-then-resume. */
+declare function failOnce<T>(value: T, error?: Error): () => Promise<T>;
+/** A step body that throws the first `n` times, then returns `value`. */
+declare function failTimes<T>(n: number, value: T, error?: Error): () => Promise<T>;
+
+/** A transport that can register worker handlers (every shipped transport does). */
+type HandleableTransport = Transport & {
+    handle(name: string, fn: (input: unknown) => Promise<unknown>): void;
+    close?(): Promise<void>;
+};
+/**
+ * The contract every `Transport` must satisfy: a remote step dispatched through it round-trips to a
+ * worker and back (success), and a throwing handler surfaces as a failed run (failure). Point it at
+ * a freshly constructed transport (engine-side + worker `group` in one instance) to prove parity —
+ * useful when adding a new transport. Throws on any mismatch; closes the transport when done.
+ *
+ * `idPrefix` keeps run ids unique across invocations against real, shared infra (queues/tables).
+ */
+declare function assertTransportConformance(transport: HandleableTransport, idPrefix?: string): Promise<void>;
+
+export { type HandleableTransport, MutableClock, type RunHistory, type StateStoreContext, type StateStoreFactory, StateStoreUnavailableError, type TestEngine, assertOutput, assertReplayable, assertRunStatus, assertStepAttempts, assertStepsRan, assertTransportConformance, createTestEngine, failOnce, failTimes, recordedSteps, runStateStoreContract };