CopilotKit 示例 E2E 测试体系实战指南基于 Playwright 的轻量冒烟测试架构【免费下载链接】CopilotKitThe Frontend Stack for Agents Generative UI. React, Angular, Mobile, Slack, and more. Makers of the AG-UI Protocol项目地址: https://gitcode.com/GitHub_Trending/co/CopilotKit导读本文围绕 CopilotKit 仓库中 examples/e2e/AGENTS.md 展开系统讲解仓库为examples/目录下所有示例应用搭建的端到端E2E冒烟测试体系包括测试框架的选取逻辑、Next.js 纯前端示例与UI Agent混合示例的区别化启动方式、本地运行命令、编写测试的规范以及 GitHub Actions 中的 CI 矩阵配置。读完本文你将掌握如何用EXAMPLE环境变量驱动 Playwright 逐个测试示例、如何为新增示例编写最小冒烟用例并接入 CI以及如何排查测试运行中的常见问题。一、这个 E2E 测试体系要解决什么问题examples/目录下存放着大量形态各异的示例应用既有纯 Next.js 前端应用也有附带 Python Agent 的混合应用。仓库选择用一套统一的 Playwright 测试工程来覆盖它们核心目标有三个见 examples/e2e/AGENTS.md提供一致的冒烟测试方式本地与 CI 使用同一套命令、同一套配置降低维护成本兼容多种示例形态Next-only 与UI Agent混合示例都能被同一套机制驱动保持测试轻量且稳定避免 flaky且不要求真实 API Key。从工程结构看这套测试位于 examples/e2e其 package.json 只依赖playwright/test、typescript和types/node三个包是一个完全独立、聚焦的冒烟测试工程不依赖示例自身的运行时代码。二、核心设计一次只测一个示例这套套件刻意设计为一次只运行一个示例。激活哪个示例由环境变量EXAMPLE决定未设置时默认回退到form-filling。这一逻辑在 playwright.config.ts 中体现得最为直接const EXAMPLE process.env.EXAMPLE ?? form-filling; const PORT Number(process.env.PORT ?? 3000); const HYBRID_EXAMPLES new Set([travel, research-canvas]); const webServerCommand HYBRID_EXAMPLES.has(EXAMPLE) ? pnpm dev:ui : pnpm dev; const exampleDir path.resolve(__dirname, ../v1, EXAMPLE);这里有几个值得注意的细节端口可配置默认端口 3000可通过PORT环境变量覆盖CI 中避免多任务撞端口示例目录解析示例统一存放在examples/v1/${EXAMPLE}下测试工程通过path.resolve从自身目录向上定位混合示例白名单travel与research-canvas属于混合示例其余按 Next-only 处理。playwright.config.ts随后用这些变量设置webServercwd指向所选示例目录command根据示例类型选择启动命令。为什么每个 spec 都要写const EXAMPLE process.env.EXAMPLE ?? form-filling;每个 spec 文件都带有一行门控代码例如 tests/v1.x/form-filling.spec.tsconst EXAMPLE process.env.EXAMPLE ?? form-filling;配合test.skip(EXAMPLE ! form-filling, ...)实现的效果是当运行某一个示例时只有匹配的 spec 会真正执行其余 spec 全部跳过。这样的好处是所有测试仍然集中在一个文件夹中但 CI 可以按每个示例一个 job跑矩阵互不干扰。三、两种示例类型Next-only 与 HybridNext.js-only 示例这类示例只包含前端直接用pnpm dev启动即可。以 examples/v1/form-filling/package.json 为例其dev脚本为next dev --turbopack测试框架只需等待这个命令就绪。Hybrid 示例UI Agenttravel和research-canvas同时带有 Python Agent。以 examples/v1/travel/package.json 为例{ dev: concurrently -k -n ui,agent -c blue,red \PORT3000 npm run dev:ui\ \PORT8000 npm run dev:agent\, dev:ui: next dev, dev:agent: cd agent uv run main.py }pnpm dev会用 concurrently 同时拉起 UI端口 3000和 Agent端口 8000。但对于 UI 冒烟测试通常只需要前端能启动即可因此 Playwright 配置对混合示例选择pnpm dev:ui从而避免在纯 UI 冒烟测试中启动 Python Agent既快又稳定。四、本地环境搭建与运行1. 安装测试工程依赖在examples/e2e目录下执行pnpm install pnpm exec playwright install --with-deps chromium--with-deps会顺带安装 Chromium 运行所需的系统库如果系统已具备这些库可只执行pnpm exec playwright install chromiumCI 正是采用这种精简方式原因见后文。2. 安装目标示例的依赖每个示例有自己的package.json需要在对应目录单独安装例如cd examples/v1/travel pnpm install注意事项如果示例的postinstall脚本依赖非 Node 工具链例如 Python 的uv而你又想要 CI 风格的行为可以改用pnpm install --ignore-scripts跳过这些钩子。3. 运行单个示例回到examples/e2e目录通过EXAMPLE环境变量指定目标EXAMPLEform-filling pnpm test EXAMPLEtravel pnpm test EXAMPLEresearch-canvas pnpm test EXAMPLEchat-with-your-data pnpm test EXAMPLEstate-machine pnpm test设置EXAMPLE后应当能看到结果为1 passed而其他示例的 spec 显示为skipped。五、测试布局与最小的冒烟用例长什么样测试统一放在 examples/e2e/tests/v1.x 目录下每个示例对应一个独立的冒烟 spec。目录中当前包含 7 个 spec 文件form-filling、travel、research-canvas、chat-with-your-data、state-machine以及两个针对聊天窗口布局的回归测试chat-window-layout。以 tests/v1.x/form-filling.spec.ts 为例冒烟用例保持最小化断言test.describe(form-filling, () { test.skip(EXAMPLE ! form-filling, EXAMPLE${EXAMPLE}); test(loads, async ({ page }) { await page.goto(/); await expect( page.getByRole(heading, { name: Security Incident Report }), ).toBeVisible(); await expect( page .getByRole(contentinfo) .filter({ hasText: /Powered by CopilotKit/i }) .first(), ).toBeVisible(); }); });可见规范要点使用getByRole等语义化选择器定位明显的标题/按钮断言只验证页面能加载、关键 UI 元素可见不涉及任何 LLM 交互。补充一个非典型spec——聊天窗口布局回归测试目录中还有 tests/v1.x/chat-window-layout.spec.ts它演示了冒烟测试之外的一种用法针对 1.55 版本回归的 flex 布局 bug 编写精确的 CSS 断言。它通过toHaveCSS(flex, 1 1 0%)、boundingBox()比较聊天消息区与窗口的高度占比、验证输入区位于窗口下半部、以及派发dragenter事件模拟拖拽态来锁定拖拽包装层无 class 导致聊天区塌陷这一历史问题。这说明该测试工程虽然以冒烟为主但也支持承载更精细的 UI 回归场景。六、编写冒烟测试的规范examples/e2e/AGENTS.md 对冒烟用例提出了三条铁律稳定Stable优先使用getByRole选择器以及显而易见的标题、按钮廉价Cheap不依赖 LLM 输出非侵入Non-invasive避免发送聊天消息或触发昂贵的后台工作。配套的固定写法test.skip(EXAMPLE ! example, ...) // 门控仅当 EXAMPLE 匹配时才执行 await expect(page).toHaveTitle(/.../); // 校验页面标题 await expect(page.getByRole(heading, { name: ... })).toBeVisible(); // 校验关键标题如果示例会自动弹出 Copilot UI 或触发调用建议增加一个查询参数来禁用该行为。travel示例就是典型其 app/page.tsx 会读取?copilotOpenfalse参数关闭聊天窗口因此对应 spec 通过page.goto(/?copilotOpenfalse)规避自动弹窗await page.goto(/?copilotOpenfalse); await expect(page).toHaveTitle(/CopilotKit Travel/i);七、CI 接入GitHub Actions 矩阵CI 工作流位于 .github/workflows/test_e2e-legacy-v1.yml核心是 5 个示例组成的矩阵form-fillingtravelresearch-canvaschat-with-your-datastate-machine工作流的 key 行为与 AGENTS.md 描述一致安装examples/e2e依赖和 Playwright Chromium安装所选示例自身的依赖使用pnpm install --frozen-lockfile保证安装可复现针对research-canvas以--ignore-scripts安装避免为了跑 UI 冒烟测试而要求 Python 工具链失败时总是上传Playwright 产物test-results与playwright-report保留 7 天用于排查。两个从仓库源码中确认的额外细节可以作为对 AGENTS.md 的补充浏览器安装刻意不加--with-deps。工作流注释说明--with-deps会调用apt在 runner 上可能长时间访问不到 Ubuntu 软件源导致超时烧掉整个 job 的预算而 runner 镜像已预装 Chromium 的系统库所以只执行pnpm exec playwright install chromium。使用 pnpm 的packageManager字段锁定版本。工作流特意省略version参数让pnpm/action-setup通过 corepack 继承仓库根 package.json 中声明的 pnpm 版本保证本地与 CI 工具链一致。此外工作流在Run e2e tests步骤中显式注入环境变量OPENAI_API_KEY: test、NEXT_PUBLIC_CPK_PUBLIC_API_KEY: 等与 Playwright 配置中的默认值对应确保 CI 环境里即使没有真实密钥也能完成 UI 冒烟。八、Playwright 配置细节速览playwright.config.ts 中还有若干值得留意的配置项testDir: ./tests、timeout: 60_000、expect.timeout: 10_000测试超时 60 秒断言等待最长 10 秒use.baseURL: http://127.0.0.1:${PORT}统一走本机回环地址避免 hostname 解析差异trace与video均设为retain-on-failure失败时保留 trace 与视频便于回放定位webServer.reuseExistingServer: !process.env.CI本地复用已启动的服务器加速迭代CI 中强制自建webServer.timeout: 180_000等待服务器就绪的上限为 3 分钟webServer.env在继承当前环境的基础上注入NEXT_TELEMETRY_DISABLED: 1关闭 Next.js 遥测、OPENAI_API_KEY: test占位密钥、REMOTE_ACTION_URL默认指向http://127.0.0.1:8000/copilotkit本地 Agent 服务只启用chromium一个 projectDesktop Chromereporter 在 CI 下用github本地用list。九、常见问题与调试examples/e2e/AGENTS.md 记录了三个高频问题next: command not found说明所选示例的node_modules未安装去示例目录执行pnpm install即可传递依赖 module not found如shiki将该依赖显式声明到示例的dependencies中并重新安装。仓库中form-filling、travel等示例的 package.json 均显式声明了shiki正是这一规范的实际落地Next.js 开发模式关于跨域allowedDevOrigins的警告当前按警告处理不影响测试通过。十、如何为新增示例接入这套体系AGENTS.md 给出了清晰的四步流程确保示例可通过pnpm devNext-only或pnpm dev:uiHybrid启动在tests/v1.x/下新增example.spec.ts沿用门控写法本地验证EXAMPLEexample pnpm test将示例名加入 CI 矩阵 .github/workflows/test_e2e-legacy-v1.yml。如果你要接入的是混合示例还需要同步把示例名加入 playwright.config.ts 的HYBRID_EXAMPLES集合否则框架会错误地使用pnpm dev启动连带拉起 Python Agent。这个集合是区分示例类型的唯一事实来源属于文档未显式强调但必须遵循的实现约束。结语CopilotKit 的这套 E2E 冒烟测试体系用一次一个示例 环境变量门控 CI 矩阵的简洁设计覆盖了形态差异巨大的数十个示例应用同时把稳定性、廉价性、非侵入性作为测试编写的基本纪律。对于想要为自己的多示例仓库搭建轻量冒烟测试的开发者examples/e2e 是一个结构清晰、开箱即用的参考模板。【免费下载链接】CopilotKitThe Frontend Stack for Agents Generative UI. React, Angular, Mobile, Slack, and more. Makers of the AG-UI Protocol项目地址: https://gitcode.com/GitHub_Trending/co/CopilotKit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考