尧图网站建设 
人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载本文是 Ironclaw面向隐私、安全与可扩展性的 Agent OS仓库内《Testing Playbook》的工程化解读与源码级扩充。它以测试优先为核心工作流为工程师回答三个实际问题某次改动该写什么测试、测试放在仓库的哪个位置、本地测试与 CI 各分层PR 反馈、合并队列、main、深度定时、发布产物如何对应。读完本文你将掌握 Ironclaw 的单元/契约测试、密闭HermeticReborn 集成测试、表面测试与实时金丝雀四种测试类型的选择方法、七个步骤的 TDD 工作流、以及覆盖率棘轮、Provider 能力覆盖、故障画像、Journey 清单等仓库级质量机制的用法。适用前提本文面向 Ironclaw 仓库含 Reborn 引擎的工程师。仓库与 crate 级指导如应用层的.claude/rules/testing.md在其更具体时仍然具有权威性跨层 Reborn 测试请先读 tests/integration/AGENTS.md。核心规则先写用户行为再写最小实现Ironclaw 的 TDD 核心规则只有一条从用户应该体验到的行为出发为该行为写一个测试然后实现让测试通过所需的最少代码。这并不意味着每个改动都要写满所有种类的测试。正确做法是依据行为本身及其风险来选择测试纯逻辑改动配单元测试跨组件行为配密闭集成测试模型选择行为配录制 fixture浏览器可见行为配 E2E真实模型/供应商行为配实时金丝雀。选择测试的过程本身就是一次风险分析。这一规则在仓库中有硬性呼应tests/integration/AGENTS.md 的Requirements expectations第一条即Test-first consolidate——先写/更新测试并看着它因正确原因失败能扩展现有测试就绝不新起一个冗余测试新增时还要说明理由。也就是说测试优先不仅是个人习惯也是集成测试层的书面约束。四种测试类型1. 单元 / 契约测试Unit or Contract Test单元或契约测试证明一条局部规则或一个 crate 拥有的公共契约。它适用于纯逻辑与校验例如拒绝非法的 cron 表达式类型化错误与状态转换隔离的缺陷修复由单一 crate 拥有的公共 API 或策略表例如调用者缺乏权限时拒绝某操作运行所属 crate 的测试cargo test -p OWNING_CRATE私有辅助函数放在实现旁边的#[cfg(test)] mod tests中保护公共契约的测试放在 crate 的tests/目录下见下文代码库示例。2. 密闭特性测试Hermetic Feature Test密闭特性测试证明一条完整的 Ironclaw 行为但不调用真实模型或外部服务——结果可重复、无需任何 API Key。Reborn 集成测试 harness 通过脚本化scripted供应商模型响应同时保留真实的产品工作流、调度器、Agent 循环、LLM 装饰器链、权限、能力与持久化在调用路径上。这是密闭hermetic一词的关键被替换的只有整条调用栈最底部的模型响应其余全部走真实代码路径。适用于大多数新增或修改的生产接线production-wiredReborn 行为cargo test --test reborn_integration_SCENARIO从源码结构看tests/integration/AGENTS.md 给出的调用链清晰地展示了唯一假点的位置submit_turn(text) ← 合成入站无 HTTP、无 Slack 解析 → product workflow → turn coordinator → scheduler → agent loop → LlmProviderModelGateway → 真实装饰器链透传 → 脚本化模型TraceLlm 喂入内存 trace ← 唯一的假 → turn 状态 助手回复持久化到 RootFilesystemInMemory assert_* 读取持久化的回复 / 状态假点必须放在真实apply_decorator_chain之下这样重试、智能路由、故障转移、熔断、响应缓存以及CompletionRequest 工具定义组装才会真实执行若在更上层gateway 处打桩则会跳过ironclaw_llm属于错误做法。3. 表面测试Surface Test表面测试通过改动所影响的外部表面证明行为。只选择相关的种类录制模型 fixtureRecorded model fixture模型必须选择某个特定工具或发送特定参数时使用。浏览器 E2E用户能在 WebUI 中看到或交互该行为时使用。后端或运行时集成行为依赖 PostgreSQL、libSQL、Docker、WASM、MCP 或其他运行时。许多纯本地改动并不需要表面测试——这是文档明确的取舍原则。4. 实时金丝雀Live Canary实时金丝雀对真实模型或供应商运行一个小场景用于发现模型漂移、供应商 API 变更、凭据失效与意外的提示词行为。金丝雀是补充性测试它绝不能是某个功能的唯一测试也不应让每个 PR 都等待金丝雀通过。确定性测试先过金丝雀殿后。如何选择测试五问决策法文档给出的决策清单一个改动可能命中多问例如 WebUI 审批功能可能需要同时具备密闭集成测试和浏览器测试用户能否在 WebUI 中看到或点击改动的行为→ 添加浏览器 E2E 测试。模型是否需要选择特定工具或参数→ 添加录制 fixture 与回放replay测试。行为是否跨越 Ironclaw 组件或执行副作用→ 添加密闭 Reborn 集成测试。改动是否只是局部逻辑→ 添加单元或契约测试。成功是否依赖真实模型或供应商的当前行为→ 在确定性测试通过后添加或运行实时金丝雀。逐步工作流七个步骤Step 1描述用户行为写一个简短的 Given/When/Then 示例描述可观察的结果而非内部函数调用。文档给出的范式Given 一个必须审批文件写入的用户当 Ironclaw 尝试写文件时那么该 turn 等待审批、审批前文件不存在、审批后文件存在。Step 2识别风险勾选适用的风险项它们决定需要哪些测试类型模型行为model behavior浏览器行为browser behavior副作用side effect持久化persistence安全或权限security or permissions外部供应商external provider跨组件行为cross-component behaviorStep 3选择最高层的确定性测试对大多数生产接线的 Reborn 行为从密闭 Reborn 集成测试开始。实时金丝雀可以是第一个被设计的场景但不应是第一个或唯一的自动化测试。Step 4让测试失败在实现功能之前运行测试确认它是因为行为缺失而失败而不是因为拼写错误或环境配置损坏。对缺陷修复测试必须复现原始 bug。Step 5写最小的修复只实现足以让测试通过的代码避免无关重构与投机性功能。Step 6补充重要边界用例在能改善诊断或保护重要规则时补充更小的测试非法输入缺少权限取消cancellation重复请求部分失败错误的用户或租户重启后的持久化不要在每一层测试里重复同一条 happy path。Step 7从快到慢运行测试单元与契约测试密闭 Reborn 集成测试录制 fixture 回放、浏览器 E2E 或后端/运行时集成实时金丝雀这保持了快速开发循环同时保留了由外到内的覆盖。本地测试如何映射到 CI文档强调一个关键区分测试类型回答要添加什么证据CI lane 回答证据何时运行。两者必须分开决策——一个浏览器测试不会因为改为 nightly 运行就变成金丝雀确定性的供应商 journey 即使在深度 lane 中被以更多顺序重复也仍然是密闭测试。Lane目的工程师应预期什么拉取请求反馈Pull request feedback对拟议改动给出快速、有范围的信号相关确定性子集、证据门禁evidence gates和变更代码检查可能在评审前运行合并队列Merge queue对合并结果的生产门禁队列覆盖的确定性检查以进入main前相同的形态运行路径范围由 workflow job 计算而非触发器过滤推送到main确认队列结果并发布共享证据重复队列覆盖的检查运行文档化的仅 post-merge 的 Windows、benchmark 与遗留快照检查预热缓存并发布报告深度定时Deep scheduled锻炼昂贵的广度更高的 property-test 计数、反向与隔离的 journey 顺序、突变审计、浏览器分片、压力、浸泡与实时漂移在常规合并门禁之外运行发布产物Release artifact验证将要真正发布的内容对构建的确切归档/二进制做冒烟测试而不是把开发构建当作发布证据权威的 workflow 契约、必需检查名称与调度细节位于 .github/workflows/README.md。其 Known accepted gaps 一节列出的确定性检查与信息性检查是故意不参与合并门禁的。修改 CI 之前先重新推导当前 lanerg -n pull_request:|merge_group:|push:|schedule:|workflow_dispatch: \ .github/workflows绿色的 PR 并不代表定时、实时、后端或发布层级跑过。在 PR 测试卡片中必须指名实际运行过的层级。这一点在 .github/workflows/README.md 中同样有硬约束任何确定性失败都不允许仅 main 出现——如果某个检查在 push 到 main 时确定性运行合并队列必须以相同形态先跑它merge_group不支持paths:过滤器需用changes作用域 job。测试归属位置行为位置说明私有辅助函数或纯局部规则crates/owning_crate/src/中的#[cfg(test)] mod tests测试紧邻实现公共 crate 契约crates/owning_crate/tests/behavior_contract.rs通过 crate 公共 API 测试完整 Reborn turn 或跨组件行为tests/integration/使用脚本化模型 harness在有意义的分界处断言模型工具选择或请求形态tests/fixtures/llm_traces/reborn_qa/与tests/reborn_qa_recorded_behavior.rs只提交清洗后的 fixtureWebUI 行为tests/e2e/scenarios/test_behavior.pyWebChat v2 使用 Reborn v2 fixtures数据库或运行时行为所属 crate 的 feature 门控集成套件或现有根集成套件覆盖受支持的生产后端真实模型或供应商漂移scripts/reborn_webui_v2_live_qa/尽量复用当前 live-QA lane代码库示例详解单元 / 契约测试锁定 WebChat v2 路由面示例crates/product/ironclaw_webui/tests/webui_v2_descriptors_contract.rs该契约锁定声明的 WebChat v2 路由面包括方法、路径、认证、请求体上限、限流、CORS、审计分类与允许的 effect 路径。从源码看它逐条比对webui_v2_routes()与一张期望表Expected结构体覆盖route_id、method、pattern、listener_class、auth_schemes、scope_source、body_limit、rate_limit_max/window/scope、cors、websocket_origin、streaming、audit、effect_path共 14 个字段host 组合层依赖这些描述符来挂载路由并施加 auth / CORS / 请求体上限 / 限流 / 审计中间件任何字段漂移都是 host 无法静默强制的行为变更。测试主体形态#[test] fn route_table_has_exactly_the_expected_routes() { let routes webui_v2_routes(); let expected expected_table(); assert_eq!( routes.len(), expected.len(), expected {} WebChat v2 routes, found {}, expected.len(), routes.len() ); }覆盖私有辅助函数时把类似测试内联保护公共契约或调用方面向行为时放入所属 crate 的tests/目录cargo test -p ironclaw_webui密闭 Reborn 集成greeting 冒烟简单示例tests/integration/greeting.rs该测试证明一条合成入站消息完整穿越产品工作流、调度、Agent 循环、真实 LLM 装饰器链与持久化的线程历史只有供应商模型响应被脚本化。代码注释标明它同时断言 turn 的两个分界输出分界的最终回复以及输入分界的模型可见系统提示T0-SYSPROMPTlet harness RebornIntegrationHarness::test_default() .script([RebornScriptedReply::text(Hello! How can I help?)]) .build() .await .expect(harness builds); harness .submit_turn(hi there) .await .expect(turn completes); harness .assert_reply_contains(Hello! How can I help?) .await .expect(reply finalized in thread history);对于独立场景在tests/integration/scenario.rs添加文件并在根Cargo.toml中注册扁平测试二进制为reborn_integration_scenario若与现有组共享昂贵初始化则加入组目录并从该组的main.rs引入模块而不是再建一个 harnesscargo test --test reborn_integration_greeting从 tests/integration/AGENTS.md 可以进一步看到 harness 的脚本纪律脚本是按模型调用计数的 FIFO而非按 turn 计数——普通回复 turn 用 1 条text(..)未门控的工具调用 turn 用 2 条tool_call(..) 执行后模型调用门控审批或认证的工具调用 turn 恰好 2 条无论门被批准或拒绝第三条会越界 FIFO 并静默泄漏进下一个 turn。存储模式默认InMemory可选.storage(StorageMode::LibSql)挂载真实 SQLite 完整 SQL 迁移与 CASassert_reply_persists_after_reopen(text)可证明回复在重启后存活。调用者路径副作用审批后文件真实落盘示例tests/integration/group_approvals/scenario_gate_then_approve.rs该场景驱动真实的审批与恢复路径并断言被批准的文件写入确实持久化了——而不是停在Completed状态或一个 mock 调用计数上let (run_id, gate_ref) h .submit_turn_until_blocked(write the approval file) .await?; h.approve_gate(run_id, gate_ref).await?; h.wait_for_status(run_id, TurnStatus::Completed).await?; h.assert_workspace_file_contains(approved.txt, approved write) .await?;源码注释进一步说明这条真实路径脚本化工具调用 → 第一方运行时 →PermissionMode::Ask且 auto-approve 关闭 →TurnStatus::BlockedApproval→approve_gate真实ApprovalResolver::approve_dispatch签发 lease→coordinator.resume_turn重新派发被门控的能力 → 模型最终回复 →Completed。它还内置了双重解决回归守卫对已Approved的门再次审批必须响亮失败NotPending而不是静默无操作或挂起。凡是辅助函数控制持久化、出站、派发、审批、密钥或其他副作用时都使用这种调用者路径形态cargo test --test reborn_group_approvals录制模型 fixture锁定模型的工具选择示例fixturetests/fixtures/llm_traces/reborn_qa/web_status_check.json契约与回放tests/reborn_qa_recorded_behavior.rs契约测试证明录制的模型响应选择了builtin.http且目标符合预期let trace load_qa_trace(WEB_STATUS_CHECK.fixture); assert_tool_called_with(trace, builtin.http, [api.github.com]);从 tests/reborn_qa_recorded_behavior.rs 的头部注释可以看到该机制分三层录制器测试#[ignore]需ANTHROPIC_API_KEY或NEARAI_API_KEY是唯一花费 token 的测试必须人工陪同运行并清洗 fixture 后提交、契约测试解析已提交 fixture钉住该短语下模型选择的能力与关键参数提示词或工具面变化会在下次重录时暴露为契约失败、回放测试通过RebornTraceReplayModelGateway::from_trace在真实 Reborn 运行时回放 fixture 并断言终态例如 routine 是否以正确 cron 真实存在。契约与回放测试是密闭的、在 CI 中运行录制器保持#[ignore]。工具选择与关键参数断言加入tests/reborn_qa_recorded_behavior.rs当 trace 应创建或修改持久状态时加入回放断言。实时录制器保持忽略契约与回放测试在 CI 中密闭运行scripts/ci/check-reborn-qa-fixtures.sh cargo test --test reborn_qa_recorded_behavior浏览器 E2E认证门禁与聊天壳示例tests/e2e/scenarios/test_reborn_webui_v2_smoke.py该测试启动独立的 Reborn 服务器证明已认证用户到达聊天壳、匿名用户到达登录屏async def test_reborn_v2_serves_shell_and_gates_auth( reborn_v2_server, reborn_v2_browser ): authed_ctx await reborn_v2_browser.new_context( viewport{width: 1280, height: 720} ) authed_page await authed_ctx.new_page() await authed_page.goto( f{reborn_v2_server}/?token{REBORN_V2_AUTH_TOKEN} ) await expect(authed_page.locator(SEL_V2[chat_composer])).to_be_visible()Reborn WebChat v2 使用reborn_v2_*fixtures 与SEL_V2选择器。若场景必须纳入 Reborn 覆盖门禁将其文件或 pytest node ID 加入 tests/e2e/reborn_coverage_tests.txt。源码头部注释补充了接线事实v2 SPA 与serve子命令无条件编译进ironclaw-reborn二进制LLM 由$IRONCLAW_REBORN_HOME/config.toml的[llm.default]选择内置openaiprovider 指向 mock 的base_urlIRONCLAW_REBORN_WEBUI_TOKEN必须 ≥ 32 字节兼任 SSO 会话签名密钥NO_PROXY/no_proxy必须覆盖 loopback 以免 provider 的 reqwest 客户端把 mock 请求路由进本地代理。cd tests/e2e pytest scenarios/test_reborn_webui_v2_smoke.py文档同时给出了浏览器层级背后的覆盖率棘轮体系合并后的 Reborn LCOV 报告强制执行三项互补棘轮聚合底线保留了更强的 85.11% post-process-journal 基线取代历史 80.81% 底线关键生产 crate 在 tests/integration/coverage-floor.toml 中有百分比与覆盖行底线新增的可插桩生产代码必须满足最初承诺的 90% 变更行底线变更分支覆盖仍在 LCOV 中要求并报告但无统一百分比底线分母来自 PR diff 与 LLVMDA/BRDA记录的交集而非手维护文件清单。变更代码豁免在 tests/integration/changed-coverage-exemptions.toml必须指名精确行号和/或分支行号加 owner、理由、issue 与未来复查日期不接受 glob 与整文件豁免测试模块与测试支持路径机械排除从 LCOV 完全缺失的生产源文件直接失败而非消失。分支 LCOV 导出使用--skip-functions变更代码门禁只消费行与分支记录钉住nightly-2025-11-01LLVM 21.1.3——更新版捆绑 LLVM 对异步泛型 Rust 存在已确认的分支映射崩溃因此覆盖专用编译器传递--ignore-rust-version并只引导当前依赖在 Rust 1.93 之后稳定下来的三个库特性array_windows、debug_closure_helpers、slice_as_array正常构建/clippy/测试 job 仍是权威的当前 MSRV 检查专用缓存键防止两个编译器对象混用。独立发布的ironclaw二进制在cargo llvm-cov下单独构建、由生产组合的 Python E2E 清单驱动、通过优雅关闭路径终止。数据库 / 运行时集成多后端 parity示例crates/loop/ironclaw_hooks/tests/parity_matrix.rs当多个后端必须实现同一行为契约时这是正确的形态。面向生产的持久化行为应同时覆盖 libSQL 与 PostgreSQL除非所属契约明确另有说明。优先使用所属 crate 的tests/目录承载单一存储或运行时契约行为跨组合层时使用现有 feature 门控的 crate 套件。绝不允许因为缺少 Docker 或 PostgreSQL 而静默从测试返回——使用文档化的 feature 门控或响亮、明确的 opt-outcargo test -p owning-crate --features integration # 例如 -p ironclaw_hooksworkspace 根 integration feature 为空实时金丝雀真实模型的端点状态检查示例实现scripts/reborn_webui_v2_live_qa/run_live_qa.pyworkflow.github/workflows/live-canary.yml现有qa_3b_endpoint_status_live_chat案例要求 Ironclaw 检查near.ai是否返回 HTTP 200 并验证当前状态被如实报告——源码 scripts/reborn_webui_v2_live_qa/run_live_qa.py 中可见其 prompt 为在 WebUI 中询问 check if near.ai returns a 200 status。新增或扩展案例放在scripts/reborn_webui_v2_live_qa/尽量复用现有reborn-webui-v2-live-qalane仅在案例需要新分片、密钥、调度或 lane 接线时才改 workflow。授权的维护者可以从 PR 运行单个案例/canary casesqa_3b_endpoint_status_live_chat保持突变隔离且可逆并清洗上传的产物。工作示例创建每小时检查网站的 routine场景用户要求 Ironclaw 创建一个每小时检查某个网站的 routine。可能的覆盖组合单元测试拒绝非法调度schedule。密闭集成测试脚本化 routine 创建的工具调用验证 routine 以正确调度被持久化。录制 fixture验证真实模型选择了 routine 工具并携带预期 URL 与调度。实时金丝雀让当前生产模型创建该 routine 并验证成功。浏览器测试在此没有必要——除非该功能改变了 routine 在 WebUI 中的呈现或行为。这正是按行为与风险选测试的直观示范同一功能在不同风险维度上各配一层证据而不是每层都重复同一条 happy path。PR 测试卡片PR 模板包含以下测试卡片请求评审前必须填完每一栏不得删除该节。对每个未使用的字段写Not applicable: 原因如果某预期测试层被省略用一句话说明理由### Test card User behavior: Risk areas: - [ ] Model behavior - [ ] Browser - [ ] Side effect - [ ] Persistence - [ ] Security or permissions - [ ] External provider - [ ] Cross-component behavior Tests added or updated: - Unit or contract: - Reborn integration: - Recorded fixture: - Browser E2E: - Backend or runtime: - Live canary: What the tests prove: Commands run:测试卡片与 CI 分层的对应关系在此闭合卡片里Commands run列出的层级就是实际被验证的层级绿色 PR 不等于定时/实时/后端/发布层级跑过。创建新测试文件之前的检查清单搜索是否已有测试驱动同一调用者或工作流有则扩展现有测试并说明理由。阅读所属 crate 的AGENTS.md、CLAUDE.md、CONTRACT.md或README.md。改动 Reborn 集成 harness 前先读 tests/integration/AGENTS.md。先写或更新测试确认它以预期原因失败。断言可观察的结果而不只是Completed状态或 mock 调用计数。开发时运行最窄的测试再按风险扩展。依赖或所有权边界变化时添加cargo test -p ironclaw_architecture_tests。Reborn 契约或整条路径行为变化时使用bash scripts/reborn-e2e-rust.sh。规则速记大多数生产改动需要单元/契约测试 一个密闭特性测试。每个可复现的缺陷修复都需要回归测试。测试真实结果写入的文件、持久化的记录、发出的事件、捕获的请求、执行的权限。涉及权限或副作用时通过真实调用者测试。只在模型行为重要时使用录制 fixture。只在浏览器行为重要时使用浏览器测试。金丝雀补充确定性测试绝不取代它们。已有测试覆盖同一工作流时优先扩展。Provider 能力覆盖按 outcome 计数而非按能力计数一个只有单条 happy path 用例通过的能力不算被覆盖。tests/e2e/provider_capability_inventory.py 中的门禁统计capability × outcome class并强制执行两条规则两者都来自随产品发布的 manifest而非手维护清单操作类型必需证据external_write一个带 provider 侧读回readback的ProviderOperationCase、一条integration_evidence条目或一条指名确切测试及其读回断言辅助函数的journey_evidence条目read一个outcome_class success的ProviderOperationCase以及一个outcome_class empty的ProviderOperationCase读/写切分来自每个工具的effects字段crates/extensions/packages/*/manifest.toml 中的external_write因此发布一个新工具会自动完成分类。被收割的工具调用名不是写入的证据。一条录制模型响应命名了slack__send_message只证明模型选择了该工具对 provider 是否真正提交了效果只字未提因此不能替代读回。这正是该规则的全部意义——文档记录的教训是在规则存在之前八个写能力仅凭录制工具调用名被分类为tested审计后发现其中两个google-sheets.write_values与google-sheets.rename_sheet唯一的 journey 是它们与append_values在同一张电子表格上被一并发出没有任何东西能单独隔离它们。outcome_class只覆盖每次操作的语义结果状态与传输失败属于下面的故障画像fault profiles不要在此重复。尚未满足规则的项进入 tests/e2e/fixtures/provider_capability_coverage.toml 的coverage_backlog携带 owner、理由、issue 与复查条件。它是一个棘轮当 backlog 条目点名的能力已被覆盖时门禁失败因此条目必须随工作落地而删除。Provider 故障画像Fault Profiles当 provider 操作必须穿越真实 Reborn 扩展与网络路径、同时 Emulate 保持权威 provider 状态时使用 tests/e2e/provider_fault_proxy.py。代理提供可复用的 HTTP、畸形响应、超时、连接重置与丢失确认lost-acknowledgement画像其账本只记录请求元数据、body 摘要与凭据指纹。按操作等价类应用画像而不是把每个 provider 操作与每种失败相乘。一个代表性读、幂等写与非幂等写必须断言模型可见结果、代理尝试次数、provider 是否收到请求、以及直接 provider 读回。丢失确认测试必须证明 provider 已提交而运行时未报告成功且没有发生盲目的重复请求。缺少凭据、凭据刷新与账号作用域行为保留在既有 auth/runtime 分界处当 provider 代理无法忠实构造该条件时。每个用例之后故障状态必须独立于 provider 状态重置。全路径 Journey 清单使用 tests/e2e/journey_types.py 与 tests/e2e/journey_cases.py 注册跨 ingress、执行、provider 状态与投递的代表性组合。JourneyCase是证据元数据不是工作流 DSL执行逻辑、provider 设置与读回留在各自拥有的测试模块中。每个 case 指名隔离的 provider 世界、ingress、执行 lane、投递目标、可观察断言与精确的 Pytest/Cargo 声明。Provider journey 还绑定其录制 trace、回放事实与定时实时证据产品 journey 在引用的测试确实断言时才可绑定精确投递地址与浏览器证据。不要凭意图填充可选字段只有被引用的测试真正断言它时才填写。test_journey_coverage.py验证证据仍然存在且可执行并从随产品发布的第一方 manifest 推导入站/出站通道表面——因此新增一个生产通道而没有代表性 journey 证据会使 CI 失败。每个受支持的 ingress 与投递机制优先一个代表性全路径 case不要用每个 provider 操作 × 每个 ingress 相乘也不要把 provider 专属断言塞进通用注册表。添加或更改 journey 后直接运行注册表门禁cd tests/e2e pytest scenarios/test_journey_coverage.py -q生成的生命周期与交互覆盖tests/e2e/state_machine_coverage.py 把 journeys、provider 操作、provider 故障与聚焦的 Reborn 集成测试投影到跨边界重要的生命周期维度上。它是一个证据清单不是第二个运行时状态机也不是笛卡尔积测试生成器。生产新增或更改以下项时更新它受支持的 ingress、认证、策略、操作、provider-outcome、生命周期或投递类触发、重试、取消、重复、重启或并发提交序列终态稳定性、至多一次效果、actor 隔离、如实不确定性或无孤儿资源不变式上述两个维度之间的高风险交互。优先投影现有JourneyCase、ProviderOperationCase或 provider 故障仅当没有现有注册表拥有该证据时才添加聚焦行并引用精确可执行的 Pytest 或 Cargo 声明只为组合行为风险高于任一单独维度的交互添加必需对。重新推导受支持的维度、序列、不变式与所选对然后运行 fail-loud 门禁rg -n \ SUPPORTED_DIMENSIONS|REQUIRED_EQUIVALENCE_PAIRS|SequenceClass|StateMachineInvariant \ tests/e2e/state_machine_coverage.py cd tests/e2e pytest scenarios/test_state_machine_coverage.py -q将失败提升为回归测试当生产、金丝雀或 QA 失败可复现时把它提升到能证明被破坏规则的最低确定性分界陈述用户可见失败与预期结果。提交任何 fixture 前移除凭据、个人数据、provider 标识符与无关 transcript 内容。用单元/契约、Reborn 集成、录制 fixture、provider 操作、journey 或浏览器测试复现失败。确认回归测试以原始原因失败。应用修复并确认同一测试通过。仅当真实模型或 provider 漂移仍是独立风险时才保留金丝雀。提交钩子与 .github/workflows/regression-test-check.yml 要求按惯例命名的修复与选定的高风险路径携带测试变更。[skip-regression-check]与对应 label 是评审可见的例外仅适用于真正不可行的场景——它不是可复现测试的替代品缺失的确定性分界与补偿证据必须在 PR 测试卡片中说明。突变审计测试断言覆盖证明代码跑过并不证明测试会检测出错误结果。当关键不变式、逃逸缺陷或可疑的过宽覆盖需要断言强度证据时使用突变审计。从单个文件或包开始分类每个可行存活者并对照未修改与遭破坏的代码验证real-gap修复./scripts/mutation-audit.sh -p OWNING_CRATE path/to/production.rs ./scripts/mutation-verify-fix.sh -p OWNING_CRATE \ copy the exact mutant string from the triage queue不要优化 workspace 级突变分数等价突变与不清晰的产品契约是显式结果广泛的突变工作属于定时前沿。环境隔离、裁决、验收标准与 fail-loud 自测遵循 docs/internal/mutation-audit.md。产品表面覆盖率报告Reborn E2E lane 以 JSON 与 Markdown 发布product-surface-coverage-sha。tests/e2e/product_surface_coverage.py 连接生产派生的能力清单、ProviderOperationCase、JourneyCase、代表性故障用例与既有 backlog——不要在报告代码中添加第二份手维护的能力或 journey 清单。五个证据轴是contract、journey、faults、browser与live。空的可选单元格如实报告缺失的生产分类或已测试但无任何可执行证据的能力会使 lane 失败已拥有的缺口、豁免与仅实时行保持醒目但不静默变成通过证据。被收割的 live-QA fixture 不是当前的实时证据除非稳定实时结果产物绑定回其类型化行定时实时单元格指名确切 workflow、job、case id 与结果产物并在消费者检查该结果之前保持scheduled。本地生成同一全景视图而不是维护独立的 capability/journey 电子表格cd tests/e2e python product_surface_coverage.py \ --json ../../artifacts/product-surface-coverage/matrix.json \ --markdown ../../artifacts/product-surface-coverage/matrix.md打开artifacts/product-surface-coverage/matrix.md查看人可读矩阵在 GitHub Actions 中从 Reborn E2E 运行下载product-surface-coverage-source-commit产物。外部仪表盘或 Notion 页面可以汇总或链接此报告但类型化注册表与生成的矩阵保持权威。小结把测试当作证据体系而非流程负担贯穿整个 playbook 的主线是Ironclaw 的测试体系是一套分层的证据体系——单元/契约测试证明局部规则密闭 Reborn 集成测试证明完整行为而不依赖真实模型表面测试只在相关时补上模型选择、浏览器与运行时维度金丝雀只在真实漂移是风险时殿后。选择测试的决策依据永远是行为与风险而 CI lane 只负责决定这些证据何时运行。配合覆盖率棘轮、能力 × outcome 计数、故障画像、Journey 清单、突变审计与产品表面报告这套体系把测试先行从一句口号变成了仓库内可执行的、带硬门禁的工程契约。赞分享人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载相关推荐IronClaw Reborn 测试体系实战从 Caller-first 覆盖到分层集成测试的完整指南IronClaw Reborn 测试体系实战从 Caller first 覆盖到分层集成测试的完整指南 导读 本文是 IronClaw一个以隐私、安全与可扩人工智能AI 应用交互助手AI AgentClaude技能宝库快速解锁1000免费AI自动化的终极指南Claude技能宝库快速解锁1000免费AI自动化的终极指南 你是否曾经想过如果Claude AI不仅能聊天还能帮你发送邮件、创建任务、分析数据甚至连AI 技能AI 插件人工智能工作流自动化IronClaw Reborn 集成测试分层实践在 vendor-SDK 缝合处打桩用真实全栈跑完整个 TurnIronClaw Reborn 集成测试分层实践在 vendor SDK 缝合处打桩用真实全栈跑完整个 Turn IronClaw 的 tests/inte人工智能AI 应用交互助手AI Agent上一篇如何用DeepWiki-Open打造智能文档生成器AI驱动的高效开发解决方案下一篇Ender3V2S1 3D打印机固件新手必学的配置优化指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Ironclaw 工程师 TDD 测试手册：四类测试、密闭 Reborn 集成与 CI 分层实践
人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载本文是 Ironclaw面向隐私、安全与可扩展性的 Agent OS仓库内《Testing Playbook》的工程化解读与源码级扩充。它以测试优先为核心工作流为工程师回答三个实际问题某次改动该写什么测试、测试放在仓库的哪个位置、本地测试与 CI 各分层PR 反馈、合并队列、main、深度定时、发布产物如何对应。读完本文你将掌握 Ironclaw 的单元/契约测试、密闭HermeticReborn 集成测试、表面测试与实时金丝雀四种测试类型的选择方法、七个步骤的 TDD 工作流、以及覆盖率棘轮、Provider 能力覆盖、故障画像、Journey 清单等仓库级质量机制的用法。适用前提本文面向 Ironclaw 仓库含 Reborn 引擎的工程师。仓库与 crate 级指导如应用层的.claude/rules/testing.md在其更具体时仍然具有权威性跨层 Reborn 测试请先读 tests/integration/AGENTS.md。核心规则先写用户行为再写最小实现Ironclaw 的 TDD 核心规则只有一条从用户应该体验到的行为出发为该行为写一个测试然后实现让测试通过所需的最少代码。这并不意味着每个改动都要写满所有种类的测试。正确做法是依据行为本身及其风险来选择测试纯逻辑改动配单元测试跨组件行为配密闭集成测试模型选择行为配录制 fixture浏览器可见行为配 E2E真实模型/供应商行为配实时金丝雀。选择测试的过程本身就是一次风险分析。这一规则在仓库中有硬性呼应tests/integration/AGENTS.md 的Requirements expectations第一条即Test-first consolidate——先写/更新测试并看着它因正确原因失败能扩展现有测试就绝不新起一个冗余测试新增时还要说明理由。也就是说测试优先不仅是个人习惯也是集成测试层的书面约束。四种测试类型1. 单元 / 契约测试Unit or Contract Test单元或契约测试证明一条局部规则或一个 crate 拥有的公共契约。它适用于纯逻辑与校验例如拒绝非法的 cron 表达式类型化错误与状态转换隔离的缺陷修复由单一 crate 拥有的公共 API 或策略表例如调用者缺乏权限时拒绝某操作运行所属 crate 的测试cargo test -p OWNING_CRATE私有辅助函数放在实现旁边的#[cfg(test)] mod tests中保护公共契约的测试放在 crate 的tests/目录下见下文代码库示例。2. 密闭特性测试Hermetic Feature Test密闭特性测试证明一条完整的 Ironclaw 行为但不调用真实模型或外部服务——结果可重复、无需任何 API Key。Reborn 集成测试 harness 通过脚本化scripted供应商模型响应同时保留真实的产品工作流、调度器、Agent 循环、LLM 装饰器链、权限、能力与持久化在调用路径上。这是密闭hermetic一词的关键被替换的只有整条调用栈最底部的模型响应其余全部走真实代码路径。适用于大多数新增或修改的生产接线production-wiredReborn 行为cargo test --test reborn_integration_SCENARIO从源码结构看tests/integration/AGENTS.md 给出的调用链清晰地展示了唯一假点的位置submit_turn(text) ← 合成入站无 HTTP、无 Slack 解析 → product workflow → turn coordinator → scheduler → agent loop → LlmProviderModelGateway → 真实装饰器链透传 → 脚本化模型TraceLlm 喂入内存 trace ← 唯一的假 → turn 状态 助手回复持久化到 RootFilesystemInMemory assert_* 读取持久化的回复 / 状态假点必须放在真实apply_decorator_chain之下这样重试、智能路由、故障转移、熔断、响应缓存以及CompletionRequest 工具定义组装才会真实执行若在更上层gateway 处打桩则会跳过ironclaw_llm属于错误做法。3. 表面测试Surface Test表面测试通过改动所影响的外部表面证明行为。只选择相关的种类录制模型 fixtureRecorded model fixture模型必须选择某个特定工具或发送特定参数时使用。浏览器 E2E用户能在 WebUI 中看到或交互该行为时使用。后端或运行时集成行为依赖 PostgreSQL、libSQL、Docker、WASM、MCP 或其他运行时。许多纯本地改动并不需要表面测试——这是文档明确的取舍原则。4. 实时金丝雀Live Canary实时金丝雀对真实模型或供应商运行一个小场景用于发现模型漂移、供应商 API 变更、凭据失效与意外的提示词行为。金丝雀是补充性测试它绝不能是某个功能的唯一测试也不应让每个 PR 都等待金丝雀通过。确定性测试先过金丝雀殿后。如何选择测试五问决策法文档给出的决策清单一个改动可能命中多问例如 WebUI 审批功能可能需要同时具备密闭集成测试和浏览器测试用户能否在 WebUI 中看到或点击改动的行为→ 添加浏览器 E2E 测试。模型是否需要选择特定工具或参数→ 添加录制 fixture 与回放replay测试。行为是否跨越 Ironclaw 组件或执行副作用→ 添加密闭 Reborn 集成测试。改动是否只是局部逻辑→ 添加单元或契约测试。成功是否依赖真实模型或供应商的当前行为→ 在确定性测试通过后添加或运行实时金丝雀。逐步工作流七个步骤Step 1描述用户行为写一个简短的 Given/When/Then 示例描述可观察的结果而非内部函数调用。文档给出的范式Given 一个必须审批文件写入的用户当 Ironclaw 尝试写文件时那么该 turn 等待审批、审批前文件不存在、审批后文件存在。Step 2识别风险勾选适用的风险项它们决定需要哪些测试类型模型行为model behavior浏览器行为browser behavior副作用side effect持久化persistence安全或权限security or permissions外部供应商external provider跨组件行为cross-component behaviorStep 3选择最高层的确定性测试对大多数生产接线的 Reborn 行为从密闭 Reborn 集成测试开始。实时金丝雀可以是第一个被设计的场景但不应是第一个或唯一的自动化测试。Step 4让测试失败在实现功能之前运行测试确认它是因为行为缺失而失败而不是因为拼写错误或环境配置损坏。对缺陷修复测试必须复现原始 bug。Step 5写最小的修复只实现足以让测试通过的代码避免无关重构与投机性功能。Step 6补充重要边界用例在能改善诊断或保护重要规则时补充更小的测试非法输入缺少权限取消cancellation重复请求部分失败错误的用户或租户重启后的持久化不要在每一层测试里重复同一条 happy path。Step 7从快到慢运行测试单元与契约测试密闭 Reborn 集成测试录制 fixture 回放、浏览器 E2E 或后端/运行时集成实时金丝雀这保持了快速开发循环同时保留了由外到内的覆盖。本地测试如何映射到 CI文档强调一个关键区分测试类型回答要添加什么证据CI lane 回答证据何时运行。两者必须分开决策——一个浏览器测试不会因为改为 nightly 运行就变成金丝雀确定性的供应商 journey 即使在深度 lane 中被以更多顺序重复也仍然是密闭测试。Lane目的工程师应预期什么拉取请求反馈Pull request feedback对拟议改动给出快速、有范围的信号相关确定性子集、证据门禁evidence gates和变更代码检查可能在评审前运行合并队列Merge queue对合并结果的生产门禁队列覆盖的确定性检查以进入main前相同的形态运行路径范围由 workflow job 计算而非触发器过滤推送到main确认队列结果并发布共享证据重复队列覆盖的检查运行文档化的仅 post-merge 的 Windows、benchmark 与遗留快照检查预热缓存并发布报告深度定时Deep scheduled锻炼昂贵的广度更高的 property-test 计数、反向与隔离的 journey 顺序、突变审计、浏览器分片、压力、浸泡与实时漂移在常规合并门禁之外运行发布产物Release artifact验证将要真正发布的内容对构建的确切归档/二进制做冒烟测试而不是把开发构建当作发布证据权威的 workflow 契约、必需检查名称与调度细节位于 .github/workflows/README.md。其 Known accepted gaps 一节列出的确定性检查与信息性检查是故意不参与合并门禁的。修改 CI 之前先重新推导当前 lanerg -n pull_request:|merge_group:|push:|schedule:|workflow_dispatch: \ .github/workflows绿色的 PR 并不代表定时、实时、后端或发布层级跑过。在 PR 测试卡片中必须指名实际运行过的层级。这一点在 .github/workflows/README.md 中同样有硬约束任何确定性失败都不允许仅 main 出现——如果某个检查在 push 到 main 时确定性运行合并队列必须以相同形态先跑它merge_group不支持paths:过滤器需用changes作用域 job。测试归属位置行为位置说明私有辅助函数或纯局部规则crates/owning_crate/src/中的#[cfg(test)] mod tests测试紧邻实现公共 crate 契约crates/owning_crate/tests/behavior_contract.rs通过 crate 公共 API 测试完整 Reborn turn 或跨组件行为tests/integration/使用脚本化模型 harness在有意义的分界处断言模型工具选择或请求形态tests/fixtures/llm_traces/reborn_qa/与tests/reborn_qa_recorded_behavior.rs只提交清洗后的 fixtureWebUI 行为tests/e2e/scenarios/test_behavior.pyWebChat v2 使用 Reborn v2 fixtures数据库或运行时行为所属 crate 的 feature 门控集成套件或现有根集成套件覆盖受支持的生产后端真实模型或供应商漂移scripts/reborn_webui_v2_live_qa/尽量复用当前 live-QA lane代码库示例详解单元 / 契约测试锁定 WebChat v2 路由面示例crates/product/ironclaw_webui/tests/webui_v2_descriptors_contract.rs该契约锁定声明的 WebChat v2 路由面包括方法、路径、认证、请求体上限、限流、CORS、审计分类与允许的 effect 路径。从源码看它逐条比对webui_v2_routes()与一张期望表Expected结构体覆盖route_id、method、pattern、listener_class、auth_schemes、scope_source、body_limit、rate_limit_max/window/scope、cors、websocket_origin、streaming、audit、effect_path共 14 个字段host 组合层依赖这些描述符来挂载路由并施加 auth / CORS / 请求体上限 / 限流 / 审计中间件任何字段漂移都是 host 无法静默强制的行为变更。测试主体形态#[test] fn route_table_has_exactly_the_expected_routes() { let routes webui_v2_routes(); let expected expected_table(); assert_eq!( routes.len(), expected.len(), expected {} WebChat v2 routes, found {}, expected.len(), routes.len() ); }覆盖私有辅助函数时把类似测试内联保护公共契约或调用方面向行为时放入所属 crate 的tests/目录cargo test -p ironclaw_webui密闭 Reborn 集成greeting 冒烟简单示例tests/integration/greeting.rs该测试证明一条合成入站消息完整穿越产品工作流、调度、Agent 循环、真实 LLM 装饰器链与持久化的线程历史只有供应商模型响应被脚本化。代码注释标明它同时断言 turn 的两个分界输出分界的最终回复以及输入分界的模型可见系统提示T0-SYSPROMPTlet harness RebornIntegrationHarness::test_default() .script([RebornScriptedReply::text(Hello! How can I help?)]) .build() .await .expect(harness builds); harness .submit_turn(hi there) .await .expect(turn completes); harness .assert_reply_contains(Hello! How can I help?) .await .expect(reply finalized in thread history);对于独立场景在tests/integration/scenario.rs添加文件并在根Cargo.toml中注册扁平测试二进制为reborn_integration_scenario若与现有组共享昂贵初始化则加入组目录并从该组的main.rs引入模块而不是再建一个 harnesscargo test --test reborn_integration_greeting从 tests/integration/AGENTS.md 可以进一步看到 harness 的脚本纪律脚本是按模型调用计数的 FIFO而非按 turn 计数——普通回复 turn 用 1 条text(..)未门控的工具调用 turn 用 2 条tool_call(..) 执行后模型调用门控审批或认证的工具调用 turn 恰好 2 条无论门被批准或拒绝第三条会越界 FIFO 并静默泄漏进下一个 turn。存储模式默认InMemory可选.storage(StorageMode::LibSql)挂载真实 SQLite 完整 SQL 迁移与 CASassert_reply_persists_after_reopen(text)可证明回复在重启后存活。调用者路径副作用审批后文件真实落盘示例tests/integration/group_approvals/scenario_gate_then_approve.rs该场景驱动真实的审批与恢复路径并断言被批准的文件写入确实持久化了——而不是停在Completed状态或一个 mock 调用计数上let (run_id, gate_ref) h .submit_turn_until_blocked(write the approval file) .await?; h.approve_gate(run_id, gate_ref).await?; h.wait_for_status(run_id, TurnStatus::Completed).await?; h.assert_workspace_file_contains(approved.txt, approved write) .await?;源码注释进一步说明这条真实路径脚本化工具调用 → 第一方运行时 →PermissionMode::Ask且 auto-approve 关闭 →TurnStatus::BlockedApproval→approve_gate真实ApprovalResolver::approve_dispatch签发 lease→coordinator.resume_turn重新派发被门控的能力 → 模型最终回复 →Completed。它还内置了双重解决回归守卫对已Approved的门再次审批必须响亮失败NotPending而不是静默无操作或挂起。凡是辅助函数控制持久化、出站、派发、审批、密钥或其他副作用时都使用这种调用者路径形态cargo test --test reborn_group_approvals录制模型 fixture锁定模型的工具选择示例fixturetests/fixtures/llm_traces/reborn_qa/web_status_check.json契约与回放tests/reborn_qa_recorded_behavior.rs契约测试证明录制的模型响应选择了builtin.http且目标符合预期let trace load_qa_trace(WEB_STATUS_CHECK.fixture); assert_tool_called_with(trace, builtin.http, [api.github.com]);从 tests/reborn_qa_recorded_behavior.rs 的头部注释可以看到该机制分三层录制器测试#[ignore]需ANTHROPIC_API_KEY或NEARAI_API_KEY是唯一花费 token 的测试必须人工陪同运行并清洗 fixture 后提交、契约测试解析已提交 fixture钉住该短语下模型选择的能力与关键参数提示词或工具面变化会在下次重录时暴露为契约失败、回放测试通过RebornTraceReplayModelGateway::from_trace在真实 Reborn 运行时回放 fixture 并断言终态例如 routine 是否以正确 cron 真实存在。契约与回放测试是密闭的、在 CI 中运行录制器保持#[ignore]。工具选择与关键参数断言加入tests/reborn_qa_recorded_behavior.rs当 trace 应创建或修改持久状态时加入回放断言。实时录制器保持忽略契约与回放测试在 CI 中密闭运行scripts/ci/check-reborn-qa-fixtures.sh cargo test --test reborn_qa_recorded_behavior浏览器 E2E认证门禁与聊天壳示例tests/e2e/scenarios/test_reborn_webui_v2_smoke.py该测试启动独立的 Reborn 服务器证明已认证用户到达聊天壳、匿名用户到达登录屏async def test_reborn_v2_serves_shell_and_gates_auth( reborn_v2_server, reborn_v2_browser ): authed_ctx await reborn_v2_browser.new_context( viewport{width: 1280, height: 720} ) authed_page await authed_ctx.new_page() await authed_page.goto( f{reborn_v2_server}/?token{REBORN_V2_AUTH_TOKEN} ) await expect(authed_page.locator(SEL_V2[chat_composer])).to_be_visible()Reborn WebChat v2 使用reborn_v2_*fixtures 与SEL_V2选择器。若场景必须纳入 Reborn 覆盖门禁将其文件或 pytest node ID 加入 tests/e2e/reborn_coverage_tests.txt。源码头部注释补充了接线事实v2 SPA 与serve子命令无条件编译进ironclaw-reborn二进制LLM 由$IRONCLAW_REBORN_HOME/config.toml的[llm.default]选择内置openaiprovider 指向 mock 的base_urlIRONCLAW_REBORN_WEBUI_TOKEN必须 ≥ 32 字节兼任 SSO 会话签名密钥NO_PROXY/no_proxy必须覆盖 loopback 以免 provider 的 reqwest 客户端把 mock 请求路由进本地代理。cd tests/e2e pytest scenarios/test_reborn_webui_v2_smoke.py文档同时给出了浏览器层级背后的覆盖率棘轮体系合并后的 Reborn LCOV 报告强制执行三项互补棘轮聚合底线保留了更强的 85.11% post-process-journal 基线取代历史 80.81% 底线关键生产 crate 在 tests/integration/coverage-floor.toml 中有百分比与覆盖行底线新增的可插桩生产代码必须满足最初承诺的 90% 变更行底线变更分支覆盖仍在 LCOV 中要求并报告但无统一百分比底线分母来自 PR diff 与 LLVMDA/BRDA记录的交集而非手维护文件清单。变更代码豁免在 tests/integration/changed-coverage-exemptions.toml必须指名精确行号和/或分支行号加 owner、理由、issue 与未来复查日期不接受 glob 与整文件豁免测试模块与测试支持路径机械排除从 LCOV 完全缺失的生产源文件直接失败而非消失。分支 LCOV 导出使用--skip-functions变更代码门禁只消费行与分支记录钉住nightly-2025-11-01LLVM 21.1.3——更新版捆绑 LLVM 对异步泛型 Rust 存在已确认的分支映射崩溃因此覆盖专用编译器传递--ignore-rust-version并只引导当前依赖在 Rust 1.93 之后稳定下来的三个库特性array_windows、debug_closure_helpers、slice_as_array正常构建/clippy/测试 job 仍是权威的当前 MSRV 检查专用缓存键防止两个编译器对象混用。独立发布的ironclaw二进制在cargo llvm-cov下单独构建、由生产组合的 Python E2E 清单驱动、通过优雅关闭路径终止。数据库 / 运行时集成多后端 parity示例crates/loop/ironclaw_hooks/tests/parity_matrix.rs当多个后端必须实现同一行为契约时这是正确的形态。面向生产的持久化行为应同时覆盖 libSQL 与 PostgreSQL除非所属契约明确另有说明。优先使用所属 crate 的tests/目录承载单一存储或运行时契约行为跨组合层时使用现有 feature 门控的 crate 套件。绝不允许因为缺少 Docker 或 PostgreSQL 而静默从测试返回——使用文档化的 feature 门控或响亮、明确的 opt-outcargo test -p owning-crate --features integration # 例如 -p ironclaw_hooksworkspace 根 integration feature 为空实时金丝雀真实模型的端点状态检查示例实现scripts/reborn_webui_v2_live_qa/run_live_qa.pyworkflow.github/workflows/live-canary.yml现有qa_3b_endpoint_status_live_chat案例要求 Ironclaw 检查near.ai是否返回 HTTP 200 并验证当前状态被如实报告——源码 scripts/reborn_webui_v2_live_qa/run_live_qa.py 中可见其 prompt 为在 WebUI 中询问 check if near.ai returns a 200 status。新增或扩展案例放在scripts/reborn_webui_v2_live_qa/尽量复用现有reborn-webui-v2-live-qalane仅在案例需要新分片、密钥、调度或 lane 接线时才改 workflow。授权的维护者可以从 PR 运行单个案例/canary casesqa_3b_endpoint_status_live_chat保持突变隔离且可逆并清洗上传的产物。工作示例创建每小时检查网站的 routine场景用户要求 Ironclaw 创建一个每小时检查某个网站的 routine。可能的覆盖组合单元测试拒绝非法调度schedule。密闭集成测试脚本化 routine 创建的工具调用验证 routine 以正确调度被持久化。录制 fixture验证真实模型选择了 routine 工具并携带预期 URL 与调度。实时金丝雀让当前生产模型创建该 routine 并验证成功。浏览器测试在此没有必要——除非该功能改变了 routine 在 WebUI 中的呈现或行为。这正是按行为与风险选测试的直观示范同一功能在不同风险维度上各配一层证据而不是每层都重复同一条 happy path。PR 测试卡片PR 模板包含以下测试卡片请求评审前必须填完每一栏不得删除该节。对每个未使用的字段写Not applicable: 原因如果某预期测试层被省略用一句话说明理由### Test card User behavior: Risk areas: - [ ] Model behavior - [ ] Browser - [ ] Side effect - [ ] Persistence - [ ] Security or permissions - [ ] External provider - [ ] Cross-component behavior Tests added or updated: - Unit or contract: - Reborn integration: - Recorded fixture: - Browser E2E: - Backend or runtime: - Live canary: What the tests prove: Commands run:测试卡片与 CI 分层的对应关系在此闭合卡片里Commands run列出的层级就是实际被验证的层级绿色 PR 不等于定时/实时/后端/发布层级跑过。创建新测试文件之前的检查清单搜索是否已有测试驱动同一调用者或工作流有则扩展现有测试并说明理由。阅读所属 crate 的AGENTS.md、CLAUDE.md、CONTRACT.md或README.md。改动 Reborn 集成 harness 前先读 tests/integration/AGENTS.md。先写或更新测试确认它以预期原因失败。断言可观察的结果而不只是Completed状态或 mock 调用计数。开发时运行最窄的测试再按风险扩展。依赖或所有权边界变化时添加cargo test -p ironclaw_architecture_tests。Reborn 契约或整条路径行为变化时使用bash scripts/reborn-e2e-rust.sh。规则速记大多数生产改动需要单元/契约测试 一个密闭特性测试。每个可复现的缺陷修复都需要回归测试。测试真实结果写入的文件、持久化的记录、发出的事件、捕获的请求、执行的权限。涉及权限或副作用时通过真实调用者测试。只在模型行为重要时使用录制 fixture。只在浏览器行为重要时使用浏览器测试。金丝雀补充确定性测试绝不取代它们。已有测试覆盖同一工作流时优先扩展。Provider 能力覆盖按 outcome 计数而非按能力计数一个只有单条 happy path 用例通过的能力不算被覆盖。tests/e2e/provider_capability_inventory.py 中的门禁统计capability × outcome class并强制执行两条规则两者都来自随产品发布的 manifest而非手维护清单操作类型必需证据external_write一个带 provider 侧读回readback的ProviderOperationCase、一条integration_evidence条目或一条指名确切测试及其读回断言辅助函数的journey_evidence条目read一个outcome_class success的ProviderOperationCase以及一个outcome_class empty的ProviderOperationCase读/写切分来自每个工具的effects字段crates/extensions/packages/*/manifest.toml 中的external_write因此发布一个新工具会自动完成分类。被收割的工具调用名不是写入的证据。一条录制模型响应命名了slack__send_message只证明模型选择了该工具对 provider 是否真正提交了效果只字未提因此不能替代读回。这正是该规则的全部意义——文档记录的教训是在规则存在之前八个写能力仅凭录制工具调用名被分类为tested审计后发现其中两个google-sheets.write_values与google-sheets.rename_sheet唯一的 journey 是它们与append_values在同一张电子表格上被一并发出没有任何东西能单独隔离它们。outcome_class只覆盖每次操作的语义结果状态与传输失败属于下面的故障画像fault profiles不要在此重复。尚未满足规则的项进入 tests/e2e/fixtures/provider_capability_coverage.toml 的coverage_backlog携带 owner、理由、issue 与复查条件。它是一个棘轮当 backlog 条目点名的能力已被覆盖时门禁失败因此条目必须随工作落地而删除。Provider 故障画像Fault Profiles当 provider 操作必须穿越真实 Reborn 扩展与网络路径、同时 Emulate 保持权威 provider 状态时使用 tests/e2e/provider_fault_proxy.py。代理提供可复用的 HTTP、畸形响应、超时、连接重置与丢失确认lost-acknowledgement画像其账本只记录请求元数据、body 摘要与凭据指纹。按操作等价类应用画像而不是把每个 provider 操作与每种失败相乘。一个代表性读、幂等写与非幂等写必须断言模型可见结果、代理尝试次数、provider 是否收到请求、以及直接 provider 读回。丢失确认测试必须证明 provider 已提交而运行时未报告成功且没有发生盲目的重复请求。缺少凭据、凭据刷新与账号作用域行为保留在既有 auth/runtime 分界处当 provider 代理无法忠实构造该条件时。每个用例之后故障状态必须独立于 provider 状态重置。全路径 Journey 清单使用 tests/e2e/journey_types.py 与 tests/e2e/journey_cases.py 注册跨 ingress、执行、provider 状态与投递的代表性组合。JourneyCase是证据元数据不是工作流 DSL执行逻辑、provider 设置与读回留在各自拥有的测试模块中。每个 case 指名隔离的 provider 世界、ingress、执行 lane、投递目标、可观察断言与精确的 Pytest/Cargo 声明。Provider journey 还绑定其录制 trace、回放事实与定时实时证据产品 journey 在引用的测试确实断言时才可绑定精确投递地址与浏览器证据。不要凭意图填充可选字段只有被引用的测试真正断言它时才填写。test_journey_coverage.py验证证据仍然存在且可执行并从随产品发布的第一方 manifest 推导入站/出站通道表面——因此新增一个生产通道而没有代表性 journey 证据会使 CI 失败。每个受支持的 ingress 与投递机制优先一个代表性全路径 case不要用每个 provider 操作 × 每个 ingress 相乘也不要把 provider 专属断言塞进通用注册表。添加或更改 journey 后直接运行注册表门禁cd tests/e2e pytest scenarios/test_journey_coverage.py -q生成的生命周期与交互覆盖tests/e2e/state_machine_coverage.py 把 journeys、provider 操作、provider 故障与聚焦的 Reborn 集成测试投影到跨边界重要的生命周期维度上。它是一个证据清单不是第二个运行时状态机也不是笛卡尔积测试生成器。生产新增或更改以下项时更新它受支持的 ingress、认证、策略、操作、provider-outcome、生命周期或投递类触发、重试、取消、重复、重启或并发提交序列终态稳定性、至多一次效果、actor 隔离、如实不确定性或无孤儿资源不变式上述两个维度之间的高风险交互。优先投影现有JourneyCase、ProviderOperationCase或 provider 故障仅当没有现有注册表拥有该证据时才添加聚焦行并引用精确可执行的 Pytest 或 Cargo 声明只为组合行为风险高于任一单独维度的交互添加必需对。重新推导受支持的维度、序列、不变式与所选对然后运行 fail-loud 门禁rg -n \ SUPPORTED_DIMENSIONS|REQUIRED_EQUIVALENCE_PAIRS|SequenceClass|StateMachineInvariant \ tests/e2e/state_machine_coverage.py cd tests/e2e pytest scenarios/test_state_machine_coverage.py -q将失败提升为回归测试当生产、金丝雀或 QA 失败可复现时把它提升到能证明被破坏规则的最低确定性分界陈述用户可见失败与预期结果。提交任何 fixture 前移除凭据、个人数据、provider 标识符与无关 transcript 内容。用单元/契约、Reborn 集成、录制 fixture、provider 操作、journey 或浏览器测试复现失败。确认回归测试以原始原因失败。应用修复并确认同一测试通过。仅当真实模型或 provider 漂移仍是独立风险时才保留金丝雀。提交钩子与 .github/workflows/regression-test-check.yml 要求按惯例命名的修复与选定的高风险路径携带测试变更。[skip-regression-check]与对应 label 是评审可见的例外仅适用于真正不可行的场景——它不是可复现测试的替代品缺失的确定性分界与补偿证据必须在 PR 测试卡片中说明。突变审计测试断言覆盖证明代码跑过并不证明测试会检测出错误结果。当关键不变式、逃逸缺陷或可疑的过宽覆盖需要断言强度证据时使用突变审计。从单个文件或包开始分类每个可行存活者并对照未修改与遭破坏的代码验证real-gap修复./scripts/mutation-audit.sh -p OWNING_CRATE path/to/production.rs ./scripts/mutation-verify-fix.sh -p OWNING_CRATE \ copy the exact mutant string from the triage queue不要优化 workspace 级突变分数等价突变与不清晰的产品契约是显式结果广泛的突变工作属于定时前沿。环境隔离、裁决、验收标准与 fail-loud 自测遵循 docs/internal/mutation-audit.md。产品表面覆盖率报告Reborn E2E lane 以 JSON 与 Markdown 发布product-surface-coverage-sha。tests/e2e/product_surface_coverage.py 连接生产派生的能力清单、ProviderOperationCase、JourneyCase、代表性故障用例与既有 backlog——不要在报告代码中添加第二份手维护的能力或 journey 清单。五个证据轴是contract、journey、faults、browser与live。空的可选单元格如实报告缺失的生产分类或已测试但无任何可执行证据的能力会使 lane 失败已拥有的缺口、豁免与仅实时行保持醒目但不静默变成通过证据。被收割的 live-QA fixture 不是当前的实时证据除非稳定实时结果产物绑定回其类型化行定时实时单元格指名确切 workflow、job、case id 与结果产物并在消费者检查该结果之前保持scheduled。本地生成同一全景视图而不是维护独立的 capability/journey 电子表格cd tests/e2e python product_surface_coverage.py \ --json ../../artifacts/product-surface-coverage/matrix.json \ --markdown ../../artifacts/product-surface-coverage/matrix.md打开artifacts/product-surface-coverage/matrix.md查看人可读矩阵在 GitHub Actions 中从 Reborn E2E 运行下载product-surface-coverage-source-commit产物。外部仪表盘或 Notion 页面可以汇总或链接此报告但类型化注册表与生成的矩阵保持权威。小结把测试当作证据体系而非流程负担贯穿整个 playbook 的主线是Ironclaw 的测试体系是一套分层的证据体系——单元/契约测试证明局部规则密闭 Reborn 集成测试证明完整行为而不依赖真实模型表面测试只在相关时补上模型选择、浏览器与运行时维度金丝雀只在真实漂移是风险时殿后。选择测试的决策依据永远是行为与风险而 CI lane 只负责决定这些证据何时运行。配合覆盖率棘轮、能力 × outcome 计数、故障画像、Journey 清单、突变审计与产品表面报告这套体系把测试先行从一句口号变成了仓库内可执行的、带硬门禁的工程契约。赞分享人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载相关推荐IronClaw Reborn 测试体系实战从 Caller-first 覆盖到分层集成测试的完整指南IronClaw Reborn 测试体系实战从 Caller first 覆盖到分层集成测试的完整指南 导读 本文是 IronClaw一个以隐私、安全与可扩人工智能AI 应用交互助手AI AgentClaude技能宝库快速解锁1000免费AI自动化的终极指南Claude技能宝库快速解锁1000免费AI自动化的终极指南 你是否曾经想过如果Claude AI不仅能聊天还能帮你发送邮件、创建任务、分析数据甚至连AI 技能AI 插件人工智能工作流自动化IronClaw Reborn 集成测试分层实践在 vendor-SDK 缝合处打桩用真实全栈跑完整个 TurnIronClaw Reborn 集成测试分层实践在 vendor SDK 缝合处打桩用真实全栈跑完整个 Turn IronClaw 的 tests/inte人工智能AI 应用交互助手AI Agent上一篇如何用DeepWiki-Open打造智能文档生成器AI驱动的高效开发解决方案下一篇Ender3V2S1 3D打印机固件新手必学的配置优化指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考