Testing

Flowcraft provides utilities for testing and debugging workflows, including step-by-step execution, event logging, and trace helpers.

createStepper

Creates a stepper for interactive, step-by-step execution of workflows.

Signature

function createStepper<
	TContext extends Record<string, any> = Record<string, any>,
	TDependencies extends RuntimeDependencies = RuntimeDependencies,
>(
	runtime: FlowRuntime<TContext, TDependencies>,
	blueprint: WorkflowBlueprint,
	functionRegistry: Map<string, NodeFunction | NodeClass>,
	initialState?: Partial<TContext>,
): Promise<IWorkflowStepper<TContext>>

Parameters

• runtime: The FlowRuntime instance to use for execution.
• blueprint: The workflow blueprint to execute.
• functionRegistry: A map of node implementations.
• initialState (optional): Initial context state.

Returns

A Promise resolving to an IWorkflowStepper instance with methods for step-by-step control.

Example

import { createStepper } from 'flowcraft/testing'

const stepper = await createStepper(runtime, blueprint, registry)
const result = await stepper.next()

IWorkflowStepper Interface

The IWorkflowStepper interface provides methods for step-by-step workflow execution.

interface IWorkflowStepper<TContext extends Record<string, any>> {
	readonly state: WorkflowState<TContext>
	readonly traverser: GraphTraverser
	next(options?: {
		signal?: AbortSignal
		concurrency?: number
	}): Promise<WorkflowResult<TContext> | null>
	prev(): Promise<WorkflowResult<TContext> | null>
	reset(): void
	isDone(): boolean
}

Methods

• state: The current state of the workflow.
• traverser: The graph traverser instance.
• next(options?): Executes the next batch of ready nodes. Returns the result or null if done.
• prev(): Reverts to the previous state. Returns the result or null if no history.
• reset(): Resets the stepper to initial state.
• isDone(): Checks if the workflow has more steps.

runWithTrace

Executes a workflow and prints a detailed trace on failure or when DEBUG is set.

Signature

function runWithTrace<
	TContext extends Record<string, any> = Record<string, any>,
	TDependencies extends RuntimeDependencies = RuntimeDependencies,
>(
	runtime: IRuntime<TContext, TDependencies>,
	blueprint: WorkflowBlueprint,
	options?: {
		functionRegistry?: Map<string, NodeFunction | NodeClass>
		initialState?: Partial<TContext>
		signal?: AbortSignal
	},
): Promise<WorkflowResult<TContext>>

Parameters

• runtime: The runtime instance.
• blueprint: The workflow blueprint.
• options (optional):
  • functionRegistry: Node implementations.
  • initialState: Initial context.
  • signal: AbortSignal.

Returns

Promise resolving to the workflow result.

Example

import { runWithTrace } from 'flowcraft/testing'

await runWithTrace(runtime, blueprint)

InMemoryEventLogger

An event bus implementation that captures events in memory for testing.

Signature

class InMemoryEventLogger implements IEventBus {
	readonly events: FlowcraftEvent[]
	constructor()
	emit(event: FlowcraftEvent): Promise<void>
	clear(): void
	find<T extends FlowcraftEvent['type']>(
		type: T,
	): Extract<FlowcraftEvent, { type: T }> | undefined
	filter<T extends FlowcraftEvent['type']>(type: T): Extract<FlowcraftEvent, { type: T }>[]
	printLog(title?: string): void
}

Methods

• events: Array of captured events.
• emit(event): Captures the event in the array.
• clear(): Clears all captured events.
• find(type): Finds the first event of the given type.
• filter(type): Filters events by type.
• printLog(title?): Prints a formatted log of all events.

Example

import { InMemoryEventLogger } from 'flowcraft/testing'

const logger = new InMemoryEventLogger()
const runtime = new FlowRuntime({ eventBus: logger })
await runtime.run(blueprint)
const event = logger.find('node:finish')
const retryEvents = logger.filter('node:retry')
logger.printLog('Execution Trace')