Skip to main content

Function: createTestingClient()

createTestingClient<T>(doBindingName, doInstanceNameOrId): T & RpcClientProxy

Defined in: packages/testing/src/create-testing-client.ts:48

Creates a testing-optimized RPC client for Cloudflare Durable Objects.

Environment Requirement: This function can only be used within Cloudflare Workers test environment (vitest with @cloudflare/vitest-pool-workers). It imports from cloudflare:test which is only available in that environment.

This is a convenience wrapper around createRpcClient that automatically:

  • Imports SELF from cloudflare:test
  • Uses HTTP transport (simple and fast for testing)
  • Provides RPC access to DO instance internals

Type Parameters​

T​

T

The type of the Durable Object. Use RpcAccessible to expose protected properties like ctx and env.

Parameters​

doBindingName​

string

The DO binding name from wrangler.jsonc (e.g., 'MY_DO')

doInstanceNameOrId​

string

The DO instance name or ID

Returns​

T & RpcClientProxy

A proxy client that supports both RPC calls and lifecycle management

Remarks​

Internally calls createRpcClient with testing-specific defaults. For production use or when you need full configuration control (custom transports, WebSocket connections, custom headers, etc.), use createRpcClient directly.

Both functions return the same underlying RpcClient instance and support 'await using' for automatic cleanup. The only difference is the level of configuration abstraction.

For test timeouts, use your test framework's timeout features (e.g., Vitest's test.timeout).

Example​

// Testing - simple, opinionated (this function)
await using client = createTestingClient<MyDOType>('MY_DO', 'instance-name');
await client.ctx.storage.put('key', 'value');

// Production - full control (use createRpcClient)
await using client = createRpcClient<MyDOType>({
  doBindingName: 'MY_DO',
  doInstanceNameOrId: 'instance-name',
  transport: 'websocket',
  baseUrl: 'https://api.example.com'
});

Throws​

Will fail to import if used outside vitest-pool-workers environment