cloudflare--workers-sdk/packages/vitest-pool-workers/AGENTS.md

vitest-pool-workers — Agent Guide

Custom Vitest pool for running Worker tests inside the actual workerd runtime. Do NOT repeat root AGENTS.md content (pnpm, changesets, code style, etc.).

THREE-CONTEXT ARCHITECTURE

1. Pool (src/pool/index.ts)

• Runs in Node.js Vitest process
• Main export (exports["."]), built as ESM (.mjs)
• Orchestrates test execution

2. Config (src/config/index.ts)

• Runs in Node.js
• Exported as exports["./config"], built as CJS (.cjs)
• Provides defineWorkersConfig() / defineWorkersProject() helpers
• Injects Vite plugin for cloudflare:test resolution, sets resolve conditions (workerd, worker, browser)

3. Worker (src/worker/index.ts)

• Runs inside workerd runtime
• NOT exported via package.json — internal entry
• Contains HACK: monkeypatches VitestExecutor to access singleton
• Has direct cross-package source import into miniflare/src/workers/core/devalue

BUILD

scripts/bundle.mjs runs 3 separate esbuild builds:

1. undici mock-agent (CJS)
2. pool + worker (ESM)
3. config + libs (CJS)

Types entry types/cloudflare-test.d.ts is hand-written (NOT generated from source).

THE cloudflare:test MODULE

Tests inside workerd import from cloudflare:test:

import { env, fetchMock, SELF } from "cloudflare:test";

Resolved by custom Vite plugin (@cloudflare/vitest-pool-workers:config) that re-exports from cloudflare:test-internal (runtime-provided).

CONVENTIONS

• expect must come from test context: it("name", ({ expect }) => {}) — never import { expect } from "vitest"
• Tests use .test.ts naming
• Excludes *.worker.test.ts from vitest config

TESTING

• Does NOT extend vitest.shared.ts
• Hook timeout: 60s, retry: 2
• Global setup starts mock npm registry, installs local package to temp dir
• Test helper: custom test fixture with tmpPath, seed(), vitestRun(), vitestDev()
• Fixtures in fixtures/vitest-pool-workers-examples/ (20+ sub-fixtures testing KV, R2, D1, DO, Queues, etc.)
• Skipped on Windows CI due to flakiness