测试你的 Agent

由于 Agents 运行在 Cloudflare Workers 与 Durable Objects 之上,可以使用与 Workers 和 Durable Objects 相同的工具与技术来测试它们。

编写并运行测试

准备工作

注意

agents-starter 模板与新的 Cloudflare Workers 项目已经包含相关的 vitest 与 @cloudflare/vitest-pool-workers 包,以及一个有效的 vitest.config.js 文件。

在编写第一个测试之前,先安装必要的包:

Terminal window

npm install vitest@~3.0.0 --save-dev --save-exact

npm install @cloudflare/vitest-pool-workers --save-dev

确保你的 vitest.config.js 与下面一致:

JavaScript

import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";


export default defineWorkersConfig({

  test: {

    poolOptions: {

      workers: {

        wrangler: { configPath: "./wrangler.jsonc" },

      },

    },

  },

});

Explain Code

添加 Agent 配置

在 vitest.config.js 中添加 durableObjects 配置,使用你的 Agent 类的名字:

JavaScript

import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";


export default defineWorkersConfig({

  test: {

    poolOptions: {

      workers: {

        main: "./src/index.ts",

        miniflare: {

          durableObjects: {

            NAME: "MyAgent",

          },

        },

      },

    },

  },

});

Explain Code

编写测试

注意

更多关于测试的信息,包括测试 API 参考与高级技巧,请查阅 Vitest 文档 ↗。

测试使用 vitest 框架。一个基础的 Agent 测试套件不仅可以验证 Agent 对请求的响应,还能对 Agent 的方法和状态做单元测试。

TypeScript

import {

  env,

  createExecutionContext,

  waitOnExecutionContext,

  SELF,

} from "cloudflare:test";

import { describe, it, expect } from "vitest";

import worker from "../src";

import { Env } from "../src";


interface ProvidedEnv extends Env {}


describe("make a request to my Agent", () => {

  // Unit testing approach

  it("responds with state", async () => {

    // Provide a valid URL that your Worker can use to route to your Agent

    // If you are using routeAgentRequest, this will be /agent/:agent/:name

    const request = new Request<unknown, IncomingRequestCfProperties>(

      "http://example.com/agent/my-agent/agent-123",

    );

    const ctx = createExecutionContext();

    const response = await worker.fetch(request, env, ctx);

    await waitOnExecutionContext(ctx);

    expect(await response.text()).toMatchObject({ hello: "from your agent" });

  });


  it("also responds with state", async () => {

    const request = new Request("http://example.com/agent/my-agent/agent-123");

    const response = await SELF.fetch(request);

    expect(await response.text()).toMatchObject({ hello: "from your agent" });

  });

});

Explain Code

运行测试

使用 vitest CLI 运行测试:

Terminal window

$ npm run test

# or run vitest directly

$ npx vitest

  MyAgent

    ✓ should return a greeting (1 ms)


Test Files  1 passed (1)

更多示例与测试配置请查阅 测试相关文档。

在本地运行 Agent

你也可以使用 wrangler CLI 在本地运行 Agent:

Terminal window

$ npx wrangler dev

Your Worker and resources are simulated locally via Miniflare. For more information, see: https://developers.cloudflare.com/workers/testing/local-development.


Your worker has access to the following bindings:

- Durable Objects:

  - MyAgent: MyAgent

  Starting local server...

[wrangler:inf] Ready on http://localhost:53645

它会启动一个本地开发服务器,运行与 Cloudflare Workers 相同的运行时,让你可以在不部署的情况下迭代并测试 Agent 代码。

详见 wrangler dev ↗ 文档,了解 CLI 参数与配置选项。