wd-test-format

name	wd-test-format
description	Detailed guide for authoring .wd-test files in workerd, with examples of bindings, Durable Objects, multi-service configs, TypeScript tests, and network access.

.wd-test File Format

.wd-test files are Cap'n Proto configs that define test workers for workerd's test framework. They use the schema defined in src/workerd/server/workerd.capnp.

---

MANDATORY: Load Reference File When Relevant

This skill is split across multiple files for context efficiency. The core patterns below cover standard single-service tests. Advanced configuration patterns live in a reference file.

You MUST read the reference file before writing or reviewing test configs that involve its subject matter. Do not guess at advanced config syntax — the reference file contains the exact patterns and fields required. Skipping it WILL lead to incorrect configs that fail at runtime.

File	MUST load when...
reference/advanced-configs.md	Test involves Durable Objects, multiple services
	communicating via service bindings, outbound network access,
	external services/sockets, or TypeScript source files

When in doubt about whether the reference file is relevant, load it — the cost of reading is far less than the cost of a broken test config.

---

Basic Structure

using Workerd = import "/workerd/workerd.capnp";

const unitTests :Workerd.Config = (
  services = [(
    name = "my-test",
    worker = (
      modules = [(name = "worker", esModule = embed "my-test.js")],
      compatibilityFlags = ["nodejs_compat_v2"],
    ),
  )],
);

Key rules:

• The const name (e.g., unitTests) must match what the test runner expects