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.tsimport { 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()andoutboxTestConnect(db)come fromapps/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/andmiddleware/(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 succeedsawait 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.