wd-test-format
Detailed guide for authoring .wd-test files in workerd, with examples of bindings, Durable Objects, multi-service configs, TypeScript tests, and network access.
- Installs
- 46
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/cloudflare/workerd --skill wd-test-format- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads wd-test-format automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
.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... |
|---|---|
| Advanced configurations | 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 modulesusesembedto inline file contents at build time- The first module should be named
"worker"— this is the entry point compatibilityFlagscontrol which APIs are available. Use thecompat-date-attool to look up available flags and their enable dates.compatibilityDateshould not be used in wd-test; use specific flags instead
Module Types
modules = [
(name = "worker", esModule = embed "my-test.js"), # ES module (most common)
(name = "helper", esModule = embed "helper.js"), # Additional ES module
(name = "data.json", json = embed "test-data.json"), # JSON module
(name = "data.wasm", wasm = embed "module.wasm"), # WebAssembly module
(name = "legacy", commonJsModule = embed "legacy.js"), # CommonJS module
],
Bindings
Bindings make services, data, and namespaces available to the worker via env:
bindings = [
# Text binding — env.MY_TEXT is a string
(name = "MY_TEXT", text = "hello world"),
# Text from file
(name = "CERT", text = embed "fixtures/cert.pem"),
# Data binding — env.MY_DATA is an ArrayBuffer
(name = "MY_DATA", data = "base64encodeddata"),
# JSON binding — env.CONFIG is a parsed object
(name = "CONFIG", json = "{ \"key\": \"value\" }"),
# Service binding — env.OTHER_SERVICE is a fetch-able service
(name = "OTHER_SERVICE", service = "other-service-name"),
# Service binding with entrypoint
(name = "MY_RPC", service = (name = "my-service", entrypoint = "MyClass")),
# KV namespace — env.KV is a KV namespace
(name = "KV", kvNamespace = "kv-namespace-id"),
# Durable Object namespace — env.MY_DO is a DO namespace
(name = "MY_DO", durableObjectNamespace = "MyDurableObject"),
],
Test JavaScript Structure
Test files export named objects with a test() method:
// Each export becomes a separate test case
export const basicTest = {
test() {
// Synchronous test
assert.strictEqual(1 + 1, 2);
},
};
export const asyncTest = {
async test(ctrl, env) {
// ctrl is the test controller
// env contains bindings from the .wd-test config
const resp = await env.OTHER_SERVICE.fetch('http://example.com/');
assert.strictEqual(resp.status, 200);
},
};
BUILD.bazel Integration
wd_test(
src = "my-test.wd-test",
args = ["--experimental"], # Required for experimental features
data = ["my-test.js"], # Test JS/TS files
)
Additional data entries for fixture files:
wd_test(
src = "crypto-test.wd-test",
args = ["--experimental"],
data = [
"crypto-test.js",
"fixtures/cert.pem",
"fixtures/key.pem",
],
)
Test Variants
Every wd_test() automatically generates three variants:
| Target suffix | Compat date | Description |
|---|---|---|
@ | 2000-01-01 | Default, tests with oldest compat date |
@all-compat-flags | 2999-12-31 | Tests with all flags enabled |
@all-autogates | 2000-01-01 | Tests with all autogates enabled |
Run specific variants:
just stream-test //src/workerd/api/tests:my-test@
just stream-test //src/workerd/api/tests:my-test@all-compat-flags
Scaffolding
Use just new-test to scaffold a new test:
just new-test //src/workerd/api/tests:my-test
This creates the .wd-test file, .js test file, and appends the wd_test() rule to BUILD.bazel.
FAQ
What does the wd-test-format skill do?
Detailed guide for authoring .wd-test files in workerd, with examples of bindings, Durable Objects, multi-service configs, TypeScript tests, and network access.
How do I install wd-test-format?
Run npx skills add https://github.com/cloudflare/workerd --skill wd-test-format in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/wd-test-format/ (personal) or .claude/skills/wd-test-format/ (project).
Which AI agents can use wd-test-format?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is wd-test-format safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains wd-test-format?
It is published by cloudflare in cloudflare/workerd, and it is an official skill from the maker of the technology it covers. It has 46 recorded installs.
More from cloudflare/workerd
verification-before-completion
cloudflare/workerd
Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
rust-review
cloudflare/workerd
Open the skill to read its SKILL.md instructions.
dad-jokes
cloudflare/workerd
After completing any task that took more than 5 tool calls, or after long-running builds/tests finish, load this skill and deliver a dad joke to lighten the mood. Also load before any user-requested joke, pun, or limerick. Never improvise jokes without loading this skill first.
markdown-drafts
cloudflare/workerd
Use markdown formatting when drafting content intended for external systems (GitHub issues/PRs, Jira tickets, wiki pages, design docs, etc.) so formatting is preserved when the user copies it. Load this skill before producing any draft the user will paste elsewhere.
receiving-code-review
cloudflare/workerd
Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation
workerd-api-review
cloudflare/workerd
Performance optimization, API design & compatibility, security vulnerabilities, and standards spec compliance for workerd code review. Covers tcmalloc-aware perf analysis, compat flags, autogates, web standards adherence, and security patterns. Load this skill when reviewing API changes, performance-sensitive code, security-relevant code, or standards implementations.
Popular testing & qa skills
tdd
mattpocock/skills
Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.
grilling
mattpocock/skills
Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases.
migrate-to-shoehorn
mattpocock/skills
Migrate test files from as type assertions to @total-typescript/shoehorn. Use when user mentions shoehorn, wants to replace as in tests, or needs partial test data.
run-train
lllllllama/rigorpilot-skills
Rigor Train skill for deep learning research repositories. Use when a documented or selected training command should be run conservatively for startup verification, short-run verification, full kickoff, or resume, with command, config, seed, log, checkpoint, status, and metric evidence written to standardized trainoutputs/. Do not use for environment setup, exploratory sweeps, speculative idea implementation, or end-to-end orchestration.
test-driven-development
obra/superpowers
Use when implementing any feature or bugfix, before writing implementation code
finishing-a-development-branch
obra/superpowers
Use when implementation is complete, all tests pass, and you need to decide how to integrate the work