lopata 0.7.0 → 0.8.2

package/src/testing/index.ts

@@ -0,0 +1,288 @@
+import { randomUUIDv7 } from 'bun'
+import { rmSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { SqliteCacheStorage } from '../bindings/cache'
+import type { DurableObjectNamespaceImpl } from '../bindings/durable-object'
+import { ForwardableEmailMessage } from '../bindings/email'
+import { createScheduledController } from '../bindings/scheduled'
+import type { SqliteWorkflowBinding } from '../bindings/workflow'
+import { setGlobalEnv } from '../env'
+import { ExecutionContext, runWithExecutionContext } from '../execution-context'
+import { TestClock } from './clock'
+import { TestDurableObjectNamespace } from './durable-object'
+import { buildTestEnv, configToBindings } from './env-builder'
+import { FetchMock, runWithFetchMock } from './fetch-mock'
+import { setupTestEnv, testCachesRef } from './setup'
+import type { TestEnv, TestEnvOptions, WorkerHandlers, WorkerModule } from './types'
+import { TestWorkflowBinding } from './workflow'
+
+export { TestClock } from './clock'
+export type { Clock } from './clock'
+export type { TestDurableObjectHandle, TestDurableObjectNamespace, TestDurableObjectStorage, TestWebSocket } from './durable-object'
+export { FetchMock } from './fetch-mock'
+export type { FetchCall } from './fetch-mock'
+export type { BindingSpec, TestEnv, TestEnvOptions, WorkerHandlers, WorkerModule } from './types'
+export type { TestWorkflowBinding, TestWorkflowInstance, TestWorkflowRun } from './workflow'
+
+export async function createTestEnv<Env = Record<string, unknown>>(options: TestEnvOptions = {}): Promise<TestEnv<Env>> {
+	// Ensure virtual modules + globals are registered (no-op if preload already ran)
+	setupTestEnv()
+
+	// Resolve clock
+	let clock: TestClock | null = null
+	if (options.clock === true) {
+		clock = new TestClock()
+	} else if (options.clock instanceof TestClock) {
+		clock = options.clock
+	}
+
+	// Create fetch mock (always available, defaults to passthrough)
+	const fetchMock = new FetchMock()
+
+	let mergedBindings = options.bindings
+	let mergedVars = options.vars
+
+	// Load from wrangler config if specified — translate to BindingSpec
+	if (options.wrangler) {
+		const { loadConfig } = await import('../config')
+		const config = await loadConfig(resolve(options.wrangler))
+		const { bindings: configBindings, vars: configVars } = configToBindings(config)
+		// Merge: explicit options.bindings override wrangler-derived bindings
+		mergedBindings = { ...configBindings, ...options.bindings }
+		// Merge: explicit options.vars override wrangler vars
+		mergedVars = { ...configVars, ...options.vars }
+	}
+
+	const { db, env, registry, tmpDirs } = buildTestEnv(mergedBindings, mergedVars, clock ?? undefined)
+
+	// Wire in-memory caches for this test env
+	testCachesRef.current = new SqliteCacheStorage(db, undefined, clock ?? undefined)
+
+	// Resolve worker module
+	let workerModule: Record<string, unknown>
+	let defaultExport: unknown
+	let classBasedExport = false
+
+	if (typeof options.worker === 'string') {
+		workerModule = await import(resolve(options.worker))
+		defaultExport = workerModule.default
+		if (typeof defaultExport === 'function' && defaultExport.prototype) {
+			classBasedExport = typeof defaultExport.prototype.fetch === 'function'
+		}
+	} else if (options.worker && 'default' in options.worker) {
+		// WorkerModule — has a `default` export (class or object) + named exports
+		const mod = options.worker as WorkerModule
+		defaultExport = mod.default
+		workerModule = { ...mod }
+		if (typeof defaultExport === 'function' && defaultExport.prototype) {
+			classBasedExport = typeof defaultExport.prototype.fetch === 'function'
+		}
+	} else if (options.worker) {
+		// Inline handlers object — also expose extra properties (e.g. DO/Workflow classes)
+		// as top-level module exports so wireClassRefs can find them
+		defaultExport = options.worker
+		workerModule = { default: defaultExport, ...options.worker }
+	} else {
+		defaultExport = {}
+		workerModule = { default: defaultExport }
+	}
+
+	// Wire DO/Workflow classes
+	for (const entry of registry.durableObjects) {
+		const cls = workerModule[entry.className]
+		if (!cls) throw new Error(`Durable Object class "${entry.className}" not exported from worker module`)
+		entry.namespace._setClass(cls as any, env)
+	}
+
+	for (const entry of registry.workflows) {
+		const cls = workerModule[entry.className]
+		if (!cls) throw new Error(`Workflow class "${entry.className}" not exported from worker module`)
+		entry.binding._setClass(cls as any, env)
+		entry.binding.resumeInterrupted()
+	}
+
+	// Wire service bindings — self-referencing
+	for (const entry of registry.serviceBindings) {
+		const wire = entry.proxy._wire as ((resolver: () => { workerModule: Record<string, unknown>; env: Record<string, unknown> }) => void) | undefined
+		if (wire) {
+			wire(() => ({ workerModule, env }))
+		}
+	}
+
+	// Set globalEnv so `import { env } from 'cloudflare:workers'` works
+	setGlobalEnv(env)
+
+	// --- Handler dispatch helpers ---
+
+	function getHandler(name: string): ((...args: unknown[]) => Promise<unknown>) | undefined {
+		if (classBasedExport) {
+			if (typeof (defaultExport as any).prototype[name] === 'function') {
+				return (...args: unknown[]) => {
+					const ctx = new ExecutionContext()
+					const instance = new (defaultExport as new(ctx: ExecutionContext, env: unknown) => Record<string, unknown>)(ctx, env)
+					return (instance[name] as (...a: unknown[]) => Promise<unknown>)(...args)
+				}
+			}
+			return undefined
+		}
+		const method = (defaultExport as Record<string, unknown>)?.[name]
+		return typeof method === 'function' ? method.bind(defaultExport) : undefined
+	}
+
+	async function fetchHandler(input: string | Request, init?: RequestInit): Promise<Response> {
+		let request: Request
+		if (typeof input === 'string') {
+			const url = input.startsWith('/') ? `http://localhost${input}` : input
+			request = new Request(url, init)
+		} else {
+			request = init ? new Request(input, init) : input
+		}
+
+		const ctx = new ExecutionContext()
+		return runWithExecutionContext(ctx, () =>
+			runWithFetchMock(fetchMock, async () => {
+				let response: Response
+				if (classBasedExport) {
+					const instance = new (defaultExport as new(ctx: ExecutionContext, env: unknown) => Record<string, unknown>)(ctx, env)
+					response = await (instance.fetch as (r: Request) => Promise<Response>)(request)
+				} else {
+					const handler = (defaultExport as Record<string, unknown>)?.fetch
+					if (typeof handler !== 'function') {
+						throw new Error('No fetch handler found')
+					}
+					response = await (handler as (r: Request, e: unknown, c: ExecutionContext) => Promise<Response>)(request, env, ctx)
+				}
+				await ctx._awaitAll()
+				return response
+			}))
+	}
+
+	async function queueHandler(queueName: string, messages: { body: unknown; contentType?: string }[]): Promise<void> {
+		const handler = getHandler('queue')
+		if (!handler) throw new Error('No queue handler found')
+
+		const builtMessages = messages.map((msg, i) => ({
+			id: randomUUIDv7(),
+			timestamp: new Date(),
+			body: msg.body,
+			attempts: 1,
+			ack() {},
+			retry(_options?: { delaySeconds?: number }) {},
+		}))
+
+		const batch = {
+			queue: queueName,
+			messages: builtMessages,
+			ackAll() {},
+			retryAll(_options?: { delaySeconds?: number }) {},
+		}
+
+		const ctx = new ExecutionContext()
+		await runWithExecutionContext(ctx, () =>
+			runWithFetchMock(fetchMock, async () => {
+				await handler(batch, env, ctx)
+				await ctx._awaitAll()
+			}))
+	}
+
+	async function scheduledHandler(opts?: { cron?: string; scheduledTime?: number }): Promise<void> {
+		const handler = getHandler('scheduled')
+		if (!handler) throw new Error('No scheduled handler found')
+
+		const controller = createScheduledController(opts?.cron ?? '* * * * *', opts?.scheduledTime ?? Date.now())
+		const ctx = new ExecutionContext()
+		await runWithExecutionContext(ctx, () =>
+			runWithFetchMock(fetchMock, async () => {
+				await handler(controller, env, ctx)
+				await ctx._awaitAll()
+			}))
+	}
+
+	async function emailHandler(opts: { from: string; to: string; raw: Uint8Array | string }): Promise<void> {
+		const handler = getHandler('email')
+		if (!handler) throw new Error('No email handler found')
+
+		const rawBytes = typeof opts.raw === 'string' ? new TextEncoder().encode(opts.raw) : opts.raw
+		const messageId = randomUUIDv7()
+		db.run(
+			"INSERT INTO email_messages (id, binding, from_addr, to_addr, raw, raw_size, status, created_at) VALUES (?, ?, ?, ?, ?, ?, 'received', ?)",
+			[messageId, '_incoming', opts.from, opts.to, rawBytes, rawBytes.byteLength, Date.now()],
+		)
+
+		const message = new ForwardableEmailMessage(db, messageId, opts.from, opts.to, rawBytes)
+		const ctx = new ExecutionContext()
+		await runWithExecutionContext(ctx, () =>
+			runWithFetchMock(fetchMock, async () => {
+				await handler(message, env, ctx)
+				await ctx._awaitAll()
+			}))
+	}
+
+	// --- Test helper factories ---
+
+	const testWorkflows: TestWorkflowBinding[] = []
+	const testDOs: TestDurableObjectNamespace[] = []
+
+	function workflowHelper(bindingName: string): TestWorkflowBinding {
+		const entry = registry.workflows.find(e => e.bindingName === bindingName)
+		if (!entry) throw new Error(`Workflow binding "${bindingName}" not found. Available: ${registry.workflows.map(e => e.bindingName).join(', ')}`)
+		const tw = new TestWorkflowBinding(entry.binding as SqliteWorkflowBinding, db)
+		testWorkflows.push(tw)
+		return tw
+	}
+
+	function durableObjectHelper(bindingName: string): TestDurableObjectNamespace {
+		const entry = registry.durableObjects.find(e => e.bindingName === bindingName)
+		if (!entry) {
+			throw new Error(`Durable Object binding "${bindingName}" not found. Available: ${registry.durableObjects.map(e => e.bindingName).join(', ')}`)
+		}
+		const td = new TestDurableObjectNamespace(entry.namespace as DurableObjectNamespaceImpl)
+		testDOs.push(td)
+		return td
+	}
+
+	async function advanceTime(ms: number): Promise<void> {
+		if (!clock) throw new Error('advanceTime requires clock: true in createTestEnv options')
+		clock.advance(ms)
+		// Fire ready DO alarms
+		for (const entry of registry.durableObjects) {
+			await Promise.all(entry.namespace._fireReadyAlarms())
+		}
+	}
+
+	function dispose(): void {
+		for (const tw of testWorkflows) tw.dispose()
+		for (const td of testDOs) td.dispose()
+		for (const entry of registry.durableObjects) {
+			entry.namespace.destroy()
+		}
+		for (const entry of registry.workflows) {
+			entry.binding.abortRunning()
+		}
+		db.close()
+		for (const dir of tmpDirs) {
+			try {
+				rmSync(dir, { recursive: true, force: true })
+			} catch {}
+		}
+		// Clean up global state
+		setGlobalEnv({})
+		testCachesRef.current = null
+		fetchMock.reset()
+	}
+
+	return {
+		env: env as Env,
+		db,
+		fetch: fetchHandler,
+		queue: queueHandler,
+		scheduled: scheduledHandler,
+		email: emailHandler,
+		workflow: workflowHelper as TestEnv<Env>['workflow'],
+		durableObject: durableObjectHelper as TestEnv<Env>['durableObject'],
+		clock,
+		fetchMock,
+		advanceTime,
+		dispose,
+	}
+}

package/src/testing/setup.ts

@@ -0,0 +1,68 @@
+import { plugin } from 'bun'
+import type { SqliteCacheStorage } from '../bindings/cache'
+import { setupCloudflareGlobals } from '../setup-globals'
+import { registerVirtualModules } from '../virtual-modules'
+import { getActiveFetchMock } from './fetch-mock'
+
+/**
+ * Mutable ref for per-test caches instance.
+ * Set by `createTestEnv()`, cleared by `dispose()`.
+ * The `caches` global getter reads from this ref.
+ */
+export const testCachesRef: { current: SqliteCacheStorage | null } = { current: null }
+
+let initialized = false
+
+/**
+ * Sets up the test environment:
+ * - Registers cloudflare:* virtual modules via Bun.plugin
+ * - Sets up global Cloudflare APIs (HTMLRewriter, WebSocketPair, crypto, etc.)
+ * - Overrides `caches` global to use in-memory storage from testCachesRef
+ * - Overrides `globalThis.fetch` to support ALS-scoped fetch mocking
+ *
+ * Idempotent — safe to call multiple times.
+ */
+export function setupTestEnv() {
+	if (initialized) return
+	initialized = true
+
+	setupCloudflareGlobals()
+
+	// Override caches to use the per-test in-memory ref instead of filesystem
+	Object.defineProperty(globalThis, 'caches', {
+		get: () => {
+			if (!testCachesRef.current) {
+				throw new Error('caches is not available — call createTestEnv() first')
+			}
+			return testCachesRef.current
+		},
+		configurable: true,
+	})
+
+	// Override globalThis.fetch to support ALS-scoped fetch mocking
+	const _originalFetch = globalThis.fetch
+	const mockedFetch = async (input: string | Request | URL, init?: RequestInit) => {
+		const mock = getActiveFetchMock()
+		if (!mock) return _originalFetch(input, init)
+
+		const request = new Request(input as any, init)
+		const result = await mock._handle(request)
+		if (result) return result.response
+
+		// Passthrough — call original fetch and record it
+		const response = await _originalFetch(input, init)
+		mock._recordPassthrough(new Request(input as any, init), response)
+		return response
+	}
+	globalThis.fetch = mockedFetch as typeof globalThis.fetch
+
+	plugin({
+		name: 'cloudflare-workers-test-shim',
+		setup(build) {
+			registerVirtualModules(build)
+		},
+	})
+}
+
+// Auto-run on import (preload behavior)
+setupTestEnv()

package/src/testing/types.ts

@@ -0,0 +1,68 @@
+import type { Database } from 'bun:sqlite'
+import type { TestClock } from './clock'
+import type { TestDurableObjectNamespace } from './durable-object'
+import type { FetchMock } from './fetch-mock'
+import type { TestWorkflowBinding } from './workflow'
+
+export interface WorkerHandlers {
+	fetch?(request: Request, env: Record<string, unknown>, ctx: unknown): Promise<Response> | Response
+	queue?(batch: unknown, env: Record<string, unknown>, ctx: unknown): Promise<void> | void
+	scheduled?(controller: unknown, env: Record<string, unknown>, ctx: unknown): Promise<void> | void
+	email?(message: unknown, env: Record<string, unknown>, ctx: unknown): Promise<void> | void
+	[key: string]: unknown
+}
+
+/** Worker module with a default export (class or object) plus named exports (DO/Workflow classes) */
+export interface WorkerModule {
+	default: (new(ctx: unknown, env: unknown) => Record<string, unknown>) | WorkerHandlers
+	[key: string]: unknown
+}
+
+export interface TestEnvOptions {
+	/** Worker: file path (string), inline handlers object, or module with default + named exports */
+	worker?: string | WorkerHandlers | WorkerModule
+	/** Binding declarations — keys become binding names in env */
+	bindings?: Record<string, BindingSpec>
+	/** Path to wrangler.toml/.json/.jsonc to load bindings from */
+	wrangler?: string
+	/** Plain string variables to add to env */
+	vars?: Record<string, string>
+	/** Enable test clock for time control. Pass true to create a new TestClock, or pass a TestClock instance. */
+	clock?: boolean | TestClock
+}
+
+export type BindingSpec =
+	| 'kv'
+	| 'r2'
+	| 'd1'
+	| 'queue'
+	| { type: 'durable-object'; className: string }
+	| { type: 'workflow'; className: string }
+	| { type: 'service'; service: string; entrypoint?: string }
+
+export interface TestEnv<Env = Record<string, unknown>> {
+	/** The built env object with all bindings */
+	env: Env
+	/** The shared in-memory database used by bindings */
+	db: Database
+	/** Dispatch a fetch request to the worker */
+	fetch(input: string | Request, init?: RequestInit): Promise<Response>
+	/** Dispatch a queue batch to the worker's queue handler */
+	queue(queueName: string, messages: { body: unknown; contentType?: string }[]): Promise<void>
+	/** Dispatch a scheduled event to the worker */
+	scheduled(options?: { cron?: string; scheduledTime?: number }): Promise<void>
+	/** Dispatch an email event to the worker */
+	email(options: { from: string; to: string; raw: Uint8Array | string }): Promise<void>
+	/** Get a test-friendly workflow binding wrapper */
+	workflow(bindingName: string & keyof Env): TestWorkflowBinding
+	/** Get a test-friendly durable object namespace wrapper */
+	durableObject(bindingName: string & keyof Env): TestDurableObjectNamespace
+	/** Test clock for time control (null if not enabled) */
+	clock: TestClock | null
+	/** Fetch mock for intercepting outgoing HTTP requests */
+	fetchMock: FetchMock
+	/** Advance time and fire ready DO alarms */
+	advanceTime(ms: number): Promise<void>
+	/** Cleanup: close DB, remove temp dirs, destroy DO namespaces */
+	dispose(): void
+}