# 测试与验证报告 日期: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。 ## 复现命令 ```sh 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 覆盖率: ```sh 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: ```sh 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/完整生命周期仍需后续验证。适配器测试证明当前工具总线类型兼容,不代表应用中已经安装这些功能。