← Workers / workers / testing / vitest-integration

Configuration

The Workers Vitest integration provides additional configuration on top of Vitest's usual options using the cloudflareTest() Vite plugin.

An example configuration would be:

import { cloudflareTest } from "@cloudflare/vitest-plugin";
import { defineConfig } from "vitest/config";

export default defineConfig({
	plugins: [
		cloudflareTest({
			wrangler: {
				configPath: "./wrangler.jsonc",
			},
		}),
	],
});

The following APIs are exported from the @cloudflare/vitest-plugin package.

A Vite plugin that configures Vitest to use the Workers integration with the correct module resolution settings, and provides type checking for CloudflareTestOptions. Add this to the plugins array in your Vitest config alongside defineConfig() ↗ from Vitest.

It also accepts an optionally-async function returning options.

import { cloudflareTest } from "@cloudflare/vitest-plugin";
import { defineConfig } from "vitest/config";

export default defineConfig({
	plugins: [
		cloudflareTest({
			// Refer to CloudflareTestOptions...
		}),
	],
});

Exported from @cloudflare/vitest-plugin/config. Creates a Pages ASSETS binding that serves files inside the assetsPath. This is required if you use createPagesEventContext() to test your Pages Functions. Refer to the Pages recipe for a full example.

import path from "node:path";
import { buildPagesASSETSBinding, cloudflareTest } from "@cloudflare/vitest-plugin";
import { defineConfig } from "vitest/config";

export default defineConfig({
	plugins: [
		cloudflareTest(async () => {
			const assetsPath = path.join(__dirname, "public");

			return {
				miniflare: {
					serviceBindings: {
						ASSETS: await buildPagesASSETSBinding(assetsPath),
					},
				},
			};
		}),
	],
});

Exported from @cloudflare/vitest-plugin/config. Reads all D1 migrations stored at migrationsPath and returns them ordered by migration number. Each migration will have its contents split into an array of individual SQL queries. Call the applyD1Migrations() function inside a test or setup file ↗ to apply migrations. Refer to the D1 recipe ↗ for an example project using migrations.

import path from "node:path";
import { cloudflareTest, readD1Migrations } from "@cloudflare/vitest-plugin";
import { defineConfig } from "vitest/config";

export default defineConfig({
	plugins: [
		cloudflareTest(async () => {
			const migrationsPath = path.join(__dirname, "migrations");
			const migrations = await readD1Migrations(migrationsPath);

			return {
				miniflare: {
					// Add a test-only binding for migrations, so we can apply them in a setup file
					bindings: { TEST_MIGRATIONS: migrations },
				},
			};
		}),
	],
	test: {
		setupFiles: ["./test/apply-migrations.ts"],
	},
});

Options passed directly to cloudflareTest().

• main: string optional

  • Entry point to Worker run in the same isolate/context as tests. This option is required to use Durable Objects without an explicit scriptName if classes are defined in the same Worker. This file goes through Vite transforms and can be TypeScript. Note that import module from "<path-to-main>" inside tests gives exactly the same module instance as is used internally for exports and Durable Object bindings. If wrangler.configPath is defined and this option is not, it will be read from the main field in that configuration file.

• miniflare: SourcelessWorkerOptions & { workers?: WorkerOptions\[]; } optional

  • Use this to provide configuration information that is typically stored within the Wrangler configuration file, such as bindings, compatibility dates, and compatibility flags. The WorkerOptions interface is defined here ↗. Use the main option above to configure the entry point, instead of the Miniflare script, scriptPath, or modules options.

    • If no compatibility_date is provided, then the test will use the latest locally available date.

  • If your project makes use of multiple Workers, you can configure auxiliary Workers that run in the same workerd process as your tests and can be bound to. Auxiliary Workers are configured using the workers array, containing regular Miniflare WorkerOptions ↗ objects. Note that unlike the main Worker, auxiliary Workers:

    • Cannot have TypeScript entrypoints. You must compile auxiliary Workers to JavaScript first. You can use the wrangler deploy --dry-run --outdir dist command for this.
    • Use regular Workers module resolution semantics. Refer to the Isolation and concurrency page for more information.
    • Cannot access the cloudflare:test module.
    • Do not require specific compatibility dates or flags.
    • Can be written with the Service Worker syntax.
    • Are not affected by global mocks defined in your tests.

• wrangler: { configPath?: string; environment?: string; } optional

  • Path to Wrangler configuration file to load main, compatibility settings and bindings from. These options will be merged with the miniflare option above, with miniflare values taking precedence. For example, if your Wrangler configuration defined a service binding named SERVICE to a Worker named service, but you included serviceBindings: { SERVICE(request) { return new Response("body"); } } in the miniflare option, all requests to SERVICE in tests would return body. Note configPath accepts both .toml and .json files.

  • The environment option can be used to specify the Wrangler environment to pick up bindings and variables from.

You can pass an async function to cloudflareTest() that receives an inject function. This allows you to define miniflare configuration based on injected values from globalSetup ↗ scripts. Use this if you have a value in your configuration that is dynamically generated and only known at runtime of your tests. For example, a global setup script might start an upstream server on a random port. This port could be provide()d and then inject()ed in the configuration for an external service binding or Hyperdrive. Refer to the Hyperdrive recipe ↗ for an example project using this provide/inject approach.

// env.d.ts
declare module "vitest" {
	interface ProvidedContext {
		port: number;
	}
}

// global-setup.ts
import type { GlobalSetupContext } from "vitest/node";
export default function ({ provide }: GlobalSetupContext) {
	// Runs inside Node.js, could start server here...
	provide("port", 1337);
	return () => {
		/* ...then teardown here */
	};
}

// vitest.config.ts
import { cloudflareTest } from "@cloudflare/vitest-plugin";
import { defineConfig } from "vitest/config";

export default defineConfig({
	plugins: [
		cloudflareTest(({ inject }) => ({
			miniflare: {
				hyperdrives: {
					DATABASE: `postgres://user:[email protected]:${inject("port")}/db`,
				},
			},
		})),
	],
	test: {
		globalSetup: ["./global-setup.ts"],
	},
});

Sourceless WorkerOptions type without script, scriptPath, or modules properties. Refer to the Miniflare WorkerOptions ↗ type for more details.

type SourcelessWorkerOptions = Omit<
	WorkerOptions,
	"script" | "scriptPath" | "modules" | "modulesRoot"
>;