VALIDATION.zh-CN.md 5.1 KB

测试与验证报告

日期:2026-11-05;原型版本:v0.1.0。

实际环境

  • Linux amd64,使用 Ubuntu 运行库。
  • Go 1.24.4 与 Go 1.25.0。
  • CDP:真实 Chrome Headless Shell 131.0.6778.204。
  • Native:GTK3 + WebKitGTK/JavaScriptCoreGTK 4.1,包版本 2.52.3。
  • Native 使用真实 Xvfb X11 显示服务器,顶层窗口保持隐藏。
  • 本次隔离容器显式开启 NoSandbox,未验证生产环境默认沙箱开启的部署情况。
  • 显示环境没有 DRI3,Native 使用兼容软件渲染的测试选项;没有宣称支持 Native 截图。

源码压缩包不包含测试使用的 Go 工具链、浏览器二进制或系统运行库。

已完成检查

检查 结果
Go 1.25.0、CGO_ENABLED=0 单元测试 通过
Go 1.24.4、CGO_ENABLED=0 单元测试 通过
Go 1.25.0 race 检查 通过;仅 race 测试运行时启用 cgo
go vet 通过
CDP 本地动态页面命令行 demo 通过
Linux Native 本地动态页面命令行 demo 通过
CLI 长度前缀管道通信 demo 通过
动态网页闭环、旧引用/取消/归属、cookie 隔离与生命周期 两后端均通过
CDP 登录态下载与 blob 下载,核对文件内容 通过
Native 下载测试 后端明确不支持,按预期跳过
ClusterFlow 注册适配器 在上传源码的独立副本中,以 Go 1.25.0 通过
六目标无 cgo 构建 通过,仅代表编译
Python 覆盖率合并辅助脚本 通过

交叉编译目标:linux/amd64、linux/arm64、windows/amd64、windows/arm64、darwin/amd64、darwin/arm64。只有 Linux amd64 做了真实运行测试。Windows/macOS 原生 worker 是返回“不支持”的程序,不是已经实现的原生后端。

覆盖率口径

Go 语句合并覆盖率为 82.42%,统计包括命令行、原生 worker,以及未执行的两个示例程序,排除 vendor 第三方代码。这是单元测试、真实引擎测试和已插桩 CLI/worker 运行结果的并集,不能解释为整个长期设计已实现 82%。

包/模块 合并语句覆盖率
主 SDK / 会话 / 文件层 84.84%
Agent 工具适配 89.04%
API / 错误契约 100.00%
CDP 驱动 79.58%
Native 客户端 83.33%
Native worker 81.08%
CLI 80.18%
导航策略 94.87%
管道协议 90.12%
嵌入脚本的 Go 包装层 100.00%

Go 包装层 100% 不代表 JavaScript 分支覆盖率。脚本通过真实浏览器测试验证了隔离世界状态保持、role/label/密码隐藏、填写/点击/勾选/选择、DOM 替换后引用过期、文本/表格读取和等待,目前没有另行接入 JS 覆盖率插桩。

单元测试各包覆盖率在 test-results/unit.txt,合并块记录在 merged.cover / coverage.txt,精确语句数见 coverage-summary.json。示例程序已编译,但未计入执行命中;CLI demo 直接执行相同 SDK。

复现命令

mkdir -p bin test-results
CGO_ENABLED=0 go test ./... -count=1 -coverprofile=test-results/unit.cover
go vet ./...
CGO_ENABLED=1 go test -race ./... -count=1
CGO_ENABLED=0 go build -o bin/cfbrowser-worker ./cmd/cfbrowser-worker
CFBROWSER_INTEGRATION=1 CFBROWSER_EXECUTABLE=/path/to/chrome go test ./integration -v -count=1
sh scripts/cross-build.sh

如需双后端测试,在可用图形/Xvfb 环境下增加 CFBROWSER_NATIVE=1 和 CFBROWSER_WORKER=/absolute/path/to/cfbrowser-worker。只有在明确隔离且无法开启浏览器沙箱的 CI 中,才显式设置 CFBROWSER_TEST_NO_SANDBOX=1;生产环境不要仅为复现测试而关闭沙箱。

收集独立 CLI/worker 覆盖率:

mkdir -p test-results/runtime-coverage
CGO_ENABLED=0 go build -cover -coverpkg=./... -o bin/cfbrowser ./cmd/cfbrowser
CGO_ENABLED=0 go build -cover -coverpkg=./cmd/cfbrowser-worker,./protocol,./api -o bin/cfbrowser-worker ./cmd/cfbrowser-worker
GOCOVERDIR="$PWD/test-results/runtime-coverage" ./bin/cfbrowser --browser /path/to/chrome demo
GOCOVERDIR="$PWD/test-results/runtime-coverage" ./bin/cfbrowser --engine native --worker "$PWD/bin/cfbrowser-worker" demo
go tool covdata textfmt -i=test-results/runtime-coverage -o=test-results/runtime.cover

真实集成测试增加 -coverpkg=./... 和 -coverprofile=test-results/integration.cover;采集 worker 时保持 GOCOVERDIR 可被子进程继承。只合并同一份已格式化源码产生的 profile:

python3 scripts/merge_coverage.py test-results/unit.cover test-results/integration.cover test-results/runtime.cover --output test-results/merged.cover
go tool cover -func=test-results/merged.cover
python3 -m unittest discover -s scripts -p 'test_*.py'

原始日志与 manifest 位于 test-results。测试截图、浏览器及系统环境二进制不放入源码包。

本次验证没有覆盖的范围

生产沙箱开启部署、Rocky 9、Wayland、Windows/macOS 实机、通用 popup/dialog、任意外站成功率、Native 截图/下载、严格出站隔离、持久登录/profile、模型视觉输入,以及 Wails UI/完整生命周期仍需后续验证。适配器测试证明当前工具总线类型兼容,不代表应用中已经安装这些功能。