wd-test-format

.wd-test ファイル形式

.wd-test ファイルは、workerd のテストフレームワーク用のテストワーカーを定義する Cap'n Proto 設定です。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 経由でサービス、データ、名前空間をワーカーから利用できます。

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() は、自動的に次の 3 つのバリアントを生成します。

ターゲットサフィックス	Compat date	説明
@	2000-01-01	デフォルト。最も古い compat date でテストします
@all-compat-flags	2999-12-31	すべてのフラグを有効にしてテストします
@all-autogates	2000-01-01	すべての autogates を有効にしてテストします

特定のバリアントを実行します。

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 に追加されます。