@voyantjs/workflows 0.0.0 → 0.6.8

package/dist/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"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"}

package/dist/testing/index.js

@@ -0,0 +1,595 @@
+// @voyantjs/workflows/testing
+//
+// In-process test harness with mocked steps, waits, and invokes.
+// Contract in docs/sdk-surface.md §11.
+//
+// Drives `executeWorkflowStep` across resumptions. Steps resolve
+// from a user-supplied stub map; waitpoints resolve from fixtures.
+import { executeWorkflowStep, } from "../runtime/executor.js";
+import { emptyJournal } from "../runtime/journal.js";
+import { getWorkflow } from "../workflow.js";
+export async function runWorkflowForTest(workflow, input, opts = {}) {
+    const def = workflow;
+    const now = opts.now ?? (() => Date.now());
+    const startedAt = now();
+    const journal = emptyJournal();
+    const metadata = {};
+    const events = [];
+    const streams = {};
+    const maxInvocations = opts.maxInvocations ?? 16;
+    const environment = {
+        name: opts.environment?.name ?? "development",
+        git: opts.environment?.git,
+    };
+    let invocationCount = 0;
+    let last;
+    // Track how many metadata mutations have already been applied so we
+    // only apply the delta on each invocation. Otherwise replays
+    // double-count `increment` / duplicate `append` values. (Positional
+    // dedup; mirrors what the real orchestrator does with journaled ids.)
+    let metadataAppliedCount = 0;
+    // Per-fixture cursors into iterable event/signal arrays, persisted
+    // across invocations so replay doesn't restart consumption.
+    const cursors = { event: new Map(), signal: new Map() };
+    while (invocationCount < maxInvocations) {
+        invocationCount += 1;
+        const response = await executeWorkflowStep(def, {
+            runId: `run_test_${def.id}`,
+            workflowId: def.id,
+            workflowVersion: "test",
+            input,
+            journal,
+            invocationCount,
+            environment: {
+                run: {
+                    id: `run_test_${def.id}`,
+                    number: 1,
+                    attempt: 1,
+                    triggeredBy: { kind: "api" },
+                    tags: [],
+                    startedAt,
+                },
+                workflow: { id: def.id, version: "test" },
+                environment,
+                project: { id: "prj_test", slug: "test" },
+                organization: { id: "org_test", slug: "test" },
+            },
+            triggeredBy: { kind: "api" },
+            runStartedAt: startedAt,
+            tags: [],
+            stepRunner: createStepRunner(opts, events, now),
+        });
+        last = response;
+        const newMutations = response.metadataUpdates.slice(metadataAppliedCount);
+        applyMetadata(metadata, newMutations);
+        metadataAppliedCount = response.metadataUpdates.length;
+        for (const chunk of response.streamChunks) {
+            const bucket = streams[chunk.streamId] ?? [];
+            streams[chunk.streamId] = bucket;
+            bucket.push(chunk);
+        }
+        if (response.status === "completed") {
+            return {
+                status: "completed",
+                output: response.output,
+                steps: stepsFromJournal(journal),
+                events,
+                metadata,
+                compensations: [],
+                streams,
+                invocations: invocationCount,
+            };
+        }
+        if (response.status === "failed") {
+            return {
+                status: "failed",
+                error: {
+                    category: response.error.category,
+                    code: response.error.code,
+                    message: response.error.message,
+                },
+                steps: stepsFromJournal(journal),
+                events,
+                metadata,
+                compensations: [],
+                streams,
+                invocations: invocationCount,
+            };
+        }
+        if (response.status === "cancelled") {
+            return {
+                status: "cancelled",
+                steps: stepsFromJournal(journal),
+                events,
+                metadata,
+                compensations: response.compensations,
+                streams,
+                invocations: invocationCount,
+            };
+        }
+        if (response.status === "compensated" || response.status === "compensation_failed") {
+            return {
+                status: response.status,
+                error: response.error
+                    ? {
+                        category: response.error.category,
+                        code: response.error.code,
+                        message: response.error.message,
+                    }
+                    : undefined,
+                steps: stepsFromJournal(journal),
+                events,
+                metadata,
+                compensations: response.compensations,
+                streams,
+                invocations: invocationCount,
+            };
+        }
+        // Waiting: resolve waitpoints from fixtures and loop. Waitpoints
+        // that have no fixture match either throw (default) or, when
+        // `pauseOnWait` is set, park the run and return a "waiting" result.
+        const stillPending = [];
+        for (const wp of response.waitpoints) {
+            const resolved = await resolveWaitpoint(wp, opts, now, events, cursors);
+            if (!resolved) {
+                if (opts.pauseOnWait) {
+                    stillPending.push(wp);
+                    continue;
+                }
+                throw new Error(`test harness: waitpoint ${wp.clientWaitpointId} (${wp.kind}) has no fixture resolution. ` +
+                    `Provide one via TestOptions.waitForEvent / waitForSignal / (sleeps auto-resolve), ` +
+                    `or set TestOptions.pauseOnWait to park the run.`);
+            }
+            journal.waitpointsResolved[wp.clientWaitpointId] = resolved;
+            events.push({
+                type: `waitpoint.resolved:${wp.kind}`,
+                at: resolved.resolvedAt,
+                data: resolved.payload ?? null,
+            });
+        }
+        if (stillPending.length > 0) {
+            return {
+                status: "waiting",
+                steps: stepsFromJournal(journal),
+                events,
+                metadata,
+                compensations: [],
+                streams,
+                invocations: invocationCount,
+                pause: {
+                    journal,
+                    pendingWaitpoints: stillPending,
+                    startedAt,
+                    invocationCount,
+                    metadataAppliedCount,
+                    fixtureCursors: {
+                        event: Object.fromEntries(cursors.event.entries()),
+                        signal: Object.fromEntries(cursors.signal.entries()),
+                    },
+                },
+            };
+        }
+    }
+    throw new Error(`test harness exceeded maxInvocations (${maxInvocations}). ` +
+        `Last status: ${last?.status ?? "<none>"}. Possible infinite waitpoint loop.`);
+}
+/**
+ * Resume a parked run. Matches the injection against one of the
+ * `pause.pendingWaitpoints`, records it in the journal, and re-enters
+ * the executor loop until the next pause or terminal state.
+ */
+export async function resumeWorkflowForTest(workflow, input, opts) {
+    const def = workflow;
+    const now = opts.now ?? (() => Date.now());
+    const maxInvocations = opts.maxInvocations ?? 16;
+    const matched = matchWaitpoint(opts.pause.pendingWaitpoints, opts.injection);
+    if (!matched) {
+        throw new Error(`resume: no pending waitpoint matches injection kind=${opts.injection.kind}, ` +
+            `key=${injectionKey(opts.injection)}`);
+    }
+    const journal = cloneJournal(opts.pause.journal);
+    journal.waitpointsResolved[matched.clientWaitpointId] = {
+        kind: matched.kind,
+        resolvedAt: now(),
+        payload: opts.injection.payload,
+        source: "live",
+        matchedEventId: opts.injection.kind === "EVENT" ? `evt_live_${opts.injection.eventType}` : undefined,
+    };
+    const events = [
+        {
+            type: `waitpoint.resolved:${matched.kind}`,
+            at: now(),
+            data: opts.injection.payload ?? null,
+        },
+    ];
+    const metadata = {};
+    const streams = {};
+    const cursors = {
+        event: new Map(Object.entries(opts.pause.fixtureCursors.event)),
+        signal: new Map(Object.entries(opts.pause.fixtureCursors.signal)),
+    };
+    const environment = {
+        name: opts.environment?.name ?? "development",
+        git: opts.environment?.git,
+    };
+    let invocationCount = opts.pause.invocationCount;
+    let metadataAppliedCount = opts.pause.metadataAppliedCount;
+    let last;
+    // Remaining pending waitpoints from the previous pause (still parked).
+    let carryover = opts.pause.pendingWaitpoints.filter((w) => w.clientWaitpointId !== matched.clientWaitpointId);
+    while (invocationCount < maxInvocations) {
+        invocationCount += 1;
+        const response = await executeWorkflowStep(def, {
+            runId: `run_test_${def.id}`,
+            workflowId: def.id,
+            workflowVersion: "test",
+            input,
+            journal,
+            invocationCount,
+            environment: {
+                run: {
+                    id: `run_test_${def.id}`,
+                    number: 1,
+                    attempt: 1,
+                    triggeredBy: { kind: "api" },
+                    tags: [],
+                    startedAt: opts.pause.startedAt,
+                },
+                workflow: { id: def.id, version: "test" },
+                environment,
+                project: { id: "prj_test", slug: "test" },
+                organization: { id: "org_test", slug: "test" },
+            },
+            triggeredBy: { kind: "api" },
+            runStartedAt: opts.pause.startedAt,
+            tags: [],
+            stepRunner: createStepRunner(opts, events, now),
+        });
+        last = response;
+        const newMutations = response.metadataUpdates.slice(metadataAppliedCount);
+        applyMetadata(metadata, newMutations);
+        metadataAppliedCount = response.metadataUpdates.length;
+        for (const chunk of response.streamChunks) {
+            const bucket = streams[chunk.streamId] ?? [];
+            streams[chunk.streamId] = bucket;
+            bucket.push(chunk);
+        }
+        if (response.status === "completed") {
+            return {
+                status: "completed",
+                output: response.output,
+                steps: stepsFromJournal(journal),
+                events,
+                metadata,
+                compensations: [],
+                streams,
+                invocations: invocationCount,
+            };
+        }
+        if (response.status === "failed") {
+            return {
+                status: "failed",
+                error: {
+                    category: response.error.category,
+                    code: response.error.code,
+                    message: response.error.message,
+                },
+                steps: stepsFromJournal(journal),
+                events,
+                metadata,
+                compensations: [],
+                streams,
+                invocations: invocationCount,
+            };
+        }
+        if (response.status === "cancelled") {
+            return {
+                status: "cancelled",
+                steps: stepsFromJournal(journal),
+                events,
+                metadata,
+                compensations: response.compensations,
+                streams,
+                invocations: invocationCount,
+            };
+        }
+        if (response.status === "compensated" || response.status === "compensation_failed") {
+            return {
+                status: response.status,
+                error: response.error
+                    ? {
+                        category: response.error.category,
+                        code: response.error.code,
+                        message: response.error.message,
+                    }
+                    : undefined,
+                steps: stepsFromJournal(journal),
+                events,
+                metadata,
+                compensations: response.compensations,
+                streams,
+                invocations: invocationCount,
+            };
+        }
+        const stillPending = [...carryover];
+        for (const wp of response.waitpoints) {
+            const resolved = await resolveWaitpoint(wp, opts, now, events, cursors);
+            if (!resolved) {
+                if (opts.pauseOnWait) {
+                    stillPending.push(wp);
+                    continue;
+                }
+                throw new Error(`resume: waitpoint ${wp.clientWaitpointId} (${wp.kind}) has no fixture resolution. ` +
+                    `Provide one via TestOptions.waitForEvent / waitForSignal, or set pauseOnWait.`);
+            }
+            journal.waitpointsResolved[wp.clientWaitpointId] = resolved;
+            events.push({
+                type: `waitpoint.resolved:${wp.kind}`,
+                at: resolved.resolvedAt,
+                data: resolved.payload ?? null,
+            });
+        }
+        carryover = []; // consumed into stillPending
+        if (stillPending.length > 0) {
+            return {
+                status: "waiting",
+                steps: stepsFromJournal(journal),
+                events,
+                metadata,
+                compensations: [],
+                streams,
+                invocations: invocationCount,
+                pause: {
+                    journal,
+                    pendingWaitpoints: stillPending,
+                    startedAt: opts.pause.startedAt,
+                    invocationCount,
+                    metadataAppliedCount,
+                    fixtureCursors: {
+                        event: Object.fromEntries(cursors.event.entries()),
+                        signal: Object.fromEntries(cursors.signal.entries()),
+                    },
+                },
+            };
+        }
+    }
+    throw new Error(`resume: exceeded maxInvocations (${maxInvocations}). Last status: ${last?.status ?? "<none>"}.`);
+}
+function matchWaitpoint(pending, inj) {
+    for (const wp of pending) {
+        if (wp.kind !== inj.kind)
+            continue;
+        if (inj.kind === "EVENT" && wp.meta.eventType === inj.eventType)
+            return wp;
+        if (inj.kind === "SIGNAL" && wp.meta.signalName === inj.name)
+            return wp;
+        if (inj.kind === "MANUAL" && wp.meta.tokenId === inj.tokenId)
+            return wp;
+    }
+    return undefined;
+}
+function injectionKey(inj) {
+    if (inj.kind === "EVENT")
+        return inj.eventType;
+    if (inj.kind === "SIGNAL")
+        return inj.name;
+    return inj.tokenId;
+}
+function cloneJournal(j) {
+    return {
+        stepResults: { ...j.stepResults },
+        waitpointsResolved: { ...j.waitpointsResolved },
+        compensationsRun: { ...j.compensationsRun },
+        metadataState: { ...j.metadataState },
+        streamsCompleted: { ...j.streamsCompleted },
+    };
+}
+function createStepRunner(opts, events, now) {
+    return async (args) => {
+        const startedAt = now();
+        const mock = opts.steps?.[args.stepId];
+        try {
+            const output = mock ? await mock(args.stepCtx) : await args.fn(args.stepCtx);
+            const finishedAt = now();
+            events.push({ type: "step.ok", at: finishedAt, data: { stepId: args.stepId, output } });
+            return {
+                attempt: args.attempt,
+                status: "ok",
+                output,
+                startedAt,
+                finishedAt,
+            };
+        }
+        catch (err) {
+            const finishedAt = now();
+            const e = err;
+            const code = err.code ?? "UNKNOWN";
+            events.push({
+                type: "step.err",
+                at: finishedAt,
+                data: { stepId: args.stepId, message: e.message, code },
+            });
+            const retryAfter = err.retryAfter;
+            return {
+                attempt: args.attempt,
+                status: "err",
+                error: {
+                    category: "USER_ERROR",
+                    code,
+                    message: e.message,
+                    name: e.name,
+                    stack: e.stack,
+                    data: retryAfter !== undefined ? { retryAfter } : undefined,
+                },
+                startedAt,
+                finishedAt,
+            };
+        }
+    };
+}
+async function resolveWaitpoint(wp, opts, now, parentEvents, cursors) {
+    const at = now();
+    if (wp.kind === "DATETIME") {
+        return { kind: "DATETIME", resolvedAt: at, source: "replay" };
+    }
+    if (wp.kind === "EVENT") {
+        const eventType = wp.meta.eventType;
+        const isIter = wp.meta.iter === true;
+        const fixture = opts.waitForEvent?.[eventType];
+        if (fixture === undefined)
+            return null;
+        if (isIter) {
+            return resolveIterableFixture(fixture, cursors.event, eventType, at, "EVENT", `evt_test_${eventType}`);
+        }
+        const payload = Array.isArray(fixture) ? fixture[0] : fixture;
+        return {
+            kind: "EVENT",
+            resolvedAt: at,
+            matchedEventId: `evt_test_${eventType}`,
+            payload,
+            source: "live",
+        };
+    }
+    if (wp.kind === "SIGNAL") {
+        const name = wp.meta.signalName;
+        const isIter = wp.meta.iter === true;
+        const fixture = opts.waitForSignal?.[name];
+        if (fixture === undefined)
+            return null;
+        if (isIter) {
+            return resolveIterableFixture(fixture, cursors.signal, name, at, "SIGNAL");
+        }
+        return { kind: "SIGNAL", resolvedAt: at, payload: fixture, source: "live" };
+    }
+    if (wp.kind === "MANUAL") {
+        const tokenId = wp.meta.tokenId;
+        const fixture = opts.waitForToken?.[tokenId];
+        if (fixture === undefined)
+            return null;
+        return { kind: "MANUAL", resolvedAt: at, payload: fixture, source: "live" };
+    }
+    if (wp.kind === "RUN") {
+        const childWorkflowId = wp.meta.childWorkflowId;
+        const childInput = wp.meta.childInput;
+        const detach = wp.meta.detach === true;
+        // Allow test-level override: `invoke: { [childId]: value | (input) => value }`.
+        const override = opts.invoke?.[childWorkflowId];
+        if (override !== undefined) {
+            const payload = typeof override === "function"
+                ? await override(childInput)
+                : override;
+            parentEvents.push({
+                type: "child.resolved-from-fixture",
+                at: now(),
+                data: { childWorkflowId, payload, detach },
+            });
+            return {
+                kind: "RUN",
+                resolvedAt: now(),
+                payload: detach ? undefined : payload,
+                source: "replay",
+            };
+        }
+        // Otherwise run the child workflow in-process.
+        const child = getWorkflow(childWorkflowId);
+        if (!child) {
+            throw new Error(`test harness: ctx.invoke target "${childWorkflowId}" is not registered. ` +
+                `Import the child workflow module, or provide a stub via TestOptions.invoke.`);
+        }
+        parentEvents.push({
+            type: "child.started",
+            at: now(),
+            data: { childWorkflowId, input: childInput },
+        });
+        const childResult = await runWorkflowForTest(child, childInput, {
+            steps: opts.steps,
+            waitForEvent: opts.waitForEvent,
+            waitForSignal: opts.waitForSignal,
+            waitForToken: opts.waitForToken,
+            invoke: opts.invoke,
+            env: opts.env,
+            environment: opts.environment,
+            now: opts.now,
+            random: opts.random,
+            maxInvocations: opts.maxInvocations,
+            pauseOnWait: detach || opts.pauseOnWait,
+        });
+        parentEvents.push({
+            type: "child.finished",
+            at: now(),
+            data: { childWorkflowId, status: childResult.status, output: childResult.output, detach },
+        });
+        if (detach) {
+            return { kind: "RUN", resolvedAt: now(), payload: undefined, source: "replay" };
+        }
+        if (childResult.status === "completed") {
+            return { kind: "RUN", resolvedAt: now(), payload: childResult.output, source: "replay" };
+        }
+        // Child failed / cancelled / compensated with error / compensation_failed.
+        const err = childResult.error ?? {
+            category: "USER_ERROR",
+            code: "CHILD_RUN_ENDED",
+            message: `child run ended with status ${childResult.status}`,
+        };
+        return {
+            kind: "RUN",
+            resolvedAt: now(),
+            source: "replay",
+            error: err,
+        };
+    }
+    return null;
+}
+const STREAM_END_MARKER = { __voyantStreamEnd: true };
+function resolveIterableFixture(fixture, cursors, key, at, kind, matchedEventId) {
+    const array = Array.isArray(fixture) ? fixture : [fixture];
+    const idx = cursors.get(key) ?? 0;
+    cursors.set(key, idx + 1);
+    if (idx >= array.length) {
+        // Stream is exhausted — signal the tenant-side iterator to terminate.
+        return {
+            kind,
+            resolvedAt: at,
+            payload: STREAM_END_MARKER,
+            source: "replay",
+            matchedEventId,
+        };
+    }
+    return {
+        kind,
+        resolvedAt: at,
+        payload: array[idx],
+        source: "live",
+        matchedEventId,
+    };
+}
+function applyMetadata(state, updates) {
+    for (const u of updates) {
+        switch (u.op) {
+            case "set":
+                state[u.key] = u.value;
+                break;
+            case "increment": {
+                const cur = typeof state[u.key] === "number" ? state[u.key] : 0;
+                state[u.key] = cur + (u.value ?? 1);
+                break;
+            }
+            case "append": {
+                const cur = Array.isArray(state[u.key]) ? state[u.key] : [];
+                state[u.key] = [...cur, u.value];
+                break;
+            }
+            case "remove":
+                delete state[u.key];
+                break;
+        }
+    }
+}
+function stepsFromJournal(j) {
+    return Object.entries(j.stepResults).map(([id, entry]) => ({
+        id,
+        status: entry.status,
+        duration: entry.finishedAt - entry.startedAt,
+        output: entry.output,
+    }));
+}