Testing Jobs

Test an outbox job end to end on the in-memory test database with runUntilIdle, test retries with a test clock, and run jobs locally.

A Job, End to End

Run the real outbox on the app's in-memory test database (PGlite with every migration, outbox schema included). Enqueue as your code does, then run everything that's due with runUntilIdle:

// apps/web/jobs/__tests__/welcome-email.job.test.ts
import { createOutbox } from '@makerkit/workers-outbox';
import { runUntilIdle } from '@makerkit/workers-outbox/testing';
import { sql } from 'drizzle-orm';
import { expect, it, vi } from 'vite-plus/test';
import { createAppTestDatabase, outboxTestConnect } from '#/db/test-database.ts';
import { welcomeEmail } from '#/jobs/welcome-email.job.ts';
const sent = vi.hoisted(() => [] as string[]);
vi.mock('#/lib/welcome-email.server.ts', () => ({
sendWelcomeEmail: async ({ userId }: { userId: string }) => {
sent.push(userId);
return { rateLimited: false };
},
}));
it('sends the welcome email once the sign-up commits', async () => {
const db = await createAppTestDatabase();
const outbox = createOutbox({ jobs: [welcomeEmail], connect: outboxTestConnect(db) });
await outbox.transaction(db, (_tx, enqueue) =>
enqueue(welcomeEmail, { payload: { userId: 'u1' }, dedupeKey: 'welcome:u1' }),
);
await expect(runUntilIdle(outbox)).resolves.toMatchObject({ succeeded: 1 });
expect(sent).toEqual(['u1']);
});
it('sends nothing when the sign-up rolls back', async () => {
const db = await createAppTestDatabase();
const outbox = createOutbox({ jobs: [welcomeEmail], connect: outboxTestConnect(db) });
const signUp = outbox.transaction(db, async (_tx, enqueue) => {
await enqueue(welcomeEmail, { payload: { userId: 'u2' }, dedupeKey: 'welcome:u2' });
throw new Error('sign-up failed');
});
await expect(signUp).rejects.toThrow('sign-up failed');
const jobs = await db.execute(sql`SELECT 1 FROM outbox.job WHERE dedupe_key = 'welcome:u2'`);
expect(jobs.rows).toHaveLength(0);
});
  • createAppTestDatabase() and outboxTestConnect(db) come from apps/web/db/test-database.ts. PGlite is one connection, so it can't reproduce two workers racing; the package's own tests cover that on real Postgres.
  • Mock the services the handler calls, not the outbox.
  • Tests live next to their subject, outside queues/, crons/, routes/ and middleware/ (Void would load them as code).

To test code that enqueues through getOutbox() (a page action, a service), point the outbox at the test database and assert on the outbox.job row it leaves:

vi.mock('void/db', async () => (await import('#/db/test-database.ts')).testDatabase());
vi.mock('@makerkit/workers-outbox/pg', async () => (await import('#/db/test-database.ts')).testOutboxConnector());
// a placeholder DATABASE_URL and no QUEUE_OUTBOX (jobs wait in the table); pass your own keys: testEnv({ SITE_URL: … })
vi.mock('void/env', async () => (await import('#/db/test-database.ts')).testEnv());

apps/web/lib/__tests__/outbox.server.test.ts is a working example. To run the jobs it enqueued, use runUntilIdle(getOutbox()) (re-exported by @kit/outbox/testing, with deliverNudges to hand a test queue's nudges to handleQueue). createAppTestDatabase() runs every migration, so create it once per file (beforeAll), as apps/web/db/__tests__/outbox.test.ts does.

Retries and Delays

Without a clock, runUntilIdle runs only what is due now. Give the outbox a test clock and it skips ahead to each retry or delayed job:

import { createTestClock, runUntilIdle } from '@makerkit/workers-outbox/testing';
const clock = createTestClock();
const outbox = createOutbox({ jobs: [syncOrganization], connect: outboxTestConnect(db), clock });
// … enqueue, with a handler that fails twice, then succeeds
await expect(runUntilIdle(outbox, { clock, db })).resolves.toMatchObject({ retrying: 2, succeeded: 1 });

runUntilIdle throws after 100 rounds (maxRounds), so a job that retries forever fails the test instead of hanging it.

Locally

In vp dev, a committed job's nudge reaches the local queue and the consumer runs it within a few seconds (Void batches queue messages for up to 5). To run the sweep or a schedule, send POST /__void/scheduled with the dev token Void prints at start-up (Schedules).

Reset the local database with pnpm db:reset or pnpm db:seed, never plain void db reset / void db seed: Void clears the public schema only, and the leftover outbox schema makes the migrations fail.