Recipe and tips to create custom service bindings (with vitest integration)

[benjavicente]

Related to my closed issue #6757 about "reading files" inside vitest using R2.
And maybe to the question service bindings: How does one mock a service binding?

In tests, it might be useful to use an API that are non-compatible with the worked runtime. For example, reading files (with node:fs) containing plain emails or requests, which can be used to test worker handlers. I found that this can be archived with a serviveBinding (link to docs, and the Wrapped Bindings Example):

// vitest.config.mts
import { defineWorkersConfig } from '@cloudflare/vitest-pool-workers/config';
import { readFileSync } from 'node:fs';

export default defineWorkersConfig({
	test: {
		poolOptions: {
			workers: {
				wrangler: { configPath: './wrangler.toml' },
				miniflare: {
					serviceBindings: {
						async bindingRunningInNode(request: Request) {
							const url = new URL(request.url);
							const path = url.pathname.slice(1);
							return new Response(readFileSync(path, 'utf8'));
						},
					},
				},
			},
		},
	},
});

// test/index.spec.ts
import { env } from 'cloudflare:test';
import { it, expect } from 'vitest';

it('Reads local files with serviveBinding', async () => {
	const response = await env.bindingRunningInNode.fetch(new Request('http://localhost/package.json'));
	expect(response).toBeDefined();
	expect(response.status).toBe(200);
	const content = (await response.json()) as { devDependencies: Record<string, string> };
	expect(content.devDependencies).toHaveProperty('wrangler');
});

declare module 'cloudflare:test' {
	interface ProvidedEnv {
		bindingRunningInNode: {
			fetch(request: Request): Promise<Response>;
		};
	}
}

---

Are there guides or tips to this type of configuration/tricks? I could not find documentation or discussions about something like this (custom or mock of service bindings).

For example:

• is it possible to create a service binding without the Request→Response interface?
• are there patterns to work with isolation (per test) on the custom binding?

My use case is testing the email handler, creating a binding with a path-to-eml-file→EmailMessage interface 🤔