Testing Blaze Workers with Vitest and Mock Environments

Test Blaze Workers without a real Cloudflare runtime. Pass synthetic Request objects and a mock Env to app.fetch() and assert on the Response.

app.fetch(req, env, ctx) is your single test seam. Pass a synthetic Request, a plain mock env object, and a mock ExecutionContext — no Worker runtime, no wrangler dev, no live Cloudflare account needed. Because Blaze enriches the standard Request internally, your tests stay clean and fast.

Unit testing with Vitest

Vitest runs in a standard Node.js environment. Build up a mockEnv with vi.fn() stubs for each binding your handler touches, then call app.fetch() and assert on the Response.

Use mockCtx.waitUntil as a vi.fn() to assert on background tasks. After calling app.fetch(), inspect mockCtx.waitUntil.mock.calls to verify that analytics writes, cache warming, or other fire-and-forget work was scheduled — without actually running the deferred work.

Integration testing with @cloudflare/vitest-pool-workers

For tests that need real Cloudflare APIs — Workers KV, D1, R2 — use the @cloudflare/vitest-pool-workers pool. It runs your tests inside an actual Workers runtime via Miniflare, so bindings behave exactly as they do in production.

Mocking Cloudflare bindings

Different bindings need different mock shapes. Here are the patterns for the most common ones:

KV

const mockKV: Partial<KVNamespace> = {
  get: vi.fn().mockImplementation(async (key: string) => {
    const store: Record<string, string> = {
      'user:1': JSON.stringify({ id: '1', name: 'Alice' }),
    };
    return store[key] ?? null;
  }),
  put: vi.fn().mockResolvedValue(undefined),
  delete: vi.fn().mockResolvedValue(undefined),
  list: vi.fn().mockResolvedValue({ keys: [], list_complete: true, cursor: '' }),
};

const mockEnv = { SESSION_KV: mockKV };

D1

// Mock the prepare → bind → first/all/run chain
const mockD1: Partial<D1Database> = {
  prepare: vi.fn().mockReturnValue({
    bind: vi.fn().mockReturnValue({
      first:  vi.fn().mockResolvedValue({ id: '1', name: 'Alice' }),
      all:    vi.fn().mockResolvedValue({ results: [{ id: '1' }], success: true }),
      run:    vi.fn().mockResolvedValue({ success: true, meta: {} }),
    }),
  }),
  batch: vi.fn().mockResolvedValue([{ results: [], success: true }]),
};

const mockEnv = { DB: mockD1 };

R2

const mockR2: Partial<R2Bucket> = {
  get: vi.fn().mockImplementation(async (key: string) => {
    if (key === 'exists.txt') {
      return {
        key,
        arrayBuffer: () => Promise.resolve(new ArrayBuffer(4)),
        httpMetadata: { contentType: 'text/plain' },
        httpEtag: '"abc123"',
      };
    }
    return null; // 404 path
  }),
  put: vi.fn().mockResolvedValue({ key: 'new-file.txt', etag: '"def456"' }),
  delete: vi.fn().mockResolvedValue(undefined),
};

const mockEnv = { ASSETS: mockR2 };

Queue

const mockQueue: Partial<Queue> = {
  send:      vi.fn().mockResolvedValue(undefined),
  sendBatch: vi.fn().mockResolvedValue(undefined),
};

const mockEnv = { JOBS: mockQueue };

// Assert a message was enqueued
it('enqueues a job on POST /jobs', async () => {
  const req = new Request('http://localhost/jobs', {
    method: 'POST',
    body: JSON.stringify({ type: 'email', to: '[e-mail]' }),
    headers: { 'Content-Type': 'application/json' },
  });

  const res = await app.fetch(req, mockEnv, mockCtx);
  expect(res.status).toBe(202);
  expect(mockQueue.send).toHaveBeenCalledWith({
    type: 'email',
    to: '[e-mail]',
  });
});

Testing middleware

Test auth middleware by controlling the Authorization header. Pass the header to simulate an authenticated request; omit it (or supply an invalid token) to test the rejection path.

test/auth.test.ts

import { describe, it, expect, vi } from 'vitest';
import app from '../src/index';

const mockEnv = {
  JWT_SECRET: 'test-secret',
  DB: { /* ... */ },
};

const mockCtx = { waitUntil: vi.fn(), passThroughOnException: vi.fn() };

describe('requireAuth middleware', () => {
  it('allows requests with a valid Bearer token', async () => {
    const req = new Request('http://localhost/api/profile', {
      headers: { Authorization: 'Bearer valid-token-for-testing' },
    });

    const res = await app.fetch(req, mockEnv, mockCtx);
    // Expect the actual route response, not a 401
    expect(res.status).not.toBe(401);
  });

  it('rejects requests with no Authorization header', async () => {
    const req = new Request('http://localhost/api/profile');
    const res = await app.fetch(req, mockEnv, mockCtx);

    expect(res.status).toBe(401);
    const body = await res.json();
    expect(body).toMatchObject({ error: 'Unauthorized' });
  });

  it('rejects requests with a malformed token', async () => {
    const req = new Request('http://localhost/api/profile', {
      headers: { Authorization: 'Bearer bad.token.here' },
    });

    const res = await app.fetch(req, mockEnv, mockCtx);
    expect(res.status).toBe(401);
  });
});

Testing error handlers

Assert on the status code and response body to verify your error handler shapes the response correctly, including custom metadata from BlazeError.

test/errors.test.ts

import { describe, it, expect, vi } from 'vitest';
import app from '../src/index';

const mockCtx = { waitUntil: vi.fn(), passThroughOnException: vi.fn() };

describe('Error handling', () => {
  it('returns 500 for unexpected errors', async () => {
    const req = new Request('http://localhost/error');
    const res = await app.fetch(req, {}, mockCtx);

    expect(res.status).toBe(500);
    const body = await res.json();
    expect(body).toMatchObject({ error: 'Internal Server Error' });
  });

  it('returns structured BlazeError responses', async () => {
    const req = new Request('http://localhost/admin/secret');
    const res = await app.fetch(req, {}, mockCtx);

    expect(res.status).toBe(403);
    const body = await res.json();
    // BlazeError metadata is spread into the response body
    expect(body).toMatchObject({
      error: 'Forbidden',
      code:  'INSUFFICIENT_PERMISSIONS',
    });
  });

  it('returns 404 for unknown routes', async () => {
    const req = new Request('http://localhost/does-not-exist');
    const res = await app.fetch(req, {}, mockCtx);

    expect(res.status).toBe(404);
    const body = await res.json();
    expect(body).toMatchObject({ error: 'Not Found' });
  });
});

To test that background tasks are scheduled correctly, assert on mockCtx.waitUntil.mock.calls after await app.fetch(...). For example, if your analytics handler writes a data point after every GET /products/:id, you can verify expect(mockCtx.waitUntil).toHaveBeenCalledOnce() without waiting for the deferred promise to settle.