claw-code 源码分析：大型移植的测试哲学——如何用 unittest 门禁守住「诚实未完成」的口碑？

涉及源码tests/test_porting_workspace.py、src/setup.py、src/parity_audit.py、src/main.py、src/hooks/__init__.py、src/execution_registry.py对照 Rustrust/crates/compat-harness中「无夹具则早退」的测试写法。1. 门禁长什么样单一 discover 入口移植工作区的官方测试命令写死在WorkspaceSetup里与setup-report的「启动步骤」叙事一致# 12:26:src/setup.pydataclass(frozenTrue)classWorkspaceSetup:python_version:strimplementation:strplatform_name:strtest_command:strpython3 -m unittest discover -s tests -vdefstartup_steps(self)-tuple[str,...]:return(start top-level prefetch side effects,build workspace context,load mirrored command snapshot,load mirrored tool snapshot,prepare parity audit hooks,apply trust-gated deferred init,)tests/下目前只有test_porting_workspace.pyunittest discover会整包执行。哲学上门禁窄而可重复——不依赖 pytest 插件矩阵只用标准库降低「测框架比产品还重」的风险。2. 诚实未完成的核心archive_present条件门禁2.1 Parity有档案才严没档案不装完成run_parity_audit()用ARCHIVE_ROOT.exists()判定是否存在本地 TS 快照目录to_markdown()在缺失时明确声明无法对比# 84:88:src/parity_audit.pydefto_markdown(self)-str:lines[# Parity Audit]ifnotself.archive_present:lines.append(Local archive unavailable; parity audit cannot compare against the original snapshot.)return\n.join(lines)CLI 帮助文案同样写「在可用时」才对比避免暗示「clone 即全量 parity」subparsers.add_parser(parity-audit, helpcompare the Python workspace against the local ignored TypeScript archive when available)单测不把「必须有 archive」当作默认前提而是# 45:51:tests/test_porting_workspace.pydeftest_root_file_coverage_is_complete_when_local_archive_exists(self)-None:auditrun_parity_audit()ifaudit.archive_present:self.assertEqual(audit.root_file_coverage[0],audit.root_file_coverage[1])self.assertGreaterEqual(audit.directory_coverage[0],28)self.assertGreaterEqual(audit.command_entry_ratio[0],150)self.assertGreaterEqual(audit.tool_entry_ratio[0],100)语义无 archive该用例静默通过不伪造 green。有 archive根文件映射必须满覆盖目录/命令/工具条目数不低于约定阈值。这就是「诚实未完成」的 unittest 表达缺少上游对照物时不宣称 parity 已证明有时则收紧到可量化指标。2.2 与「永远 green」的虚假胜利划界若改成「无 archive 也 assert 比例」会把 CI 变成谎言若「有 archive 也不测」则档案形同虚设。当前写法是二态门禁环境具备对照条件时才验收结构覆盖率而不是验收业务等价后者在单测里基本未做。3. 黑盒子进程测「可运行 可观测契约」不测 TS 行为克隆PortingWorkspaceTests大量subprocess.run(..., checkTrue)调python -m src.main subcommand断言退出码 0与 stdout子串标题、关键词、模式串。效果诚实通过表示「CLI 面在当前仓库数据下能跑通」不表示「与原版 Ink/React 一致」。稳定子串契约比像素级 diff 快照更耐重构。覆盖面summary、parity-audit、route、bootstrap、exec、turn-loop、remote/ssh/teleport 模式、command-graph、tool-pool 等移植工作流被串成回归网。示例bootstrap 与 load-session 链# 104:174:tests/test_porting_workspace.pydeftest_bootstrap_cli_runs(self)-None:resultsubprocess.run([sys.executable,-m,src.main,bootstrap,review MCP tool,--limit,5],checkTrue,capture_outputTrue,textTrue,)self.assertIn(Runtime Session,result.stdout)...deftest_load_session_cli_runs(self)-None:fromsrc.runtimeimportPortRuntime sessionPortRuntime().bootstrap_session(review MCP tool,limit5)session_idPath(session.persisted_session_path).stem resultsubprocess.run([sys.executable,-m,src.main,load-session,session_id],checkTrue,capture_outputTrue,textTrue,)self.assertIn(session_id,result.stdout)self.assertIn(messages,result.stdout)口碑含义对外可以说「门禁保证port 脚手架与镜像数据自洽」而不是「已完整复刻产品」。4. 词汇诚实Mirrored、占位包与快照边界4.1 执行层命名ExecutionRegistry使用MirroredCommand/MirroredTool测试断言输出含「Mirrored command」/「Mirrored tool」# 9:24:src/execution_registry.pydataclass(frozenTrue)classMirroredCommand:name:strsource_hint:strdefexecute(self,prompt:str)-str:returnexecute_command(self.name,prompt).message# 123:137:tests/test_porting_workspace.pydeftest_exec_command_and_tool_cli_run(self)-None:...self.assertIn(Mirrored command review,command_result.stdout)self.assertIn(Mirrored tool MCPTool,tool_result.stdout)测试在巩固一种用户可见语义这是镜像/演示执行不是隐式冒充生产行为。4.2 子系统占位hooks包显式为placeholder元数据来自reference_dataJSON并导出PORTING_NOTEPython package placeholder for the archived hooks subsystem. ... PORTING_NOTE fPython placeholder package for {ARCHIVE_NAME} with {MODULE_COUNT} archived module references.单测通过MODULE_COUNT、SAMPLE_FILES等0断言验证「占位与快照挂钩」而非「hooks 已移植」。4.3 快照与清单测「规模与结构」不测语义test_command_and_tool_snapshots_are_nontrivialPORTED_COMMANDS/PORTED_TOOLS数量下限。test_manifest_counts_python_filestotal_python_files 20等粗阈值。test_execution_registry_runsregistry 规模 执行结果字符串包含镜像关键词。这些与reference_data/*.json、archive_surface_snapshot.json共同构成「表面对齐」的可测定义unittest 不把 undefined 的「行为 parity」塞进断言。5. 内联 API 测薄层不变量少量直接调用 Python APIQueryEnginePort.render_summary()、PortRuntime.bootstrap_session()检查结构字段如Prompt:、usage有消耗与 CLI 黑盒互补# 21:25:tests/test_porting_workspace.pydeftest_query_engine_summary_mentions_workspace(self)-None:summaryQueryEnginePort.from_workspace().render_summary()self.assertIn(Python Porting Workspace Summary,summary)self.assertIn(Command surface:,summary)self.assertIn(Tool surface:,summary)哲学内联测适合纯函数/聚合报告有副作用与 argv 的走子进程边界清晰。6. 与 Rust 侧的呼应可选对照compat-harness集成测试在缺少上游 fixture时直接 return与 Python「无 archive 不收紧」同构// 311:316:rust/crates/compat-harness/src/lib.rs#[test]fnextracts_non_empty_manifests_from_upstream_repo(){letpathsfixture_paths();if!has_upstream_fixture(paths){return;}说明「诚实未完成」在整个 monorepo 里是一种可复制的测试习惯缺输入就不宣称成功证明而不是skip刷屏或假失败。7. 小结unittest 如何守住口碑手法守住的承诺明确不承诺的if audit.archive_present条件断言「有快照时根文件映射与规模指标达标」「无快照也完成 TS 对齐」Parity 文案 CLI help「when available」对照物缺失时显式降级静默满分子进程 checkTrue 子串工作流与数据自洽、可演示与上游运行时行为逐行一致Mirrored*与占位包测试用户可见输出不自称为原版hooks/子系统已完整实现快照数量阈值表面命令/工具条目不萎缩每个条目语义已验证discover 标准库低依赖门禁易在任意环境复跑复杂属性测试/模糊测试一句话这套 unittest 把「我们保证什么」写成可执行契约能跑、有镜像词、有档案时结构对齐把「我们还没保证什么」留在条件分支与文档字符串里——这就是大型移植里诚实未完成的口碑工程化。