Hunk 测试体系全解：跨模块、跨进程与终端边界的分层测试布局与命令指南

开发工具代码评审CLIAI 应用【免费下载链接】hunkReview-first terminal diff viewer for agentic coders项目地址https://gitcode.com/gh_mirrors/hu/hunk点击查看免费下载本篇技术指南围绕 HunkReview-first 终端 diff 查看器仓库的顶层测试树test/展开系统讲解其单元测试就近、边界测试集中的测试布局哲学、8 个测试目录的职责划分、9 条测试放置规则以及完整的测试命令矩阵与覆盖范围。读完本文你将掌握如何判断一个测试应该放在哪个层级、如何运行 Linux/Windows/PTY/审查一致性等不同套件并能理解 Hunk 测试调度器scripts/test/run-test-suite.ts的分片、序列化与平台隔离原理。一、测试布局的整体设计就近原则 边界集中Hunk 的测试布局遵循一条核心原则大多数单元测试与被测源码就近存放colocated而顶层test/树专门收纳那些跨越模块、进程、仓库、运行时或终端边界的测试。这一点在 test/README.md 开头即被明确为设计起点。这种分层带来的直接收益是就近测试能直接引用被测模块的私有实现细节测试成本低、反馈快与源码同目录更便于开发者改了代码顺手补测试边界测试则聚焦于真正的集成风险点——比如 CLI 入口进程的启动行为、daemon/broker 的跨进程通信、审查语义在不同消费方之间的一致性、以及真实 PTY 下的终端渲染——这些场景无法在单元层面模拟必须集中到顶层独立管理。从仓库结构看就近测试的规模相当可观仅packages/hunk/src下就有超过 60 个*.test.ts如 packages/hunk/src/app/cli.test.ts、packages/hunk/src/core/liveComments.test.ts而顶层test/树则按边界类型进一步细分。二、顶层 test/ 树结构8 个目录的职责划分test/树的标准结构如下摘自 test/README.mdtest/ helpers/ shared test-only builders and fixtures fixtures/ runtime-neutral cross-process fixtures cli/ black-box CLI contracts session/ daemon, broker, and session CLI flows review-conformance/ shared semantic fixtures and consumer projections session-broker-node/ real Node adapter conformance session-broker-runtime/ shared Bun/Node connection fixtures pty/ live PTY-driven UI integration smoke/ opt-in terminal transcript checks各目录的实际职责与仓库现状对应如下目录核心职责仓库内实际内容举例test/helpers/共享的、仅测试使用的构建器与夹具diff-helpers.ts、review-session-harness.ts、session-daemon-fixtures.ts、theme-helpers.ts 等 13 个辅助模块test/fixtures/运行时无关的跨进程夹具sessionBrokerAdapterConformance.json供 Node/Bun 两侧共用test/cli/黑盒 CLI 契约help、version、pager 回退、错误路径entrypoint.test.ts、pager-pipe-output.test.ts、non-interactive-stdin.test.ts以及子目录install-vm/的可选 Firecracker 安装兼容套件test/session/跨进程的 daemon、broker、session CLI 流程daemon.test.ts、daemon-restart.test.ts、broker-e2e.test.ts、cli.test.tstest/review-conformance/手写的审查语义夹具 每个已注册消费方的真实投影conformance.test.ts、consumers.ts 及 9 个消费者适配器test/session-broker-node/真实 Node 监听器/适配器的一致性验证adapter.test.mjs、connection-fixture.tstest/session-broker-runtime/Bun/Node 共享的连接夹具connectionFixture.ts、bun-connection-fixture.tstest/pty/真实 PTY 驱动的 UI 集成resize、导航、鼠标、布局、滚动、note 可见性harness.ts、scroll.test.ts、nav.test.ts、highlighting.test.ts 等 20 个集成测试test/smoke/可选的真实 TTY 转录级渲染检查tty.test.ts其中test/pty/harness.ts是终端集成测试的关键基建它通过 Tuistory 驱动真实 PTY将 Hunk 的原子化渲染和 60ms 空闲延迟作为等待语义见 harness.ts并提供pressKeyRepeat、measureKeyScroll、measureMouseWheelScroll等行数级滚动度量工具同时支持BUN_BIN/BUN环境变量与HUNK_TEST_EXECUTABLE指定被测可执行文件见 harness.ts。三、测试放置规则9 条可执行的判定标准test/README.md 的 Placement 一节给出了决定测试放哪里的完整规则清单实操时按序套用即可就近原则当测试能直接驱动某个模块或辅助函数时把测试放在该模块旁边共享构建器把共享的单元测试构建器放进test/helpers/并显式命名为测试专用辅助如diff-helpers.ts、review-store-helpers.tsCLI 黑盒契约spawn 入口点的行为help、version、pager 回退、错误放到test/cli/跨进程流程跨进程的 daemon、broker、session CLI 流程放到test/session/审查语义一致性手写的审查语义夹具与每个已注册消费方的真实投影放到test/review-conformance/broker 适配器可移植性可移植的 broker 适配器行为放到test/session-broker-node/与test/session-broker-runtime/跨运行时共享夹具放test/fixtures/实时 UIresize、导航、鼠标、布局、滚动、note 可见性等真实 UI 行为放到test/pty/转录级渲染真实 TTY 上的转录级渲染检查放到test/smoke/平台边界新增新增依赖 Windows 平台边界的 UI 测试时放入windows-ui分组。这套规则的精髓是先判断测试是否跨越了模块/进程/仓库/运行时/终端边界——没有跨界就就近放跨界就按边界类型归入对应顶层目录。四、测试命令矩阵与覆盖范围Hunk 以 Bun 作为测试运行时package.json 声明packageManager: bun1.4.2engines.node 22。下表完整列出 test/README.md 定义的命令及其覆盖范围命令覆盖范围bun run testpackages/、scripts/、examples/、test/cli/、test/session/具体分组定义见 scripts/test/run-test-suite.ts 的TEST_PATTERN_GROUPS.defaultbun run test:windowsWindows 平台下的进程、VCS、CLI、打包覆盖Linux 负责终端 UI 语义套件bun test ./test/review-conformance共享审查夹具与已注册消费方的投影bun run test:session-broker-node使用已入库的跨运行时夹具对真实 Node listener/adapter 做一致性验证bun run test:integrationtest/pty/下由 PTY 支撑的测试对应--groupintegrationbun run test:tty-smoketest/smoke/下可选的真实 TTY smoke 测试bun run test:install-vmtest/cli/install-vm/下可选的 Firecracker 安装兼容场景bun run vm:shell [-- --with-hunk]可丢弃的 Ubuntu Firecracker shell可选附带全新本地 Hunk 构建命令在 package.json 中的真实定义如下test: bun run ./scripts/test/run-test-suite.ts, test:windows: bun run ./scripts/test/run-test-suite.ts --groupwindows bun run ./scripts/test/run-test-suite.ts --groupwindows-ui, test:integration: bun run ./scripts/test/run-test-suite.ts --groupintegration, test:session-broker-node: bun run ./scripts/test/test-session-broker-node.ts, test:tty-smoke: HUNK_RUN_TTY_SMOKE1 \${npm_execpath:-bun}\ test ./test/smoke, test:install-vm: bun run ./test/cli/install-vm/runner.ts, vm:shell: bun run ./test/cli/install-vm/vm-shell.ts4.1 默认套件并不包含全部测试test/README.md 特别强调专用测试树不会被bun run test直接选中尽管部分包测试会导入共享的运行时夹具。这意味着默认套件覆盖不到test/review-conformance/、test/session-broker-node/、test/pty/、test/smoke/等目录而默认套件未覆盖并不等于其他命令会覆盖它——请运行与所改行为匹配的命令。五、测试调度器源码解析分组、分片与序列化bun run test并非直接调用bun test而是经由 scripts/test/run-test-suite.ts 调度。该模块注释揭示了原因Bun 1.3.14 的--parallel会隐式启用--isolate导致 OpenTUI 的原生 FFI 渲染器初始化失败Cannot access default before initialization.独立--shardN/M进程可以避免该问题但 Bun 只运行请求的那个 shard因此该模块负责启动并监督全部 shard。5.1 测试分组TEST_PATTERN_GROUPS源码第 16-25 行定义了四个命名分组可用--groupname切换定义于 run-test-suite.tsexport const TEST_PATTERN_GROUPS { default: [./packages, ./scripts, ./examples, ./test/cli, ./test/session], integration: [./test/pty], windows: [./packages, ./scripts, ./examples, ./test/cli, ./test/session], windows-ui: [ ./packages/hunk/src/ui/diff/worker/highlightWorkerClient.test.ts, ./packages/hunk/src/ui/lib/openInEditor.test.ts, ./packages/hunk/src/ui/lib/workspaceWriteGuard.test.ts, ], } as const;注意windows分组会通过--path-ignore-patterns**/packages/hunk/src/ui/**排除全部终端 UI 语义代码第 30-33 行而windows-ui分组则精确挑选了三个依赖 Windows 平台边界的 UI 测试highlight worker 启动highlightWorkerClient.test.ts、编辑器命令openInEditor.test.ts、工作区路径安全workspaceWriteGuard.test.ts。5.2 分片策略与 HUNK_TEST_SHARDS自动分片上限Linux 上自动分片数 min(2, max(1, floor(cpuCount)))MAX_AUTOMATIC_TEST_SHARDS 2非 Linux 平台自动保持串行第 35、60-62 行显式覆盖通过HUNK_TEST_SHARDS环境变量可显式指定 1-64 之间的正整数MAX_EXPLICIT_TEST_SHARDS 64非法值会抛出HUNK_TEST_SHARDS must be a positive safe integer或HUNK_TEST_SHARDS cannot exceed 64第 44-62 行PTY 集成默认串行integration分组在未显式指定 shard 数时始终串行执行第 65-73 行这是因为它属于资源密集型测试。5.3 序列化条件当调用含以下参数时requiresSerialTestExecution第 98-107 行整个套件回退为单进程串行-t或--only测试名过滤--test-name-pattern名称模式过滤--coverage覆盖率统计--reporter-outfile文件输出型 reporter原因如注释所述过滤运行与共享文件型输出必须保持在单个进程内run-test-suite.ts。5.4 信号与终止调度器为每个 shard 注册SIGINT退出码 130与SIGTERM退出码 143处理先向所有存活 shard 转发信号1 秒宽限后未退出者升级为SIGKILL第 128-137、196-208 行任一 shard 失败时打印Test shard failure: N/M (exit code)并返回 1第 222-230 行。这些行为全部有对应测试保障见 scripts/test/run-test-suite.test.ts。六、review-conformance对抗性夹具驱动的语义一致性test/review-conformance/是 Hunk 测试体系中颇具特色的部分它用同一套手写语义夹具去验证每一个真实消费方确保审查模型在核心、终端、producer、broker 镜像、扩展快照、wire 协议、HTTP 浏览器表面之间不发生语义漂移。其设计原则写在 types.ts 的头部注释中期望值必须按语义手写绝不允许从某个原始实现的输出捕获——捕获的期望会跟着 bug 走而对抗性夹具存在的意义恰恰是防止旧的复制品再次出错投影必须渲染器无关——只有某个消费方能产生的行、宽度、DOM 等内容不得进入语料否则语料失去可比性。消费者注册表定义于 consumers.ts当前注册情况如下语料类别已注册消费者几何REVIEW_GEOMETRY_CONSUMERScore review model、terminal render planning、review producer导航REVIEW_NAVIGATION_CONSUMERScore intent planner、terminal review排序REVIEW_ORDERING_CONSUMERScore publication ordering、broker review mirror快照REVIEW_SNAPSHOT_CONSUMERSextension review snapshotwireREVIEW_WIRE_CONSUMERSreview wire protocol事件REVIEW_EVENT_CONSUMERSreview event protocol、browser review HTTP surface每个夹具都携带findings字段指向其所防护的审计发现编号如A1、B1、C1、D1、EXT1。conformance.test.ts 第 37-55 行列出了 17 个必须被夹具覆盖的已偿清发现并有一条专门测试断言每个声称已偿清的发现都有对应对抗性夹具第 84-97 行防止声称已修复但没有测试守护的情况。各消费者的适配器位于 test/review-conformance/consumers/ 目录如coreModel.ts、terminalRenderPlan.ts、reviewProducer.ts、brokerMirror.ts、extensionReviewSnapshot.ts、browserReviewSurface.ts等 9 个。以 wire 消费方为例其契约要求回答两个问题见 types.ts动作被解析后表示什么意图对应发现 B12/B10以及一条 note 是否允许跨边界传输对应发现 D1——每个字段都通过但整体超限的 note 必须在准入前被拒绝见 conformance.test.ts。运行方式bun test ./test/review-conformance。新增消费方时只需在 consumers.ts 注册适配器此后整个语料库包括之前所有阶段的对抗性夹具都会自动对它运行。七、Windows 平台覆盖与新增测试指引test/README.md 末尾明确了平台分工Linux 套件拥有平台无关的终端 UI 语义树packages/hunk/src/ui/**是终端 UI 语义的主战场Windows 套件bun run test:windows跳过该语义树改为运行三个聚焦的 UI 边界测试worker 启动、编辑器命令、工作区路径安全新增规则当新 UI 测试的行为依赖 Windows 平台边界时将其加入windows-ui分组即 run-test-suite.ts 的三个文件路径列表。八、可选套件Firecracker 安装兼容与真实 TTY smoke8.1 test:install-vmFirecracker 微虚拟机位于 test/cli/install-vm/完全可选验证 Linux x64 上 npm/pnpm 安装与升级、认证 daemon 升级、legacy Bun 回退、离线执行以及 curl 安装/升级行为。运行前置条件详见 test/cli/install-vm/README.mdLinux x86_64至少 6 GiB 可用空间无需sudo即可访问 Docker daemon可读写/dev/kvm与/dev/net/tun。常用操作bun run test:install-vm -- --list # 列出全部场景 bun run test:install-vm -- --scenario pnpm-global-upgrade bun run test:install-vm -- --scenario authenticated-daemon-upgrade bun run test:install-vm # 运行全部 bun run vm:shell # 打开干净 Ubuntu 24.04 交互 shell bun run vm:shell -- --with-hunk # shell 附带当前 checkout 的构建产物 bun run test:install-vm:clean # 清理 tmp/install-vm 下的 harness 产物该套件基于校验和固定的Firecracker、内核、rootfs 与 Node 输入安全边界上控制器仅获得/dev/kvm、/dev/net/tun、NET_ADMIN、CHOWN、DAC_OVERRIDE五个权限且不挂载仓库或 Docker socket见 install-vm/README.md 的 Security boundary 一节。需注意其边界Firecracker 无法验证 macOS/Windows也无法模拟 Apple Silicon 的最终原生退出行为。8.2 test:tty-smoke真实 TTY 转录检查bun run test:tty-smoke通过HUNK_RUN_TTY_SMOKE1环境变量启用 test/smoke/tty.test.ts在真实 TTY 上做转录级渲染校验属于按需启用的 opt-in 检查不进入默认套件。九、实践建议如何选择正确的测试命令结合 test/README.md 与调度器源码可归纳出以下决策路径改动仅涉及单个模块/辅助函数 → 就近放置单元测试随bun run test默认套件运行改动涉及 CLI 入口、pager、错误路径 →test/cli/随默认套件运行改动涉及 daemon/broker 跨进程流程 →test/session/随默认套件运行改动涉及审查语义或任一消费方投影 →test/review-conformance/运行bun test ./test/review-conformance改动涉及 broker 适配器跨运行时行为 →test/session-broker-node/与test/session-broker-runtime/运行bun run test:session-broker-node改动涉及终端 UI 交互resize/导航/鼠标/布局/滚动/note→test/pty/运行bun run test:integration改动涉及真实 TTY 渲染或 Linux x64 安装升级 → 分别运行bun run test:tty-smoke与bun run test:install-vm在 Windows 平台工作或新增平台边界依赖的 UI 测试 →bun run test:windows并将新测试加入windows-ui分组。最后记住调度器的两个默认行为Linux 自动分片最多 2 个 shard可用HUNK_TEST_SHARDS显式调大而带过滤、覆盖率或文件型 reporter 的调用一律串行执行PTY 集成测试默认串行除非显式指定 shard 数。这套规则确保了测试既能在开发机上快速反馈又能在 CI 中可靠并行。赞分享开发工具代码评审CLIAI 应用【免费下载链接】hunkReview-first terminal diff viewer for agentic coders项目地址https://gitcode.com/gh_mirrors/hu/hunk点击查看免费下载相关推荐Open-Sora 单卡图生视频实战指南60 秒出第一条 256px 视频Open Sora 单卡图生视频实战指南60 秒出第一条 256px 视频 Open Sora 2.011B是开源视频生成模型单份权重同时跑文生视频T人工智能大模型媒体生成音视频预训练分布式训练isomorphic-git 贡献指南分层架构、命令扩展清单与子模块测试体系isomorphic git 贡献指南分层架构、命令扩展清单与子模块测试体系 isomorphic git纯 JavaScript 实现的 Git有一套清开发工具PraisonAI 测试体系全解Mock 与 Real 双层测试、test_runner 命令及安全门控机制PraisonAI 测试体系全解Mock 与 Real 双层测试、test_runner 命令及安全门控机制 本文以 PraisonAI 仓库中的测试指南为蓝人工智能AI AgentAgent 框架多智能体工作流自动化RAGMCP 服务上一篇Haystack Docker 镜像构建与部署指南从 docker buildx bake 多平台构建到生产发布下一篇Ente Photos 桌面端发布流程全解析从 nightly 到稳定版 Release 的完整实践指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考