Testing
Warlock tests run on Vitest. Pure unit specs mock collaborators and need no framework bootstrap. Integration tests call services/models with real connectors or hit an HTTP server. The generated projects keep unit specs separate from integration setup.
This guide explains the architecture, then walks both modes end-to-end.
The 30-second look
Section titled “The 30-second look”# One command from a fresh project — drops vite.config.ts, test-global-setup.ts, test-setup.tsnpx warlock add test
# Run the suitenpm run test
# Watch mode while you worknpm run test:watchA service integration test looks like this:
import { describe, expect, it } from "vitest";import { createProductService } from "../services/create-product.service";
describe("createProductService", () => { it("creates a product with a slug", async () => { const product = await createProductService({ name: "Pen", price: 5 }); expect(product.get("slug")).toBe("pen"); });});An HTTP integration test looks like this:
import { describe, expect, it } from "vitest";import { expectJson, testPost } from "@warlock.js/core/tests";
describe("POST /products", () => { it("creates a product over HTTP", async () => { const response = await testPost("/products", { name: "Pen", price: 5 }); const { product } = await expectJson<{ product: { id: string } }>(response, 201); expect(product.id).toBeDefined(); });});Both run against your real code. No mocks of the framework, no in-memory replacements for the DB. The bootstraps below explain ownership; opt-in worker lifetime later in this guide amortizes setup across files.
Keep Vitest setup out of development
Section titled “Keep Vitest setup out of development”warlock dev (and warlock build) load your app’s vite.config.ts. Anything you put there for tests runs in development too. Guard vitest-only setup:
if (process.env.VITEST) { Object.assign(process.env, testEnv); // test database, test keys...}The two-worlds architecture
Section titled “The two-worlds architecture”The generated integration project uses Vitest fork workers. File setup runs before each file; the pool can execute files in parallel. The HTTP server needs to live somewhere that all those workers can reach. So the framework splits the bootstrap into two layers:
┌─── Main vitest process (one) ────────────────────────────┐│ ││ globalSetup: ./src/test-global-setup.ts ││ └─ startHttpTestServer() ││ • boots ALL connectors (db, http, socket, …) ││ • listens on an OS-assigned ephemeral port ││ • owns its own DB connection ││ │└──────────────────────────────────────────────────────────┘ │ HTTP fetch requests ▼┌─── Fork worker N (setup before each file) ──────────────────┐│ ││ setupFiles: ./src/test-setup.ts ││ └─ setupTest({ connectors: true }) ││ • boots Early-phase connectors EXCEPT http ││ • owns ITS OWN db / cache connection ││ • calls services, repositories, models directly ││ │└──────────────────────────────────────────────────────────┘The HTTP server runs once and stays up for the whole vitest run. Each worker owns a parallel set of connections so service-level tests don’t fight over a shared DB pool.
Two consequences worth pulling out:
- Per-worker writes go to a different connection than HTTP-server reads. Both point at the same physical DB, so committed data is mutually visible — but uncommitted transactions are not.
- The HTTP server is a real server. Real routing, real middleware, real validation, real responses. You don’t need a separate “mode” — production code is the test code.
Mode 1 — Unit tests
Section titled “Mode 1 — Unit tests”Anything you can import and call without going through HTTP. Services, repositories, models, use-cases, util functions.
setupTest({ connectors })
Section titled “setupTest({ connectors })”Each Vitest worker runs src/test-setup.ts before each integration test file executes. The file calls setupTest:
import { setupTest } from "@warlock.js/core/tests";
await setupTest({ connectors: true });setupTest runs the framework’s bootstrap (env, config, modules, files orchestrator) and starts the connectors you ask for. By default, pair setup with afterAll(teardownTest) in every file; worker lifetime is opt-in below.
The connectors knob
Section titled “The connectors knob”| Value | Boots | Use when |
|---|---|---|
true (default) | All Early-phase connectors except http (db, cache, logger, …) | Most service / model tests. Sensible default. |
false | Nothing | Pure logic with no framework subsystem touches. |
["database", "cache"] | Only those, in that order | A narrow test that needs DB but not, say, storage. |
You can also set tests.connectors in src/config/tests.ts for a project-wide default that applies unless the setupTest parameter is explicit:
const testsConfigurations = { connectors: ["database", "logger"],};
export default testsConfigurations;A complete unit test
Section titled “A complete unit test”import { afterEach, describe, expect, it } from "vitest";import { Cart } from "../../carts/models/cart";import { Order } from "../models/order";import { placeOrderService } from "../services/place-order.service";
describe("placeOrderService", () => { afterEach(async () => { await Order.query().delete(); await Cart.query().delete(); });
it("creates an order from a cart", async () => { const cart = await Cart.create({ user_id: "u_1", items: [{ product_id: "p_1", quantity: 2, unit_price: 50 }], });
const order = await placeOrderService({ cart_id: cart.id });
expect(order.get("total")).toBe(100); expect(order.get("status")).toBe("pending_payment"); });
it("throws when the cart is empty", async () => { const cart = await Cart.create({ user_id: "u_1", items: [] });
await expect(placeOrderService({ cart_id: cart.id })).rejects.toThrow(/empty/i); });});No bootstrap in the file — src/test-setup.ts already did it. Direct calls to services and models. Real DB. Vitest’s afterEach resets between tests so the order is deterministic.
For the full unit-test playbook, see test-service/SKILL.md.
Mode 2 — HTTP integration tests
Section titled “Mode 2 — HTTP integration tests”When you want to assert the full stack: route resolution, middleware chain, validation, controller, response shape.
startHttpTestServer() in globalSetup
Section titled “startHttpTestServer() in globalSetup”import { startHttpTestServer, stopHttpTestServer } from "@warlock.js/core/tests";
export async function setup() { await startHttpTestServer();}
export async function teardown() { await stopHttpTestServer();}Vitest calls setup before any worker spawns and teardown after they all exit. The server boots once, your tests share it.
The server is “real but minimal” — no file watching, no HMR, no health checkers. Same routing and middleware as production.
When the app has the web connector, startHttpTestServer() boots it with a Vite dev server (pass { web: false } for an API-only suite to skip it). stopHttpTestServer() shuts every connector down, and the web connector closes Vite, its HMR websocket and its file watchers even when it booted but never finished starting, so the run exits on its own instead of ending with “something prevents 2 Vite servers from exiting”. If a connector still reports itself active after shutdown, teardown prints [test-server] Connectors still active after shutdown: <names>. Test workers should not start the web connector; select the connectors a spec needs with tests.connectors.
The HTTP helpers
Section titled “The HTTP helpers”import { testGet, testPost, testPut, testPatch, testDelete, testRequest, expectJson, parseJsonResponse, getTestServerUrl,} from "@warlock.js/core/tests";Everything is built on native fetch:
const response = await testPost("/products", { name: "Pen", price: 5 });// sends JSON body, sets Content-Type, returns the Response
const body = await expectJson<{ product: { id: string } }>(response, 201);// asserts status === 201, parses JSON, throws with response body on mismatch
console.log(body.product.id);getTestServerUrl() reads http.host + http.port from config — change those, the helpers follow.
A complete HTTP test
Section titled “A complete HTTP test”import { describe, expect, it } from "vitest";import { authService } from "@warlock.js/auth";import { expectJson, testGet, testPost } from "@warlock.js/core/tests";import { User } from "../../users/models/user";
describe("Products API", () => { it("requires auth on POST /products", async () => { const response = await testPost("/products", { name: "Pen", price: 5 }); await expectJson(response, 401); });
it("creates a product when authenticated", async () => { const user = await User.create({ email: "u@e.com", password: "secret" }); const { accessToken } = await authService.createTokenPair(user);
const response = await testPost( "/products", { name: "Pen", price: 5 }, { headers: { Authorization: `Bearer ${accessToken.token}` } }, );
const { product } = await expectJson<{ product: { id: string; name: string }; }>(response, 201);
expect(product.name).toBe("Pen");
// Read it back via HTTP const list = await testGet("/products"); const { products } = await expectJson<{ products: Array<{ id: string }> }>(list); expect(products.some((p) => p.id === product.id)).toBe(true); });
it("validates the request body", async () => { const response = await testPost("/products", { name: "" }); const body = await expectJson<{ errors: Array<{ key: string }> }>(response, 400); expect(body.errors.some((e) => e.key === "name")).toBe(true); });});For the full HTTP-test playbook, see test-http/SKILL.md.
The test kit
Section titled “The test kit”Everything below ships in @warlock.js/core/tests, next to setupTest and the HTTP helpers.
Fakes — on by default
Section titled “Fakes — on by default”In the test environment setupTest() (per test file) and startHttpTestServer() (in globalSetup) install seven fakes once their connectors are up, and restore them on teardown:
| Fake | Replaces | Assertions |
|---|---|---|
mailFake | Mail delivery — sendMail() / Mail capture instead of send | assertSent(matcher?), assertNotSent, assertSentCount(n, matcher?), assertNothingSent, sent() |
queueFake | @warlock.js/queue dispatch — recorded, never pushed to Redis | assertPushed(job, payload?), assertNotPushed, assertPushedCount(n, job?), assertNothingPushed, pushed() |
cacheFake | The cache’s current driver — a fresh in-memory driver | assertHas(key), assertMissing(key), assertStored(key, value) |
storageFake | Every storage driver (local, S3, R2, Spaces) — a temp directory | assertExists(path, driver?), assertMissing(path, driver?), files(driver?) |
clockFake | clock from @warlock.js/core — frozen at 2026-01-01T00:00:00Z | travel(ms), travelTo(date), freeze(date?), now() |
idsFake | ids from @warlock.js/core — numbered UUIDs and tokens | uuid(n) (the n-th UUID), reset() |
secretsFake | The secrets facade — isolated namespace-aware memory | assertHas(name), assertMissing(name), assertStored(name, value), clear() |
import { mailFake, queueFake } from "@warlock.js/core/tests";import { beforeEach, expect, it } from "vitest";import { sendWelcomeSeries } from "../jobs/send-welcome-series.job";import { registerUserService } from "../services/register-user.service";
beforeEach(() => { mailFake.clear(); queueFake.clear();});
it("welcomes a new user and schedules the follow-up mails", async () => { const user = await registerUserService({ name: "Ada", email: "ada@example.test" });
mailFake.assertSent({ to: "ada@example.test", subject: /welcome/i }); queueFake.assertPushed(sendWelcomeSeries, { userId: user.id });});The secret store fake bypasses keychain, environment and files. It retains values only in its process; assertion failures never reveal them. Opt out with fakes: { secrets: false } for deliberate backend integration tests.
A matcher is a predicate or an object of fields that must all match ({ to, subject, from, contains } for mail; a payload subset for jobs). A failing assertion lists what was actually recorded.
Jobs are recorded, not run — call the job’s handler directly to test what it does. The clock and ids fakes replace only the framework’s clock and ids; Date, setTimeout and drivers keep real time, so nothing stalls. Read the time through clock.now() / clock.timestamp() and generate identifiers through ids.uuid() / ids.token() where a test needs to control them.
The storage fake replaces the configured default driver too. A default: "r2" (or s3, spaces) in src/config/storage.ts does not need the cloud SDK packages in a test run: in the test environment the connector builds the configured default on first use rather than at boot, and while the storage fake is on every driver is a local one under the temp root.
A fake records in the process that runs the code. Mail sent while the shared HTTP server (Vitest’s main process) handles a request is captured there, not in the test worker that sent the request. To assert on what a request did, serve it in the worker with createTestHttpServer(). The storage fake is the exception: its temp root is shared with the workers, so a file an HTTP request stored is visible to the test.
Opting out
Section titled “Opting out”Precedence is the fakes option > tests.fakes in src/config/tests.ts > all on.
const testsConfigurations = { // keep the real drivers for every fake: // fakes: false, // or only for some: fakes: { cache: false, storage: false },};
export default testsConfigurations;await setupTest({ importModule: (file) => import(file), fakes: false });await startHttpTestServer({ port: 0, fakes: { queue: false } });An unknown fake name or a non-boolean value fails setup with the list of known fakes. Tests that relied on real deliveries, a real Redis cache shared between the HTTP server and the workers, or real buckets need fakes: false (or the matching per-fake false).
Model factories
Section titled “Model factories”defineFactory(Model, (seed) => attributes) builds deterministic records — no faker, no randomness. The n-th record a factory builds is the same on every run.
import { defineFactory } from "@warlock.js/core/tests";import { User } from "app/users/models/user";
export const userFactory = defineFactory(User, (seed) => ({ name: seed.text("User"), // "User 1", "User 2", ... email: seed.email(), // "user1@example.test", ... password: "test-password",})).state("admin", () => ({ role: "admin" }));const body = userFactory.make({ name: "Ada" }); // attributes only, no databaseconst users = await userFactory.create(3); // three saved usersconst admin = await userFactory.with("admin").create();make() / makeMany(n) return attributes without touching the database — use them for request bodies. create() saves through the model’s own create(), so casts, defaults, hooks and events run; create(n) / createMany(n) save n in order. The seed offers sequence, index, text(prefix), email(prefix), uuid(), date(offsetDays), number(min, max) and pick(values). Overrides may be a partial or a function of the seed. resetFactorySequences() restarts every factory.
In-process server with the production plugins
Section titled “In-process server with the production plugins”createTestHttpServer() starts an HTTP server inside the test worker, built the way production builds it: the same Fastify setup, every plugin production registers (rate limit with its cache store, CORS, multipart, cookies) and the router’s real route registration, listening on an OS-assigned port. Tests cannot drift from real request shapes, and the fakes see what the handler did.
import { createTestHttpServer, mailFake } from "@warlock.js/core/tests";import { afterAll, beforeAll, expect, it } from "vitest";
let app: Awaited<ReturnType<typeof createTestHttpServer>>;
beforeAll(async () => { // every app route; pass the same importer setupTest() takes app = await createTestHttpServer({ loadAppModules: true, importModule: (file) => import(file) });});
afterAll(() => app.close());
it("mails the support inbox", async () => { const response = await app.post("/api/contact", { name: "Ada", email: "ada@example.test", message: "Hi", });
expect(response.status).toBe(200); mailFake.assertSent({ to: "support@example.test" });});It returns url, port, the Fastify server, the request helpers (request, get, post, put, patch, delete), actingAs(user) bound to it, and close(). Pass routes: (router) => … instead of (or as well as) loadAppModules to register routes for one test; close() removes them. App modules load once per process.
Pass importModule whenever the test needs the app’s modules to run. Without it nothing is imported in the test worker, so Model.events().listeners stays empty: model event listeners the app registers (in events/ files or main.ts) never fire, and the routes and main.ts code are not loaded.
The modules are found from the project at the current working directory (src/app/*/routes.ts, main.ts, events, locales), so run the tests from the project root. That works for a project inside a dot-directory such as a git worktree under .claude/worktrees/. If the project has route or main.ts files on disk and the load finds none, createTestHttpServer() throws an error naming the project root and the file counts, instead of serving an empty application. A worker that moves to another project root loads that project’s modules again.
Ephemeral ports
Section titled “Ephemeral ports”startHttpTestServer({ port: 0 }) lets the OS pick a free port and publishes the bound one to the workers, so the suite never collides with warlock dev or another suite. warlock add test generates src/test-global-setup.ts with it. createTestHttpServer() always uses an OS-assigned port.
Response snapshots
Section titled “Response snapshots”snapshotResponse(response, { redact }) reduces a response to { status, contentType, body } with the values that change every run replaced by "[redacted]":
const response = await testPost("/posts", { title: "Hello" });
expect( await snapshotResponse(response, { redact: ["post.id", "post.createdAt"] }),).toMatchSnapshot();* matches any key or array index ("posts.*.id"). It consumes the body — call it instead of response.json().
Picking the right mode
Section titled “Picking the right mode”| You’re testing | Mode |
|---|---|
| A service / use-case / repository in isolation | Unit (test-service) |
| A model’s transformers / accessors / hooks | Unit |
| A util function with no DB | Unit with connectors: false |
| A route’s auth / validation / response shape | HTTP (test-http) |
| Multi-controller flow (e.g. order placement → notification) | HTTP |
| Error response status codes | HTTP |
Default to unit tests — they’re faster and easier to reason about. Promote to HTTP when the value of the test is “does the full route work” rather than “does this function work.”
Project layout
Section titled “Project layout”warlock add test generates the files below plus src/test-runner.ts for awaited worker cleanup:
src/test-global-setup.ts— vitestglobalSetup, starts/stops the HTTP server.src/test-setup.ts— vitestsetupFiles, callssetupTestbefore each integration file.vite.config.ts— separates unit and integration projects; see the runtime guide below.
It also installs vitest, @vitest/coverage-v8, vite, and @mongez/vite (which is what makes TypeScript imports + the framework’s module layout work under vitest). vitest and @vitest/coverage-v8 are pinned to the same exact version: coverage-v8 peers on vitest at one version, so a range would let npm resolve two copies.
Tests live colocated with the module they exercise:
src/app/products/ models/ services/ controllers/ tests/ create-product.service.test.ts products.controller.test.tsRunning tests
Section titled “Running tests”npm run test # one-shot runnpm run test:watch # watch modenpm run test:coverage # with v8 coveragenpm run test:ui # vitest UIYou can scope down with vitest’s filename or test-name filters:
npm run test -- create-product # files matching "create-product"npm run test -- -t "creates a product" # test name patternwarlock test runs the project’s own Vitest and can run only what a change affects — the fast loop while you work:
warlock test --changed # tests affected by uncommitted changeswarlock test --changed --since main # ... by changes since mainwarlock test --related src/app/posts/services/create-post.service.tswarlock test --json # machine-readable results on stdoutSee CLI commands for every flag.
Running tests on Windows
Section titled “Running tests on Windows”The test helpers exported from @warlock.js/core/tests build their files with node:path and os.tmpdir(), so they behave the same on Windows as elsewhere. The differences that reach app test suites come from the operating system:
- Symlinks. Creating a file symlink on Windows needs administrator rights or Developer Mode, and fails with
EPERMotherwise. A directory link made withfs.symlink(target, link, "junction")needs neither, so linknode_modulesfolders and fixture directories as junctions (the option is ignored on Linux and macOS). Skip a test that needs a file symlink withit.skipIf(process.platform === "win32"). - Permissions.
chmodandmode & 0o777checks have no effect on Windows; skip tests that assert Unix permission bits. - Paths. Build expected paths with
path.join/path.resolve, or convert afile:URL withfileURLToPathinstead of readingURL.pathname, which yields/C:/…. - Services. Redis and Mongo service containers are not available on GitHub’s Windows runners, so keep specs that need them behind an opt-in variable such as
WARLOCK_REDIS_INTEGRATION.
Caveats and trade-offs
Section titled “Caveats and trade-offs”When a unit test copies TypeScript source into a temporary directory for a fresh
Node process, preserve the source package’s module mode. ESM fixtures need a
package.json with "type": "module"; otherwise tsx can load the copy as
CommonJS and named exports fail before the behavior under test runs. Assert the
child process exit status with its captured stderr before checking stdout.
- The two-worlds connection split is intentional. Don’t fight it by trying to share connections — it would deadlock test parallelism. Instead, design tests so the worker write commits before the HTTP read.
- Test data persists across files unless you clean it up. Vitest doesn’t wrap test files in transactions. Use
afterEachtruncates or design idempotent fixtures. - The HTTP server is started in dev mode (
runtimeStrategy: development). That’s so routes get re-resolved properly under the framework’s dev orchestrator. It’s still a real server with real routing — just not the production builder pipeline. - Vitest 5 defaults
clearMocksto true, which also clears calls a module made when it was imported. A scheduler that registers jobs, or an event bus that subscribes, from amain.tsimported at the top of a spec has those recorded calls cleared before the first test, so asserting them fails although the code ran. Import the module inside the test (await import("./main")) after the mocks are set up, or setclearMocks: falsefor the project. The Warlock fakes record on their own and are not affected. - Fakes, not mocks. Mail, queue, cache, storage, clock, ids and secrets are faked by default (the test kit); everything else runs for real. For an external API (OpenAI, Stripe), vitest’s
vi.mock(...)works fine.
See also
Section titled “See also”test-service/SKILL.md— per-task playbook for unit tests.test-http/SKILL.md— per-task playbook for HTTP integration tests.- Integration test recipe — end-to-end walkthrough of testing a CRUD controller.
warlock addfeatures — whatwarlock add testinstalls.
Verify shared rate limits against Redis
Section titled “Verify shared rate limits against Redis”Framework contributors can run the cache-backed rate-limit store checks from packages/core with WARLOCK_REDIS_INTEGRATION=1 npx vitest run src/http/rate-limit-cache-store.redis.spec.ts. The suite connects to QUEUE_REDIS_HOST / QUEUE_REDIS_PORT (defaults 127.0.0.1:6390), uses isolated UUID-prefixed keys, and fails if the requested Redis service is unavailable. It exercises separate Redis clients, concurrent counts, preserved window deadlines, aligned window resets, and a seed that actually expires before its atomic increment. Without the opt-in flag it reports a local skip; CI enables it against its Redis service.
Worker dictionaries and owned runtime resources
Section titled “Worker dictionaries and owned runtime resources”The generated src/test-setup.ts calls:
await setupTest({ importModule: (file) => import(file) });setupTest() reads src/app/*/utils/locales.json after configuration in each
Vitest worker. Server translation helpers therefore see all configured locales
without manual registration. Invalid dictionaries fail setup. teardownTest()
unregisters those dictionaries; legacy executable locale files still require
explicit imports in worker setup.
Global HTTP fixtures should use await startHttpTestServer({ port: 0, web: false })
for API-only suites and await stopHttpTestServer() in teardown. Stop releases
connectors and the file runtime’s loader channel, queued work, watchers, health
workers, and registered module cleanup hooks, including after partial startup.
A Node loader registration is process-scoped; its message channel is closed at
teardown. Module-owned timers/listeners must register their cleanup hooks.
A module that owns a long-running handle can export an awaited cleanup:
import { createServer } from "node:net";const listener = createServer();listener.listen(0, "127.0.0.1");export async function cleanup(): Promise<void> { await new Promise<void>((resolve, reject) => { listener.close((error) => (error ? reject(error) : resolve())); });}HTTP test teardown awaits these cleanup functions and reports failures after attempting every module’s cleanup. Avoid leaving module-owned handles running outside this lifecycle.
Runtime lifetime, unit projects and setup profiling
Section titled “Runtime lifetime, unit projects and setup profiling”warlock add test (also used by create-warlock --features=test) generates two
Vitest projects. unit discovers src/**/*.unit.{spec,test}.ts and has no Warlock
setup or HTTP global setup. integration discovers every other src/**/*.{spec,test}.ts,
specs inside src/**/tests/, and tests/**/*.{test,spec}.ts, and excludes *.unit.*
files. It uses the framework setup, HTTP global setup and a generated src/test-runner.ts.
Name a pure service spec <name>.unit.spec.ts, keep it beside its source and mock
repositories at the boundary. The .unit infix is the only switch: a plain .spec.ts or
.test.ts boots the app. Existing config files are never overwritten, so an app created
before 5.38 keeps *.spec.ts as unit and *.test.ts as integration until you copy the
new include and exclude globs into its vite.config.ts and rename the unit specs.
Existing config files are preserved; copy the projects layout into them manually.
The generated unit project lists plugins: [guardUnitProject()] (from
@warlock.js/core/vite) and env: { WARLOCK_TEST_PROJECT: "unit" }. A unit spec that
imports a connector, connectorsManager, bootstrap or a test-server helper, or calls
setupTest() without { mode: "unit" }, fails with a message that names the import and
says to drop .unit from its name. The opposite mistake is reported by
warlock check as WL9024 (a warning): an integration spec
that imports nothing needing the app should be renamed to <name>.unit.spec.ts.
Vitest 5 or newer is required for the generated runner (Vitest 5 removed vitest/runners; the runner extends TestRunner from vitest).
For a unit spec that needs configuration values, use:
import { afterAll, expect } from "vitest";import { setupTest, teardownTest } from "@warlock.js/core/tests";
await setupTest({ mode: "unit", importModule: (file) => import(file), file: expect.getState().testPath,});afterAll(teardownTest);Unit mode loads warlock.config.ts and configuration values once per module graph.
It skips bootstrap/env/prestart hooks, connectors, config special handlers,
filesOrchestrator.init(), the native ESM loader, and fake installation. Keep
configuration imports free of side effects; arbitrary code imported by a config
file can still perform I/O. A plain unit spec usually needs no setupTest() at all.
connectors: false still bootstraps; it is not the cheap unit mode. Use separate
projects for unit and integration runtimes.
One runtime per fork
Section titled “One runtime per fork”Apps generated by 5.38 or newer (warlock add test, create-warlock) boot the framework
once per Vitest worker: src/config/tests.ts sets lifetime: "worker" and
resetDatabase: true, the integration project has isolate: false, and the database
config uses one database per worker. WARLOCK_TEST_LIFETIME=file switches the three back to
one runtime per test file. An app created earlier keeps its configuration; warlock upgrade
lists the places to change. The steps below do the same by hand for an existing config.
To reuse a runtime, change the integration project’s isolate to false, keep
pool: "forks" and runner: "./src/test-runner.ts", then configure:
import { resetWorkerDatabase } from "../test-database";
export default { lifetime: "worker", // Application-owned callback: truncate only this worker's test database. // Called before every file's fixtures, including the first file. resetBetweenFiles: async () => { await resetWorkerDatabase(); }, profileSetup: true,};Run with npx vitest run --project integration. Worker lifetime refuses watch,
threads, isolated module graphs, or a missing runner with a message explaining
the required settings. Keep afterAll(teardownTest) in the setup file: in worker
mode it marks the end of the file; Vitest’s awaited worker cleanup closes the
runtime once. The runner uses TestRunner.onCleanupWorkerContext, verified
in Vitest 5.0.3’s TestRunner declaration, runner implementation and worker cleanup source.
For an existing project, generate this runner without overwriting your config:
import { configureTestWorker } from "@warlock.js/core/tests";import { TestRunner } from "vitest";
export default class WarlockTestRunner extends TestRunner { public constructor(config: ConstructorParameters<typeof TestRunner>[0]) { super(config); configureTestWorker( { pool: this.pool, watch: config.watch, isolate: config.isolate }, (cleanup) => this.onCleanupWorkerContext?.(cleanup), ); }}The first file bootstraps; subsequent files reuse connectors and config. Between
files, selected fakes are restored and reinstalled, resetting mail/queue records,
cache, secrets, clock, IDs and a private storage directory. Worker storage is
separate from the global HTTP server’s storage: use an in-process test HTTP server
when assertions need to see request-side fake state. The hook runs after fake
reset and before fixtures. It must finish before returning. Within a file,
repeated setupTest() calls remain idempotent; use beforeEach/afterEach for
per-test cleanup.
Before each file the runtime resets, in this order: test HTTP servers the previous file left
open are closed; the request context is cleared; the route table returns to the snapshot
taken after the app booted (routes a file registered by hand are removed, the app’s own
stay); a real in-memory cache driver is flushed; the database is truncated
(resetDatabase); then resetBetweenFiles runs. The fakes (mail, queue, cache, storage,
clock, ids, secrets) are restored and reinstalled first. State outside those, such as a
notification channel, is reset in resetBetweenFiles.
A spec that changes global configuration the reset does not undo (config.set, process
environment, a driver option) opts its own file out:
await setupTest({ importModule: (file) => import(file), lifetime: "file" });The worker’s shared runtime is shut down, the file gets a fresh runtime that its own
teardownTest() closes, and the next file goes back to the worker lifetime. It costs one
extra boot for that file. "file" is the only accepted value.
This trades module isolation for startup cost: application singletons, config
mutations, mocks and module side effects can survive between files. Reset your
own state in resetBetweenFiles, restore mocks, and keep connector selection
consistent. Give each worker a distinct database/schema using
process.env.VITEST_POOL_ID (1-based since Vitest 5) when preparing test connections. Never drop a shared
database from this hook while other workers are using it. The framework does not
create a memory replica set or a cross-worker lock; those belong to the application’s
global setup. A shared HTTP server and a single replica set can contend on I/O,
locks and shared fixtures even though workers run concurrently. Scope rows and
HTTP fixtures per worker, or run tests that require global mutation separately
with maxWorkers: 1. No test-server teardown ownership changes are needed here.
getTestRuntimeStats() from @warlock.js/core/tests returns process-local
{ bootstraps, files }. For example, after setup in worker mode:
import { expect, it } from "vitest";import { getTestRuntimeStats } from "@warlock.js/core/tests";
it("reuses this worker's runtime", () => { expect(getTestRuntimeStats().bootstraps).toBe(1);});Across one integration project, a successful run with no worker recycling needs
at most maxWorkers bootstraps. Multiple projects, worker crashes and memory-limit
recycling can create additional processes; count distinct PIDs in profiles.
Worker lifetime with the HTTP test server and a database
Section titled “Worker lifetime with the HTTP test server and a database”Two things are shared when a worker keeps its runtime: the database and the servers a file opened. Both have a built-in reset now.
export default { lifetime: "worker", // Truncate every table/collection (the migrations ledger is kept) before each file. resetDatabase: true, // or { except: ["countries"] }};import { workerDatabaseName } from "@warlock.js/core/tests";
// One database per Vitest worker: the reset above may delete every row in it.const name = process.env.VITEST ? workerDatabaseName("app_test") : "app";resetDatabaseruns after the fakes reset and beforeresetBetweenFiles, so the hook can seed reference data.resetTestDatabase({ except, only, connection })is exported for tests and custom hooks. On PostgreSQL it truncates withCASCADE.workerDatabaseName(base)returnsbase_<VITEST_POOL_ID>;testWorkerId()returns the 1-based worker id. Create or migrate that database in the application’s global setup or in abootstrapstep before connectors start.- Servers from
createTestHttpServer()that a file did notclose()are closed before the next file, so their routes and ports do not leak. App modules (loadAppModules) load once per worker and are reused. - The global
startHttpTestServer()server runs in Vitest’s main process with its own connections and fakes. Worker lifetime does not touch it, so keep requests through it independent of the worker database, or usecreateTestHttpServer()in the worker for tests that read the same database the assertions use. isolate: falseshares module state between files of a worker: singletons,vi.mock()of app modules and module-level caches survive. Restore mocks inafterEach, and clear module state inresetBetweenFiles.
Measure and size CI workers
Section titled “Measure and size CI workers”Set tests.profileSetup: true or run
WARLOCK_TEST_PROFILE=1 npx vitest run --project integration. Pass
file: expect.getState().testPath to setupTest() for file labels (the generated
setup does this). Each file emits one line with milliseconds for environment, config,
bootstrap, orchestrator, app config, connectors, fakes, reset and teardown as
applicable, plus body, the time between setup finishing and teardown starting.
Reused files report reset instead of startup steps. A file that booted also reports one
connector.<name> entry per connector (its boot() plus start()), which names the slow
one: the database connector includes opening the connection and registering models, and the
web connector includes creating the Vite dev server. Loading the app’s modules (routes,
main.ts, events, models) is appModules. When a file-lifetime run spends
half or more of its time in setup over at least four files, the worker summary and
TestSetupReporter print a line recommending worker lifetime. A summary per
worker reports file/bootstrap counts, summed step timings and final shutdown.
The generated config also installs TestSetupReporter from @warlock.js/core/vite
(reporters: ["default", new TestSetupReporter()]), which aggregates file counts,
bootstrap counts and timings across PIDs into a run summary. With profiling on, the
same block lists the boot phases (config, translations, connectors, fakes, routes, reset,
teardown), each connector, the HTTP test server’s own boot phases and the five slowest
files. startHttpTestServer() prints its phases as a [warlock:test] server line, with the
web connector and Vite as connector.web. Set WARLOCK_TEST_PROFILE_JSON=profile.json, or
pass new TestSetupReporter({ json: "profile.json", slowest: 10 }), to also write the
profile as JSON (phases, connectors, server, slowestFiles, perFile). Summed
timings are not wall time. Worker shutdown is included when its summary reaches the reporter
before the run-end callback; individual worker summaries always report it.
The generated config sets maxWorkers: recommendedTestWorkers() from
@warlock.js/core/vite. It takes the smaller of CPU affinity and the tightest
visible cgroup v2 quota, rounding fractional CPUs down with a minimum of one.
For example cpu.max = 1200000 100000 recommends 12 workers on a 48-CPU host.
The format follows the kernel cgroup v2 CPU interface.
It reads /proc/self/cgroup and visible ancestors under /sys/fs/cgroup; hosts
without readable v2 quotas use affinity. Set maxWorkers explicitly on cgroup v1,
custom cgroup mounts, or when database/memory limits require fewer workers.
Release gate
Section titled “Release gate”npx warlock test --changed --since "$LAST_RELEASE_REF"npx vitest run --project integration# Nightly (all projects):npx vitest runThe first command includes affected tests, using the existing changed-test CLI; the second always covers integration wiring. Keep the full suite nightly and compare cold and reused setup profiles on the same revision, worker count and database fixture before claiming a speedup.
For a manual fake harness outside setupTest, the same private storage behavior
is available with await installTestFakes(true, { isolatedStorage: true }), paired
with await restoreTestFakes(). Both are exported from @warlock.js/core/tests.
await storageFake.install({ isolated: true }) / await storageFake.restore()
provides it for a storage-only harness. Existing installs share the HTTP root by
default; the isolated option never replaces or deletes that shared root.
Module cleanup hooks that close asynchronous handles must return a promise that resolves after closure. For a MessagePort, register its close event listener before calling close() and await that event before asserting the handle is no longer referenced.