VALIDATION.en.md 5.6 KB

Validation report

Date: 2026-11-05 · Prototype v0.1.0.

Actual environment

  • Linux amd64 execution environment with Ubuntu runtime packages.
  • Go 1.24.4 and Go 1.25.0.
  • Chrome Headless Shell 131.0.6778.204 for actual CDP tests.
  • GTK3 plus WebKitGTK/JavaScriptCoreGTK 4.1 runtime package version 2.52.3 for actual native tests.
  • Native tests used a real Xvfb X11 display. The native top-level window remained hidden.
  • Isolated-container tests explicitly enabled NoSandbox; default production sandbox behavior was not validated.
  • Native rendering used software-compatible options because the test display had no DRI3 acceleration. No native screenshot capability is claimed.

Toolchains, browsers and OS libraries are not included in the source archive.

Checks completed

Check Result
Go 1.25.0 unit suite with CGO_ENABLED=0 Passed
Go 1.24.4 unit suite with CGO_ENABLED=0 Passed
Go 1.25.0 race detector suite Passed; cgo enabled only for the race test runtime
go vet Passed
CDP deterministic CLI demo Passed
Linux native deterministic CLI demo Passed
Framed CLI host protocol demo Passed
Actual dynamic workflow, stale refs/cancellation/scope, cookie isolation/lifecycle Passed with both engines
CDP authenticated download and blob download, content verified Passed
Native download test Explicitly skipped because the backend reports unsupported
ClusterFlow registry adapter seam Passed inside a separate copy of the actual uploaded source, Go 1.25.0
Six target no-cgo builds Passed; compilation only
Python coverage merge utility Passed

Cross-build targets: linux/amd64, linux/arm64, windows/amd64, windows/arm64, darwin/amd64, darwin/arm64. Only Linux amd64 was runtime-tested. Windows/macOS native workers are unsupported-platform programs, not implemented native backends.

Coverage

Merged statement coverage is 82.42% across the Go source recorded in the profiles, including command entry points, the native worker and the two unexecuted example programs. Third-party vendor code is excluded. This is a union of unit tests, real-engine integration tests and instrumented CLI/worker executions; it is not a claim of 82% of the entire long-term product design.

Package Merged statement coverage
Main SDK/session/file layer 84.84%
Agent tool adapter 89.04%
API contracts/errors 100.00%
CDP driver 79.58%
Native driver client 83.33%
Native worker 81.08%
CLI 80.18%
Navigation policy 94.87%
Pipe protocol 90.12%
Embedded-script Go wrapper 100.00%

The Go wrapper's 100% does not measure JavaScript branch coverage. The JS script is exercised by actual browser tests: isolated-world persistence, roles/labels/password masking, fill/click/check/select, stale element replacement, read/table extraction and waits. A separate JS coverage instrumenter has not been added.

Unit-only package coverage is recorded in test-results/unit.txt; overall merged blocks are in merged.cover and coverage.txt, with exact package counts in coverage-summary.json. Example programs compile but do not contribute executed coverage. The CLI demo exercises the same SDK without requiring example-specific assertions.

Reproduce

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

For both engines, run the integration command inside a working graphical/Xvfb session with CFBROWSER_NATIVE=1 and CFBROWSER_WORKER=/absolute/path/to/cfbrowser-worker. In an isolated CI environment that cannot run browser sandboxes, explicitly set CFBROWSER_TEST_NO_SANDBOX=1. Do not set this in production merely to match the test environment.

To collect standalone worker/CLI coverage:

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

Run integration tests with -coverpkg=./... -coverprofile=test-results/integration.cover, and preserve GOCOVERDIR in worker environment when collecting its execution. Merge profiles only from the same formatted source revision:

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'

The raw text logs and manifest are included under test-results/. Browser screenshots and the local test environment's binaries are deliberately not shipped.

Limits of this validation

This does not validate sandbox-enabled deployment, Rocky 9, Wayland, Windows/macOS runtime behavior, general popup/dialog handling, arbitrary external sites, native capture/downloads, strict egress isolation, persistent login/profile handling, visual model input or Wails UI/lifecycle behavior. These remain separate milestones. The source adapter test proves compatibility with the existing Tool Bus types, not an already-installed application feature.