# 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.

*Canonical: https://makerkit.dev/docs/void-cloudflare/outbox/testing*

---

## 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`:

```ts
// 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:

```ts
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:

```ts
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](./schedules#locally)).

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.
