コンテンツにスキップ

API

Wranglerは、Cloudflare Workersとプログラム的に対話するためのAPIを提供します。

  • unstable_dev - Workerに対してエンドツーエンド（e2e）または統合テストを実行するためのサーバーを起動します。
  • getPlatformProxy - Node.jsプロセス内でCloudflare Workersプラットフォームをエミュレートするためのプロキシと値を取得します。

unstable_dev

Workerのテスト用にHTTPサーバーを起動します。

呼び出されると、unstable_devはWorkerを呼び出すためのfetch()関数と、HTTPサーバーをシャットダウンするためのstop()関数を返します。アドレスやポートを知る必要はありません。

デフォルトでは、unstable_devはローカルサーバーに対して統合テストを実行します。プレビューWorkerに対してe2eテストを実行したい場合は、unstable_dev()関数を呼び出す際にoptionsオブジェクトにlocal: falseを渡してください。e2eテストは統合テストよりもかなり遅くなる可能性があります。

コンストラクタ

const worker = await unstable_dev(script, options)

パラメータ

  • script string

    • Workerスクリプトへのパスを含む文字列で、Workerプロジェクトのルートディレクトリに対して相対的です。

  • options object optional

    • wrangler devの設定を含むオプションのオプションオブジェクトです。
    • options内にexperimentalオブジェクトを含めて、disableExperimentalWarningなどの実験的機能にアクセスします。
      • disableExperimentalWarningをtrueに設定すると、unstable_プレフィックスのAPIを使用する際のWranglerの警告を無効にします。

戻り値の型

unstable_dev()は、以下のメソッドを含むオブジェクトを返します。

  • fetch() Promise<Response>

    • Workerにリクエストを送信します。Responseオブジェクトで解決されるPromiseを返します。
    • Fetchを参照してください。

  • stop() Promise<void>

    • 開発サーバーをシャットダウンします。

使用法

各テストスイートを開始する際には、beforeAll()関数を使用してunstable_dev()を起動します。beforeAll()関数はオーバーヘッドを最小限に抑えるために使用されます：開発サーバーの起動には数百ミリ秒かかり、各個別のテストごとに起動と停止を行うとすぐに時間がかかります。

各テストケースでは、await worker.fetch()を呼び出し、レスポンスが期待通りであることを確認します。

テストスイートを終了するには、afterAll関数内でawait worker.stop()を呼び出します。

シングルWorkerの例

const { unstable_dev } = require("wrangler");


describe("Worker", () => {
  let worker;


  beforeAll(async () => {
    worker = await unstable_dev("src/index.js", {
      experimental: { disableExperimentalWarning: true },
    });
  });


  afterAll(async () => {
    await worker.stop();
  });


  it("should return Hello World", async () => {
    const resp = await worker.fetch();
    const text = await resp.text();
    expect(text).toMatchInlineSnapshot(`"Hello World!"`);
  });
});

マルチWorkerの例

他のWorkerを呼び出すWorkerをテストできます。以下の例では、他のWorkerを呼び出すWorkerを親Workerと呼び、呼び出されるWorkerを子Workerと呼びます。

子Workerを早期にシャットダウンすると、親Workerは子Workerが存在することを知らず、テストが失敗します。

import { unstable_dev } from "wrangler";


describe("multi-worker testing", () => {
  let childWorker;
  let parentWorker;


  beforeAll(async () => {
    childWorker = await unstable_dev("src/child-worker.js", {
      config: "src/child-wrangler.toml",
      experimental: { disableExperimentalWarning: true },
    });
    parentWorker = await unstable_dev("src/parent-worker.js", {
      config: "src/parent-wrangler.toml",
      experimental: { disableExperimentalWarning: true },
    });
  });


  afterAll(async () => {
    await childWorker.stop();
    await parentWorker.stop();
  });


  it("childWorker should return Hello World itself", async () => {
    const resp = await childWorker.fetch();
    const text = await resp.text();
    expect(text).toMatchInlineSnapshot(`"Hello World!"`);
  });


  it("parentWorker should return Hello World by invoking the child worker", async () => {
    const resp = await parentWorker.fetch();
    const parsedResp = await resp.text();
    expect(parsedResp).toEqual("Parent worker sees: Hello World!");
  });
});

getPlatformProxy

getPlatformProxy関数は、プロキシ（ローカル workerdバインディング）とCloudflare Workers特有の値のエミュレーションを含むオブジェクトを取得する方法を提供し、Node.jsプロセス内でそれをエミュレートします。

プラットフォームプロキシを取得する一般的な使用例は、Workersをターゲットにしたアプリケーションでバインディングをエミュレートすることですが、Workersランタイムの外で実行される場合（例えば、Node.jsで実行されるフレームワークのローカル開発サーバー）や、テスト目的（例えば、コードがバインディングのタイプと適切に相互作用することを確認する）です。

構文

const platform = await getPlatformProxy(options);

パラメータ

  • options object optional

    • バインディングの設定を含むオプションのオプションオブジェクト：

      • environment string

        使用する環境。

      • configPath string

        使用する設定ファイルへのパス。

        パスが指定されていない場合、デフォルトの動作は、現在のディレクトリからファイルシステムを上に検索してwrangler.tomlを使用します。

        注意： このフィールドはオプションですが、パスが指定されている場合は、ファイルシステム上の有効なファイルを指す必要があります。

      • experimentalJsonConfig boolean

        trueの場合、ユーティリティがJSON設定ファイル（例えば、wrangler.json）を読み取ることを許可します。

      • persist boolean | { path: string }

        バインディングデータを永続化するかどうか、またはどこに永続化するかを示します。trueまたはundefinedの場合、Wranglerが使用するのと同じ場所にデフォルトされるため、データはそれと呼び出し元の間で共有できます。falseの場合、ファイルシステムにデータは永続化されず、読み取られません。

        注意： wranglerの--persist-toオプションを使用する場合、このオプションは内部でv3というサブディレクトリを追加しますが、getPlatformProxyのpersistはそうではありません。例えば、wrangler dev --persist-to ./my-directoryを実行する場合、getPlatformProxyを使用して同じ場所を再利用するには、persist: "./my-directory/v3"を指定する必要があります。

戻り値の型

getPlatformProxy()は、以下のフィールドを含むオブジェクトに解決されるPromiseを返します。

  • env Record<string, unknown>

    • 本番バインディングと同じ方法で使用できるバインディングへのプロキシを含むオブジェクトです。これは、モジュール形式のWorkerに対して第二引数として渡されるenvオブジェクトの形状に一致します。これらのプロキシはworkerd内で実行されるバインディング実装に接続します。
    • TypeScriptのヒント：getPlatformProxy<Env>()はジェネリック関数です。バインディングレコードの形状を型引数として渡すことで、unknown値なしで適切な型を取得できます。

  • cf IncomingRequestCfProperties read-only

    • 本番環境で見ることができるデータを含むRequestのcfプロパティのモック。

  • ctx object

  • caches object

    • Workers cachesランタイムAPIのエミュレーション。
    • 現時点では、すべてのキャッシュ操作は何もしません。より正確なエミュレーションが近日中に提供される予定です。

  • dispose() () => Promise<void>

    • 基本となるworkerdプロセスを終了します。
    • プログラムがもはやプラットフォームプロキシを必要としない場合は、これを呼び出します。開発サーバーのように、プロキシを無期限に利用できる長時間実行されるプロセスを実行している場合は、この関数を呼び出す必要はありません。

使用法

getPlatformProxy関数は、wrangler.tomlに見つかったバインディングを使用します。例えば、wrangler.tomlに以下のような環境変数設定がある場合：

[vars]
MY_VARIABLE = "test"

次のようにgetPlatformProxyをインポートすることで、バインディングにアクセスできます：

import { getPlatformProxy } from "wrangler";


const { env } = await getPlatformProxy();

MY_VARIABLEバインディングの値にアクセスするには、次のコードを追加します：

console.log(`MY_VARIABLE = ${env.MY_VARIABLE}`);

これにより、次の出力が表示されます：MY_VARIABLE = test。

サポートされているバインディング

wrangler.tomlに見つかったすべてのサポートされているバインディングは、envを介して利用可能です。

getPlatformProxyによってサポートされているバインディングは以下の通りです：

Cloudflare DashboardDiscordCommunityLearning CenterSupport Portal
Cookie Settings