Skip to main content
workerd uses multiple test frameworks to ensure code quality and compatibility.

​
Running tests

​
Run all tests

bazel test //...

​
Run specific tests

You can target specific test files or packages: 
just test //src/workerd/api/tests:encoding-test@
The @ suffix is required in test target names. It indicates the default test variant.

​
Test types

​
.wd-test files

Cap’n Proto config files that define test workers with embedded JavaScript/TypeScript modules.
Example test
using Workerd = import "/workerd/workerd.capnp";

const unitTests :Workerd.Config = (
  services = [(
    name = "my-test",
    worker = (
      modules = [(name = "worker", esModule = embed "my-test.js")],
      compatibilityDate = "2024-01-01",
      compatibilityFlags = ["nodejs_compat"],
    ),
  )],
);
Key elements:
  • modules - Embed JS/TS test files
  • compatibilityFlags - Enable features
  • bindings - Service bindings, KV, JSON, etc.
  • durableObjectNamespaces - Durable Object configuration

​
C++ tests

KJ-based unit tests using the kj_test() macro: 
just test //src/workerd/io:io-gate-test@

​
Node.js compatibility tests

Test Node.js API compatibility: 
just node-test zlib
just node-test crypto

​
Web Platform Tests

Run WPT (Web Platform Tests): 
just wpt-test urlpattern
just wpt-test fetch

​
Test variants

Every test automatically generates three variants:
VariantDescription
name@Default variant with oldest compatibility date (2000-01-01)
name@all-compat-flagsNewest compatibility date (2999-12-31), all flags enabled
name@all-autogatesAll autogates enabled with oldest compatibility date
Use bazel query //src/workerd/api/tests:all to list all test targets in a package.

​
Creating new tests

​
Create a .wd-test

1

Create test files

Use the scaffolding command:
just new-test //src/workerd/api/tests:my-feature-test
2

Write your test

Edit the generated .wd-test file and JavaScript test file.
3

Run the test

just test //src/workerd/api/tests:my-feature-test@

​
Create a WPT test

just new-wpt-test myapi
This creates the test structure and opens it for editing.

​
Running tests with sanitizers

​
AddressSanitizer (ASAN)

Detect memory errors: 
just build-asan

​
Code coverage

Code coverage is only supported on Linux.
1

Install LLVM tools

sudo apt-get install llvm
If your distribution installs versioned binaries, create symlinks:
sudo ln -sf /usr/bin/llvm-profdata-19 /usr/local/bin/llvm-profdata
sudo ln -sf /usr/bin/llvm-cov-19 /usr/local/bin/llvm-cov
2

Run coverage

Generate coverage for all tests:
just coverage
Or for specific paths:
just coverage //src/workerd/api/...
3

View results

The just coverage command generates an HTML report automatically.Using Bazel directly:
bazel coverage //...

​
Finding test targets

To find the right target name for a file:
  1. Check the BUILD.bazel file in the same directory for wd_test() or kj_test() rules
  2. Use Bazel query:
bazel query //src/workerd/api/tests:all

​
Benchmarking

Run performance benchmarks: 
just bench mimetype

​
Continuous testing

Watch for changes and rerun tests automatically: 
just watch test //src/workerd/api/tests:encoding-test@

​
Next steps

Debugging

Learn to debug failing tests

Building

Build workerd from source

Build docs developers (and LLMs) love

Get started for freeTalk to us