无极开物Docs

测试与 CI

测试层级、如何在本地运行，以及它们在 CI/发布流程中如何进行门禁把关。

测试分级（全仓库模型）

我们在脚本和 GitHub Actions 中始终统一使用这些测试流水线。

1) 单元测试

用于验证纯逻辑与组件行为的高速确定性测试。

根目录命令：

yarn test
yarn test:import-cycles

该命令将运行：

  • yarn workspace @Kaiwu-dev/self-hosting/protocol test
  • yarn workspace @Kaiwu-dev/transfers test
  • yarn workspace @Kaiwu-dev/agents test
  • yarn workspace @Kaiwu-dev/cli-common test
  • yarn workspace @Kaiwu-dev/connection-supervisor test
  • yarn workspace @Kaiwu-dev/app test
  • yarn workspace @Kaiwu-dev/cli test:unit
  • yarn --cwd apps/server test:unit
  • yarn --cwd packages/relay-server test
  • yarn --cwd apps/stack test:unit

CLI 单元测试流水线还会运行 CLI 运行时循环导入防护检查。若仅运行该检查：

yarn test:import-cycles

注意：UI 工作区包名为 @Kaiwu-dev/app，所在目录为 apps/ui。

2) 集成测试

应用级别的真实进程、文件系统与网络编排测试。

命名规范：

  • *.integration.test.*
  • *.integration.spec.*
  • *.real.integration.test.*

根目录命令：

yarn test:integration

该命令将运行：

  • yarn workspace @Kaiwu-dev/app test:integration
  • yarn workspace @Kaiwu-dev/cli test:integration
  • yarn --cwd apps/server test:integration
  • yarn --cwd apps/stack test:integration

3) 服务端数据库契约测试

仅针对服务端的契约测试套件，面向明确的数据库提供商运行（Docker 流水线中的 Postgres/MySQL）。

根目录命令：

yarn test:db-contract:docker

包内命令：

yarn --cwd apps/server test:db-contract

4) 核心端到端测试

位于 packages/tests 的端到端测试套件，针对真实的服务端/Socket 契约运行。

根目录命令：

yarn test:e2e
yarn test:e2e:core:fast
yarn test:e2e:core:slow
yarn test:e2e:core:embedded

流水线定位：

  • test:e2e / test:e2e:core = 核心测试全量门限。
  • test:e2e:core:fast = 默认本地闭环测试（排除了耗时最长的进程编排场景）。
  • test:e2e:core:slow = 耗时较长的场景（切换/物化/模式编排）。

核心端到端慢速测试命名规范：

  • *.slow.e2e.test.ts 文件仅在 test:e2e:core:slow 中运行。
  • 其他所有 suites/core-e2e/**/*.test.ts 文件均在 test:e2e:core:fast 中运行。
  • test:e2e 仍会运行全量核心套件（包含快速和慢速测试）。

4b) UI 端到端测试（Playwright）

基于浏览器的端到端测试，面向 Expo Web UI 运行，复用了与核心端到端测试相同的 server-light + 守护进程测试套具。

根目录命令：

yarn test:e2e:ui

注意事项：

  • 这些测试通过 Playwright 针对 expo start --web 运行，需要先安装 Playwright 浏览器环境（参见 Playwright 安装文档）。
  • UI 端到端测试规模应尽量精简，聚焦于必须由 UI 驱动的流程（鉴权/登录/连接、页面导航以及核心跨应用联动）。更底层的服务端/守护进程不变量测试应归入核心端到端测试。
  • 如果怀疑 Metro 转译结果陈旧，可通过 Kaiwu_E2E_EXPO_CLEAR=1 选择清理 Expo/Metro 缓存（默认关闭，因为 --clear 偶发会导致 Metro 崩溃）。
  • 人工 QA 提示：如果并发代码变更导致 UI 不断重新加载，可以在打开 UI 时附加 ?Kaiwu_hmr=0 参数，按浏览器标签页禁用 Expo Web 的快速刷新（Fast Refresh/HMR），重新启用请使用 ?Kaiwu_hmr=1。此功能仅限 Web 且仅限开发环境。

4c) 原生端到端测试（Maestro）（iOS/Android）

基于 Maestro 的原生端到端测试，用于覆盖移动端特有的回归问题（触摸、键盘、返回键、手势及弹窗渲染）。

根目录命令：

yarn test:e2e:mobile
yarn test:e2e:mobile:android
yarn test:e2e:mobile:ios

注意事项：

  • 这些流水线默认不作为 PR 检查项；在我们稳定 CI 模拟器运行之前，主要用于手动触发或发布验证。
  • 需要 Java 17+ 以及 iOS 模拟器或 Android 模拟器。
  • 为 Expo Dev Client 启动 Metro（Maestro 通过原生视图标识符定位 React Native testID）。
  • 设置目标服务器 URL（主机）：Kaiwu_E2E_SERVER_URL=http://127.0.0.1:⟦K20⟧。
    • Android 模拟器运行时会自动将 127.0.0.1/localhost 映射到 10.0.2.2，以确保设备网络可见。
  • 如果服务器或 Metro 运行在宿主设备上，请开启 adb reverse，以便 Android 能够访问它们：Kaiwu_E2E_ANDROID_ADB_REVERSE=1。
  • 构建产物将写入 packages/tests/.project/logs/e2e/mobile-maestro/ 目录下。
  • 覆盖 Maestro 二进制文件路径（如有需要）：Kaiwu_E2E_MAESTRO_BIN=/path/to/maestro。

4d) WSREPL Lima 矩阵测试（macOS/Linux 宿主设备）

Lima 宿主↔客户机 WSREPL 矩阵作为由测试模块自主维护的自选流水线对外提供。

根目录命令：

yarn test:e2e:ui:wsrepl:lima -- Kaiwu-wsrepl-qa

包内命令：

yarn workspace @Kaiwu-dev/tests test:ui:e2e:wsrepl:lima -- Kaiwu-wsrepl-qa

测试套具自测：

yarn test:e2e:ui:wsrepl:lima:self

注意事项：

  • 该流水线目前特意未纳入 GitHub 托管的默认 PR 矩阵。可在本地或已安装 Lima 的自托管 Runner 上使用。
  • tests 工作区现已接管该流水线的入口点、原始 WSREPL Lima 测试套具以及 Lima 引导助手：packages/tests/scripts/run-wsrepl-lima-matrix.mjs、packages/tests/scripts/wsrepl-lima-matrix.sh、packages/tests/scripts/lima-vm.sh。
  • 位于 apps/stack/scripts/provision/ 下的栈副本仅作为兼容垫片，不包含在发布的栈包中。
  • 请在 -- 之后传递虚拟机名称及现有的 WSREPL 环境变量覆盖项。包装脚本始终从 apps/stack/ 运行底层测试套具，因此现有的报告路径和相对脚本调用均保持稳定。

5) 提供商测试

位于 packages/tests 的提供商契约/基线测试套件（调用真实的提供商 CLI）。

根目录命令：

yarn test:providers
yarn test:providers:all:smoke
yarn test:providers:claude:extended
yarn test:providers:codex:smoke
yarn test:providers:opencode:extended

6) 压力测试

位于 packages/tests 的重复/混沌可靠性测试套件。

根目录命令：

yarn test:stress

7) 测试规范治理

仓库级别的治理检查，用于验证测试文件命名、流水线归属及特性标签的有效性。

根目录命令：

yarn test:import-cycles
yarn test:wiring:self
yarn test:wiring
yarn test:policy:self
yarn test:policy
yarn test:inventory
yarn test:migration:inventory

注意事项：

  • test:import-cycles 直接运行 CLI 运行时循环导入防护检查；yarn workspace @Kaiwu-dev/cli test:unit 也会运行该检查，因此根单元测试流水线与 CI 中的 CLI 单元测试任务都会强制执行该防护。
  • test:wiring:self 和 test:policy:self 是针对校验器本身的快速治理自测试。
  • 当存在无效的特性标签、明显的流水线命名错误以及根脚本/工作流/文档之间的一致性偏差时，test:wiring 将报错失败。
  • test:policy 当前仅强制执行安全、低误报的规则；其余可能产生较多噪音的规则仅生成报告，待仓库清理跟进后再行启用。
  • test:inventory 和 test:migration:inventory 仅用于生成报告。它们会输出流水线/包内覆盖率，并将治理清单产物写入 .project/testing/reports/governance/ 目录下。
  • 当前的分阶段落地计划如下：
    • enforce：.only、禁止从 @Kaiwu-dev/tests 内部进行运行时导入、根脚本/工作流/文档一致性
    • report-only：直接测试 console.*、直接 .skip/.todo、隐式跳过别名、已废弃的辅助函数导入、重复模式清单

7b) 仅包内提供的流水线

以下流水线特意未作为规范的根脚本暴露：

  • CLI 慢速流水线：yarn --cwd apps/cli test:slow
  • 网站测试：仅在 apps/website 下作为包内测试提供
  • 发布运行时测试：yarn --cwd packages/release-runtime test
  • 栈单元测试/集成测试/原生真实集成流水线：yarn --cwd apps/stack test:unit、yarn --cwd apps/stack test:integration 以及 apps/stack 中受防护的真实集成文件

8) 类型检查

针对主要运行时包（UI/CLI/服务端）的 TypeScript 类型检查。

根目录命令：

yarn typecheck

TypeScript 编译器归属

Kaiwu 的第一方类型检查与包构建流水线采用原生 TypeScript 7 编译器。针对尚不支持 TypeScript 7 原生 API 的 AST 工具及集成，typescript 包仍保留在 API 兼容的 5.9 版本线上。

编译器的选用统一收敛在 scripts/workspaces/typescriptCommand.mjs 中。各子包脚本均使用共享工作区运行器，而非裸 tsc 可执行文件，从而避免因依赖提升或包管理器 bin 链接顺序而隐式选中使用旧版编译器的 API 包。

为便于使用，仓库根目录以及每个包含 TypeScript 的工作区均定义了 yarn tsc ...。它会委托给同一个原生运行器，因而使用的是 TypeScript 7；系统仍不支持直接调用 tsc、npx tsc 和 typescript/bin/tsc。

9) 发布契约

针对工作流/安装/签名不变量的安全与发布流水线契约检查。

根目录命令：

yarn test:release:contracts

该命令将运行：

  • scripts/release/*.test.mjs
  • 包括安装程序同步、安全与发布不变量
  • 以及工作流策略防护，例如生产环境 Tauri 签名/公证失败熔断门限

10) 扩展数据库矩阵（Postgres/MySQL）

用于验证核心端到端测试与数据库契约测试在非嵌入式引擎上行为符合预期的可选检查。 在 CI 中，该检查通过包含服务容器的专用工作流运行。

本地命令：

yarn test:e2e:core:docker
yarn test:db-contract:docker

子包级流水线脚本

UI（apps/ui，工作区 @Kaiwu-dev/app）

  • 单元测试：yarn --cwd apps/ui test:unit
  • 集成测试：yarn --cwd apps/ui test:integration

CLI（apps/cli）

  • 单元测试：yarn --cwd apps/cli test:unit
  • 集成测试：yarn --cwd apps/cli test:integration
  • 仅慢速测试流水线：yarn --cwd apps/cli test:slow

服务端（apps/server）

  • 单元测试：yarn --cwd apps/server test:unit
  • 集成测试：yarn --cwd apps/server test:integration
  • 数据库契约测试：yarn --cwd apps/server test:db-contract

栈（apps/stack）

  • 单元测试：yarn --cwd apps/stack test:unit
  • 集成测试：yarn --cwd apps/stack test:integration

端到端工作区（packages/tests，工作区 @Kaiwu-dev/tests）

  • 核心（全量）：yarn workspace @Kaiwu-dev/tests test
  • 核心快速：yarn workspace @Kaiwu-dev/tests test:core:fast
  • 核心慢速：yarn workspace @Kaiwu-dev/tests test:core:slow
  • UI WSREPL Lima 矩阵（macOS/Linux 宿主设备）：yarn workspace @Kaiwu-dev/tests test:ui:e2e:wsrepl:lima -- Kaiwu-wsrepl-qa
  • 提供商：yarn workspace @Kaiwu-dev/tests test:providers
  • 压力测试：yarn workspace @Kaiwu-dev/tests test:stress

环境变量受控的集成测试套件

部分集成测试套件特意要求显式设置环境变量：

  • CLI 守护进程重新挂载/PID 安全性：Kaiwu_CLI_DAEMON_REATTACH_INTEGRATION=1
  • CI 中的 CLI tmux 集成路径：Kaiwu_CLI_TMUX_INTEGRATION=1

CI 会为相关任务自动配置这些变量。本地运行若需执行这些套件，可手动进行设置。

前置依赖矩阵

单元测试（yarn test）

  • 依赖：仅需 Node + Yarn。
  • 不应依赖 tmux、Docker、提供商 CLI 或 API 密钥。

集成测试（yarn test:integration）

  • UI 集成测试：
    • 依赖：Node + Yarn。
  • CLI 集成测试：
    • 依赖：Node + Yarn。
    • 可选的受控套件：
      • 需安装 Kaiwu_CLI_TMUX_INTEGRATION=1 和 tmux 以支持 *.real.integration.test.ts tmux 覆盖。
      • 需设置 Kaiwu_CLI_DAEMON_REATTACH_INTEGRATION=1 以运行真实 PID/重新挂载进程检查套件。
  • 服务端集成测试：
    • 依赖：Node + Yarn。
    • 常规集成测试流水线无需 Docker。
  • 栈集成测试：
    • 依赖：Node + Yarn，且 PATH 中必须包含 git。
    • 会启动真实的子进程，并验证进程归属与清理回收行为。

数据库契约测试（yarn --cwd apps/server test:db-contract）

  • 依赖：数据库提供商运行时（postgres/mysql）及相应的连接环境变量。
  • 基于 Docker 的辅助命令：
    • yarn test:db-contract:docker

核心端到端测试（yarn test:e2e、yarn test:e2e:core:embedded）

  • 依赖：Node + Yarn。
  • 通过 packages/tests 使用真实的服务端/Socket/运行时契约。
  • 不需要提供商 API 密钥。
  • 推荐的本地闭环流程：
    • 迭代开发期间运行 yarn test:e2e:core:fast。
    • 涉及较多编排逻辑变更时，在交接前运行 yarn test:e2e:core:slow。
    • 运行 yarn test:e2e 作为核心测试全量门限。

提供商测试套件（yarn test:providers、yarn test:providers:*）

  • 默认情况下，yarn test:providers 单独运行时会禁用提供商执行（未设置 Kaiwu_E2E_PROVIDERS），因此不需要提供商 CLI 或 API 密钥。
  • yarn test:providers:all:smoke / yarn test:providers:claude:extended（及类似的包装脚本）会启用真实的提供商执行，此时需要对应提供商的 CLI 或二进制文件。
  • 直接调用工作区命令（高级）：yarn workspace @Kaiwu-dev/tests providers:run ⟦K21⟧ ⟦K22⟧。
  • 鉴权模式由提供商规范驱动：
    • host 模式：使用本地已有的提供商 CLI 登录状态/会话（无需 API 密钥即可运行）。
    • env 模式：需要提供商规范声明的提供商密钥/凭据。
  • 实践指南：
    • smoke：最小场景级别，但通过 test:providers:* 包装脚本或 providers:run 运行时仍会执行真实的提供商调用。
    • extended：覆盖更多场景的更完整层级；在 CI 中通常会叠加环境变量密钥或 Secrets 运行。

真实的 Claude Agent Teams 探测（自选）

Kaiwu 内置了一个轻量级的自选探测程序，可通过运行本地安装的 claude CLI 来发现具体的 Agent Teams 工具名称并捕获典型载荷结构：

  • 测试文件：packages/tests/suites/providers/claude.agentTeams.toolNames.realProbe.test.ts

本地运行方式（要求宿主设备已安装 Claude Code 并完成身份认证）：

Kaiwu_TEST_REAL_CLAUDE=1 yarn -s workspace @Kaiwu-dev/tests test:providers claude.agentTeams.toolNames.realProbe.test.ts

扩展信号测试（会生成团队成员并发送消息，耗时可能更长）：

Kaiwu_TEST_REAL_CLAUDE=1 Kaiwu_TEST_REAL_CLAUDE_FULL=1 yarn -s workspace @Kaiwu-dev/tests test:providers claude.agentTeams.toolNames.realProbe.test.ts

压力测试（yarn test:stress）

  • 依赖：Node + Yarn。
  • 属于耗时较长的可靠性循环测试，请勿纳入 PR 默认本地闭环流程。

产物

核心端到端测试 / 提供商测试 / 压力测试会将每个测试的日志写入：

  • .project/logs/e2e/...

测试失败时，CI 会将此目录作为构建产物上传。

GitHub Actions（各任务运行分布）

默认 PR/推送门限

工作流：CI — Tests (.github/workflows/tests.yml)

默认门限包含：

  • 单元测试（共享工作区包 + 应用/单元测试流水线）
  • 集成测试（UI/CLI/服务端/栈应用流水线）
  • 治理校验器（test:wiring、test:policy，以及仅生成报告的清单命令）
  • 类型检查
  • 发布契约（发布/工作流/安装/签名防护）
  • 守护进程集成端到端测试（CLI + Server (light/sqlite) E2E）
  • 核心端到端快速测试（sqlite）

守护进程集成端到端测试任务特意与应用单元测试/集成测试流水线分离开来，因为它需要针对真实轻量级服务端进程验证跨包启动、鉴权与守护进程行为。

按需提供商契约测试

工作流：CI — Provider Contracts (.github/workflows/providers-contracts.yml)

所需密钥（Secrets）：

  • OPENAI_API_KEY（codex 和 opencode 所需）
  • ANTHROPIC_API_KEY（claude 所需）
  • CODEX_API_KEY（Codex 可选替代密钥，替代 OPENAI_API_KEY）

每夜压力测试

工作流：CI — Stress Tests (.github/workflows/stress-tests.yml)

每夜扩展数据库矩阵测试

工作流：CI — Extended DB Matrix (.github/workflows/extended-db-tests.yml)

贡献者指南

  1. 默认本地闭环流程：优先运行最小粒度的单元测试目标。
  2. 若测试需要真实的进程、文件系统或网络编排，应将其命名为集成测试，切勿放入单元测试流水线。
  3. 在交接前，针对所改动区域运行对应的应用/单元测试及应用/集成测试流水线。
  4. 若涉及协议、运行时、Socket 或数据库契约的变更，还需运行核心端到端测试。
© 乾元执中（南京）科技有限公司 · WUJI-Labs

参与贡献

构建 Kaiwu 本身——本地栈、测试及 CI 校验标准。

桌面端与 Web 端 QA

在需要手动验证设置与控制面板的变更时，驱动真实的 Tauri 窗口和一次性 Web 栈。

On this page

测试分级（全仓库模型）1) 单元测试2) 集成测试3) 服务端数据库契约测试4) 核心端到端测试4b) UI 端到端测试（Playwright）4c) 原生端到端测试（Maestro）（iOS/Android）4d) WSREPL Lima 矩阵测试（macOS/Linux 宿主设备）5) 提供商测试6) 压力测试7) 测试规范治理7b) 仅包内提供的流水线8) 类型检查TypeScript 编译器归属9) 发布契约10) 扩展数据库矩阵（Postgres/MySQL）子包级流水线脚本UI（apps/ui，工作区 @Kaiwu-dev/app）CLI（apps/cli）服务端（apps/server）栈（apps/stack）端到端工作区（packages/tests，工作区 @Kaiwu-dev/tests）环境变量受控的集成测试套件前置依赖矩阵单元测试（yarn test）集成测试（yarn test:integration）数据库契约测试（yarn --cwd apps/server test:db-contract）核心端到端测试（yarn test:e2e、yarn test:e2e:core:embedded）提供商测试套件（yarn test:providers、yarn test:providers:*）真实的 Claude Agent Teams 探测（自选）压力测试（yarn test:stress）产物GitHub Actions（各任务运行分布）默认 PR/推送门限按需提供商契约测试每夜压力测试每夜扩展数据库矩阵测试贡献者指南