Test APIs

env: import(“cloudflare:test”).ProvidedEnv

• Exposes the env object for use as the second argument passed to ES modules format exported handlers. This provides access to bindings that you have defined in your Vitest configuration file.

  
  

  To configure the type of this value, use an ambient module type:

SELF: Fetcher

• Service binding to the default export defined in the main Worker. Use this to write integration tests against your Worker. The main Worker runs in the same isolate/context as tests so any global mocks will apply to it too.

  
  

fetchMock: import(“undici”).MockAgent

• Declarative interface for mocking outbound fetch() requests. Deactivated by default and reset before running each test file. Refer to undici’s MockAgent documentation for more information. Note this only mocks fetch() requests for the current test runner Worker. Auxiliary Workers should mock fetch()es using the Miniflare fetchMock/outboundService options. Refer to Configuration for more information.

  
  

createExecutionContext(): ExecutionContext

• Creates an instance of the context object for use as the third argument to ES modules format exported handlers.

waitOnExecutionContext(ctx:ExecutionContext): Promise<void>

• Use this to wait for all Promises passed to ctx.waitUntil() to settle, before running test assertions on any side effects. Only accepts instances of ExecutionContext returned by createExecutionContext().

  
  

createScheduledController(options?:FetcherScheduledOptions): ScheduledController

• Creates an instance of ScheduledController for use as the first argument to modules-format scheduled() exported handlers.

  
  

createMessageBatch(queueName:string, messages:ServiceBindingQueueMessage[]): MessageBatch

• Creates an instance of MessageBatch for use as the first argument to modules-format queue() exported handlers.

getQueueResult(batch:MessageBatch, ctx:ExecutionContext): Promise<FetcherQueueResult>

• Gets the acknowledged/retry state of messages in the MessageBatch, and waits for all ExecutionContext#waitUntil()ed Promises to settle. Only accepts instances of MessageBatch returned by createMessageBatch(), and instances of ExecutionContext returned by createExecutionContext().

  
  

runInDurableObject<O extends DurableObject, R>(stub:DurableObjectStub, callback:(instance: O, state: DurableObjectState) => R | Promise<R>): Promise<R>

• Runs the provided callback inside the Durable Object instance that corresponds to the provided stub.

  
  

  This temporarily replaces your Durable Object’s fetch() handler with callback, then sends a request to it, returning the result. This can be used to call/spy-on Durable Object instance methods or seed/get persisted data. Note this can only be used with stubs pointing to Durable Objects defined in the main Worker.

  
  

runDurableObjectAlarm(stub:DurableObjectStub): Promise<boolean>

• Immediately runs and removes the Durable Object pointed to by stub’s alarm if one is scheduled. Returns true if an alarm ran, and false otherwise. Note this can only be used with stubs pointing to Durable Objects defined in the main Worker.

listDurableObjectIds(namespace:DurableObjectNamespace): Promise<DurableObjectId[]>

• Gets the IDs of all objects that have been created in the namespace. Respects isolatedStorage if enabled, meaning objects created in a different test will not be returned.

  
  

applyD1Migrations(db:D1Database, migrations:D1Migration[], migrationTableName?:string): Promise<void>

• Applies all un-applied D1 migrations stored in the migrations array to database db, recording migrations state in the migrationsTableName table. migrationsTableName defaults to d1_migrations. Call the readD1Migrations() function from the @cloudflare/vitest-pool-workers/config package inside Node.js to get the migrations array. Refer to the D1 recipe for an example project using migrations.