Testing
Test Models and your Worker against a real D1 database with Vitest and Miniflare.
At a glance
| To | Write |
|---|---|
| get a real D1 database in Node | Miniflare’s getD1Database, with your migrations applied |
| run a Model’s code in a test | withDatabase(connect(database.binding), async () => { … }) |
| call your Worker in a test | withDatabase(…, () => worker.fetch(request)) |
| query a database you hold | connect(database.binding).model(User) |
The Model
The tests below check this Model and Worker, with the users table its migration creates:
import { ApplicationRecord } from "./application-record";
export class User extends ApplicationRecord {
static {
this.beforeValidation((user) => {
user.email = user.email.toLowerCase();
});
}
}import { User } from "./models/user";
// The app's Worker: here, one route that lists the users' emails.
export default {
async fetch() {
return Response.json(await User.order({ email: "asc" }).pluck("email"));
},
} satisfies ExportedHandler<Env>;// Generated by `active-record schema` from migrations/ — don't edit.
// schema: ae4437c2fc95
import { defineSchema, type TableAttributes } from "@forestfuture/active-record";
import { d1 } from "@forestfuture/active-record/d1";
/** users — last changed by 0001_create_users.sql */
export const users = {
id: { type: "string", null: false, generateId: true },
email: { type: "string", null: false },
} as const;
/** The database's adapter and binding, its tables (with their primary keys), and the Models built on them. */
export const schema = defineSchema({
adapter: d1({ binding: "DB" }),
tables: {
users: { attributes: users, primaryKey: "id" },
},
models: { User: "users" },
});
declare module "../models/user" {
interface User extends TableAttributes<typeof users, (typeof User)["attributes"]> {}
}CREATE TABLE users (
id TEXT PRIMARY KEY NOT NULL,
email TEXT NOT NULL
);CREATE TABLE users (
id UUID PRIMARY KEY,
email TEXT NOT NULL
);Installing
Miniflare runs Cloudflare’s runtime, D1 included, inside Node:
npm install --save-dev vitest miniflare@4
Creating a test database
Start Miniflare with a D1 database, and apply a folder of migrations to it, in order:
import { readdirSync, readFileSync } from "node:fs";
import { Miniflare } from "miniflare";
export async function testDatabase(folder = "migrations") {
const mf = new Miniflare({ modules: true, script: "export default {}", d1Databases: ["DB"] });
const binding = await mf.getD1Database("DB");
for (const file of readdirSync(folder).sort()) {
// Each migration's statements, without its comments, applied together.
const statements = readFileSync(`${folder}/${file}`, "utf8")
.replace(/^\s*--.*$/gm, "")
.split(/;\s*$/m)
.map((statement) => statement.trim())
.filter(Boolean);
if (statements.length > 0)
await binding.batch(statements.map((statement) => binding.prepare(statement)));
}
return { binding, dispose: () => mf.dispose() };
}
Testing Models
Outside a Worker there’s no binding, so run the test’s code inside withDatabase. This checks that User saves emails in lowercase:
import { withDatabase } from "@forestfuture/active-record";
import { connect } from "@forestfuture/active-record/d1";
import { afterAll, beforeAll, expect, test } from "vitest";
import { User } from "../src/models/user";
import { testDatabase } from "./d1";
let database: Awaited<ReturnType<typeof testDatabase>>;
beforeAll(async () => (database = await testDatabase()));
afterAll(() => database.dispose());
test("emails are saved in lowercase", async () => {
await withDatabase(connect(database.binding), async () => {
const user = await User.create({ email: "Jane@Example.com" });
expect((await User.find(user.id)).email).toBe("jane@example.com");
});
});
Outside a Worker, the database given to withDatabase serves every Model on its adapter, whatever binding its base class names. For code that takes a database explicitly, pass it one: connect(database.binding).model(User).
Testing your Worker
Call your Worker’s fetch handler inside withDatabase too, and its queries use the test’s database. This calls the Worker in src/index.ts:
import { withDatabase } from "@forestfuture/active-record";
import { connect } from "@forestfuture/active-record/d1";
import { afterAll, beforeAll, expect, test } from "vitest";
import worker from "../src/index";
import { testDatabase } from "./d1";
let database: Awaited<ReturnType<typeof testDatabase>>;
beforeAll(async () => (database = await testDatabase()));
afterAll(() => database.dispose());
test("GET lists users", async () => {
const response = await withDatabase(connect(database.binding), () =>
worker.fetch(new Request("https://example.com/")),
);
expect(response.status).toBe(200);
});
Each test file gets its own database.