wd-test-format

.wd-test 文件格式

.wd-test 文件是 Cap'n Proto 配置文件，用于为 workerd 的测试框架定义测试 worker。它们使用 src/workerd/server/workerd.capnp 中定义的架构。

---

必须：在相关时加载参考文件

此技能拆分为多个文件，以提高上下文效率。以下核心模式涵盖标准的单服务测试。高级配置模式位于参考文件中。

在编写或审查涉及参考文件所涵盖内容的测试配置之前，必须先阅读参考文件。不要猜测高级配置语法——参考文件包含所需的准确模式和字段。跳过这一步会导致配置错误，并在运行时失败。

文件	必须加载的情况
高级配置	测试涉及 Durable Objects、多个服务
	通过服务绑定进行通信、出站网络访问、
	外部服务/套接字或 TypeScript 源文件时

如果不确定参考文件是否相关，就加载它——阅读所花费的成本远低于测试配置损坏的代价。

---

基本结构

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"],
    ),
  )],
);

主要规则：

• const 名称（例如 unitTests）必须与测试运行器的预期一致
• modules 使用 embed 在构建时内嵌文件内容
• 第一个模块应命名为 "worker"——它是入口点
• compatibilityFlags 控制可用的 API。使用 compat-date-at 工具查询可用标志及其启用日期。
• 在 wd-test 中不应使用 compatibilityDate；请改用具体标志

模块类型

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
],

绑定

绑定通过 env 向 worker 提供服务、数据和命名空间：

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"),
],

测试 JavaScript 结构

测试文件会导出带有 test() 方法的具名对象：

// 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 集成

wd_test(
    src = "my-test.wd-test",
    args = ["--experimental"],      # Required for experimental features
    data = ["my-test.js"],          # Test JS/TS files
)

用于测试数据文件的其他 data 条目：

wd_test(
    src = "crypto-test.wd-test",
    args = ["--experimental"],
    data = [
        "crypto-test.js",
        "fixtures/cert.pem",
        "fixtures/key.pem",
    ],
)

测试变体

每个 wd_test() 都会自动生成三个变体：

目标后缀	兼容日期	描述
@	2000-01-01	默认，使用最早兼容日期进行测试
@all-compat-flags	2999-12-31	启用所有标志进行测试
@all-autogates	2000-01-01	启用所有自动门控进行测试

运行指定变体：

just stream-test //src/workerd/api/tests:my-test@
just stream-test //src/workerd/api/tests:my-test@all-compat-flags

脚手架

使用 just new-test 创建新测试的脚手架：

just new-test //src/workerd/api/tests:my-test

此命令会创建 .wd-test 文件和 .js 测试文件，并将 wd_test() 规则追加到 BUILD.bazel 中。