RackPeek测试体系深度剖析:黑盒CLI集成测试与Playwright/Testcontainers E2E实战
RackPeek测试体系深度剖析:黑盒CLI集成测试与Playwright/Testcontainers E2E实战
RackPeek 是一个用于发现、管理和文档化 IT 基础设施与 Home Lab 的 CLI + Web UI 工具,它的测试体系由两层组成:快速的黑盒 CLI 集成测试(Tests/)和基于 Playwright + Testcontainers 的 Web UI E2E 测试(Tests.E2e/)。本文带你完整看懂这套测试架构:为什么坚持黑盒、临时目录如何做到完全隔离、Docker 镜像如何被"随机端口"地拉起来给浏览器自动化,以及那些让测试不腐化的工程原则。
一图看懂:RackPeek 的两层测试架构
🧪 整个仓库只维护两套测试工程,职责划分非常清晰:
| 测试层 | 目录 | 框架 | 被测对象 | 速度 |
|---|---|---|---|---|
| 黑盒 CLI 集成测试 | Tests/ | xUnit + Spectre.Console.Testing | rpk 命令行 + 落盘 YAML |
快,无需 Docker |
| 黑盒 API 集成测试 | Tests/Api/ | xUnit + WebApplicationFactory | REST Inventory API | 快,无需 Docker |
| Web UI E2E 测试 | Tests.E2e/ | xUnit + Playwright + Testcontainers | Docker 容器中的 Blazor Web UI | 较慢,需 Docker |
官方测试原则写在 docs/development/testing-guidelines.md,核心只有一句话:
只测试系统边缘的可观察行为(行为,而非实现细节),换来重构自由、优化信心和长期稳定的测试。
所有测试必须在 PR 合入 main 前通过——这也是 justfile 中 just ci 命令对应的完整流程。
一键运行:3 个 Just 命令跑通全部测试
项目用 justfile 封装了所有测试命令,新手只需记住三个:
| 命令 | 作用 |
|---|---|
just test-cli |
只跑 CLI 黑盒测试,不依赖 Docker,反馈最快 |
just e2e-setup |
首次运行:安装 Playwright 浏览器依赖 |
just test-e2e |
先构建 Web Docker 镜像(rackpeek:ci),再跑 E2E 测试 |
just test-e2e 依赖 just build-web(即 docker build -t rackpeek:ci -f RackPeek.Web/Dockerfile .),这一点非常关键:E2E 测试测的就是真实 Docker 镜像,而不是本地调试进程。如果你想亲手体验整套流程,可以克隆仓库后依次执行上述命令:
git clone https://gitcode.com/gh_mirrors/ra/RackPeek
just test-cli
just test-e2e
黑盒 CLI 集成测试:如何"不启动进程"地测试整个 CLI
CLI 测试是反馈最快的一层,但它测的绝不是某个方法,而是真实的命令 + 真实的文件副作用。核心由三个类协作完成:
1️⃣ TempYamlCliFixture:每个测试类一个干净的临时目录
Tests/EndToEnd/Infra/TempYamlCliFixture.cs 在初始化时创建 临时目录/rackpeek-tests/{GUID} 并写入空 config.yaml,结束时整体删除。这意味着:
- 测试之间零共享状态,可安全并行;
- 所有 CLI 命令"写盘"的都是这个一次性目录,绝不影响你的真实配置;
- 通过 Tests/EndToEnd/Infra/YamlCliTestCollection.cs 中的
[CollectionDefinition("Yaml CLI tests", DisableParallelization = true)]约束同一集合串行,保证确定性。
2️⃣ YamlCliTestHost:把整条 CLI 管线装进测试
Tests/EndToEnd/Infra/YamlCliTestHost.cs#L12-L57 的 RunAsync 是这套黑盒测试的"发动机":
var console = new TestConsole();
AnsiConsole.Console = console; // 劫持 Spectre 控制台输出
app.Configure(c => c.Settings.Console = console);
// ...同时劫持 Console.Out 捕获不走 Spectre 的原始输出
await app.RunAsync(args);
三个细节让它可以"黑盒"到最后一厘米:
- 真实依赖注入:通过
CliBootstrap.RegisterInternals注册完整服务集合,走的是与生产完全相同的 DI 管线; - 双重输出捕获:Spectre 的
TestConsole+ 被替换的Console.Out(比如graph topology命令必须输出不加包装的 Mermaid 文本,会绕过 Spectre 直接写原始流); - 日志可观测:自定义 Tests/XUnitLoggerProvider.cs 把
ILogger日志全部转发到 xUnit 测试输出,失败时日志直接可见。
3️⃣ 双重断言:既看屏幕输出,也翻 YAML 文件
看一段真实测试 Tests/EndToEnd/DesktopTests/DesktopWorkflowTests.cs#L25-L40:
(output, yaml) = await ExecuteAsync("desktops", "add", "workstation01");
Assert.Equal("Desktop 'workstation01' added.\n", output); // 屏幕输出逐字符精确
Assert.Contains("name: workstation01", yaml); // 磁盘上的 YAML 也校验
每次执行后测试会同时断言控制台输出(甚至精确到 \n)和落盘的 config.yaml 内容——这正是"文档即数据"工具该有的测试姿态。
而错误路径同样被系统覆盖,例如 Tests/EndToEnd/FirewallTests/FirewallErrorTests.cs#L21-L44 覆盖了"重名资源、get/set/del 不存在的资源"等场景,只断言输出包含 already exists / not found 这类用户可见的措辞。
顺带一提,Web UI 内置了一个与本地 CLI 完全一致的控制台模拟器,浏览器里也能跑 rpk 命令,测试同样覆盖到它背后的同一套命令注册逻辑:
API 集成测试:WebApplicationFactory 模拟真实服务
REST Inventory API(用于把 YAML 导入/导出基础设施清单)由 Tests/Api/ApiTestBase.cs 承载:用 WebApplicationFactory<Program> 启动完整的 Web 宿主,注入测试 API Key 和独立临时目录,再用 HttpClient 发真实 HTTP 请求。
以 Tests/Api/InventoryEndpointTests.cs#L9-L41 为例,dryRun 模式的测试会连续两次提交同一份 YAML,断言第二次仍然返回 "added"——精确刻画了"试运行不落盘"这一用户可观察行为。未配置 API Key 的场景则单独放在 Tests/Api/InventoryEndpointUnconfiguredTests.cs。
Playwright + Testcontainers E2E 实战:给真实容器开浏览器
E2E 层的目标不是"UI 能打开",而是用户关键工作流真的能走通。它的技术选型在 Tests.E2e/Tests.E2e.csproj 里一目了然:Microsoft.Playwright + Testcontainers。
1️⃣ Testcontainers:随机端口 + HTTP 等待策略
Tests.E2e/Infra/PlaywrightFixture.cs#L16-L47 是整套 E2E 的基石,三步走:
_container = new ContainerBuilder("rackpeek:ci")
.WithPortBinding(8080, true) // 随机主机端口,避免端口冲突
.WithWaitStrategy(
Wait.ForUnixContainer()
.UntilHttpRequestIsSucceeded(r => r.ForPort(8080).ForPath("/")))
.Build();
await _container.StartAsync();
var mappedPort = _container.GetMappedPublicPort(8080);
BaseUrl = $"http://127.0.0.1:{mappedPort}";
- 随机端口映射让 CI 与本地、多个测试类并发都不会互相打架;
- HTTP 等待策略确保容器"真的能应答请求"后才开始跑测试,而不是仅
docker run成功; - 浏览器以 Headless Chromium 启动,
Assertions.SetDefaultExpectTimeout(15000)统一放宽断言等待。
还有一个"测试镜像本身"的测试:Tests.E2e/DockerHealthcheckTests.cs 用 UntilContainerIsHealthy() 等待策略 + 60 秒取消令牌,专门验证 Docker 镜像的 HEALTHCHECK 指令真的生效——如果镜像漏配健康检查,这个测试会快速失败并自动打印容器日志。
2️⃣ Page Object Model:测试读起来像工作流
每个页面都有一个 POM 类,集中在 Tests.E2e/PageObjectModels/。以 Tests.E2e/PageObjectModels/DesktopsListPom.cs#L56-L99 为例,POM 把选择器封装成意图级方法:GotoAsync、AddDesktopAsync、DeleteDesktopAsync、AssertDesktopExists。
于是测试代码读起来就是一个故事,而不是浏览器脚本:
var listPage = new DesktopsListPom(page);
await listPage.AssertLoadedAsync();
await listPage.AddDesktopAsync(resourceName);
await listPage.AssertDesktopExists(resourceName);
await listPage.DeleteDesktopAsync(resourceName);
await listPage.AssertDesktopDoesNotExist(resourceName);
(完整示例见 Tests.E2e/DesktopTests.cs#L14-L57)
配合两个小设计,稳定性大增:
- 唯一测试数据:
$"e2e-ap-{Guid.NewGuid():N}"[..16],天然幂等、互不干扰; - data-testid 定位:POM 全部使用
page.GetByTestId("desktops-list")这类语义化测试 ID,而不是脆弱的 CSS 路径,UI 样式改版不会波及测试。
导航类测试(如从首页进入 Hardware 树再到 Desktops 列表)覆盖了真实用户的点击路径,界面即被测物:
3️⃣ 失败诊断:DOM 快照 + 浏览器控制台转发
E2E 最容易让人抓狂的是"挂了却不知道为什么"。Tests.E2e/Infra/E2ETestBase.cs 在创建页面时就把浏览器的 console 和 PageError 事件转发到 xUnit 输出;而测试失败时(见 Tests.E2e/DesktopTests.cs#L42-L53)会捕获当前 URL 并整页输出 DOM 快照,调试一次到位。
调试技巧:临时把 PlaywrightFixture.cs 中 Headless 改为 false、SlowMo 调大可肉眼观察执行过程——但提交前务必恢复 Headless = true,CI 必须无头运行。
六条让测试不腐化的工程原则
这些标准来自 docs/development/testing-guidelines.md#L263-L297,值得每个团队抄作业:
- 行为优先:只测用户能观察到的输出与文件,不测内部实现;重构不改行为,测试就永不红;
- 集成优先于微 Mock:宁可真实 DI 管线 + 真实 YAML 文件,也不追求隔离纯度(NSubstitute 只留给确实需要的场景,见 Tests/Git/);
- 快速反馈:CLI 层要快,E2E 层"少而精",只测 happy path 与关键流;
- 测试即文档:一个测试同时说明功能是什么、预期行为是什么、回归长什么样;
- 稳定 > 覆盖率:高价值测试比覆盖率数字重要;
- 零 Flaky 容忍:不稳定的测试要么立刻修,要么删掉——它会侵蚀整个团队对 CI 的信任。
另外还有一条"Definition of Done":功能实现、测试存在、本地通过、CI 通过、边界覆盖、无调试开关残留,六项全勾才算完成。
总结
RackPeek 的测试体系是一套值得小团队直接借鉴的样板:
- 🖥️ CLI 层:临时目录隔离 +
TestConsole双路输出捕获 + 屏幕输出与落盘 YAML 双重断言,无需 Docker 就能黑盒验证全部命令行为; - 🐳 E2E 层:Testcontainers 拉起真实 Docker 镜像 + 随机端口 + HTTP 就绪等待,Playwright 通过 POM 把 UI 测试写成工作流叙事,失败时自动输出 DOM 与浏览器日志;
- ✅ 纪律层:行为优先、零 Flaky、CI 全绿才可合并,让测试资产长期保值。
如果你也在给 CLI 工具或 Blazor/Docker 应用搭测试,可以从 justfile 的 test-cli / test-e2e 配方和 docs/development/testing-guidelines.md 开始,半天就能搭出同等体量的骨架。




