Skip to main content
The test command runs tests for services defined in a workerd configuration. Tests are defined by exporting a test function in your worker code.

​
Usage

workerd test [config-file] [filter] [options]

​
Arguments

​
config-file
string
Path to the configuration file. Can be:
  • A Cap’n Proto text file (.capnp)
  • A binary Cap’n Proto file (with --binary flag)
​
filter
string
Specifies which tests to run. Has one of the following formats:
  • <service-pattern>: Match services by glob pattern
  • <service-pattern>:<entrypoint-pattern>: Match services and entrypoints
  • <const-name>:<service-pattern>:<entrypoint-pattern>: Specify config constant, services, and entrypoints
Default is *:* (all services, all entrypoints).Examples:
  • api-*: All services starting with “api-”
  • *:test*: All test entrypoints in all services
  • main:unit*: Unit tests in the “main” service

​
Options

​
Configuration parsing

​
-I, --import-path
<dir>
Add a directory to the list of directories searched for non-relative imports (imports starting with /).Can be specified multiple times.
​
-b, --binary
flag
Indicates that the configuration file is an encoded binary Cap’n Proto message rather than text format.

​
Service overrides

​
-d, --directory-path
<name>=<path>
Override the directory named <name> to point to <path> instead of the path specified in the config file.
​
-e, --external-addr
<name>=<addr>
Override the external service named <name> to connect to the address <addr> instead of the address specified in the config file.

​
Test behavior

​
--no-verbose
flag
Disable INFO-level logging. By default, INFO logging is enabled for tests to show uncaught exceptions.
​
--predictable
flag
Enable predictable mode. Makes workerd behave more deterministically by using pre-set values instead of random data or timestamps.Useful for snapshot testing and reproducible test runs.
workerd test config.capnp --predictable
​
--all-autogates
flag
Enable all autogates. Useful for testing code paths that are guarded by autogates.
workerd test config.capnp --all-autogates
​
--compat-date
<date>
Set the compatibility date for all workers. When specified, workers must NOT specify compatibilityDate in the config.Special values:
  • 0000-00-00: Oldest behavior
  • 9999-12-31: Newest behavior
workerd test config.capnp --compat-date 2024-01-01

​
Development features

​
-w, --watch
flag
Watch configuration files and automatically rerun tests when changes are detected.Tests will run once immediately, then again whenever changes are detected.
workerd test config.capnp --watch
​
-i, --inspector-addr
<addr>
Enable the Chrome DevTools inspector protocol on the specified address.
workerd test config.capnp --inspector-addr localhost:9229

​
Python support

​
--pyodide-package-disk-cache-dir
<path>
Use the specified path as a disk cache for Python packages.
​
--pyodide-bundle-disk-cache-dir
<path>
Use the specified path as a disk cache for Pyodide bundles.
​
--python-load-snapshot
<path>
Load a Python snapshot from the specified directory.
​
--python-snapshot-dir
<path>
Set the Python snapshot directory.

​
Advanced options

​
--experimental
flag
Permit the use of experimental features.
​
-p, --perfetto-trace
<path>=<categories>
Enable Perfetto tracing output to the specified file.

​
Writing tests

​
ES modules syntax

Export a test function from your worker: 
export default {
  async test(ctrl, env, ctx) {
    // Test passes if this function completes without throwing
    const result = await someFunction();
    if (result !== expected) {
      throw new Error('Test failed!');
    }
  }
}

​
Multiple tests

Export multiple entrypoints with test functions: 
export let test1 = {
  async test(ctrl, env, ctx) {
    // First test
  }
};

export let test2 = {
  async test(ctrl, env, ctx) {
    // Second test
  }
};

​
Test parameters

​
ctrl
TestController
Test controller (currently unused, reserved for future use).
​
env
Environment
Environment object containing bindings, same as in fetch handlers.
​
ctx
ExecutionContext
Execution context, same as in fetch handlers.

​
Loopback networking

The test command enables special “loopback:” network addresses for testing network communication within the same process: 
// In your test
const response = await fetch('http://loopback:my-service/path');
Loopback addresses allow end-to-end testing of the network stack without creating real external sockets. They are only available in test mode.

​
Examples

​
Run all tests

workerd test config.capnp

​
Run tests for specific service

workerd test config.capnp "api-service"

​
Run specific test entrypoint

workerd test config.capnp "*:unit-test"

​
Run tests with watch mode

workerd test config.capnp --watch

​
Run tests with predictable mode

workerd test config.capnp --predictable

​
Run with specific compatibility date

workerd test config.capnp --compat-date 2024-01-01

​
Run tests with filter and options

workerd test config.capnp "api-*:test*" --predictable --all-autogates

​
Test output

The test command provides clear output: 
[PASS] service-name:test1
[PASS] service-name:test2
[FAIL] service-name:test3
  Error: Test failed!
      at test (worker.js:10:15)

Tests: 2 passed, 1 failed, 3 total

​
Exit codes

  • 0: All tests passed
  • 1: One or more tests failed or configuration error
  • Other: System-specific error codes

​
Assertions

workerd does not include a built-in assertion library. You can:
  • Throw errors directly
  • Use conditional throws
  • Import an assertion library in your worker code
export default {
  async test(ctrl, env, ctx) {
    // Simple assertion
    if (1 + 1 !== 2) {
      throw new Error('Math is broken!');
    }
    
    // Custom assertion function
    function assertEquals(actual, expected, message) {
      if (actual !== expected) {
        throw new Error(message || `Expected ${expected}, got ${actual}`);
      }
    }
    
    assertEquals(await myFunction(), 42, 'Function should return 42');
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us