ContextQMD
Back to Chromium

Code Coverage Local Debugger

agents/skills/experimental-code-coverage-local-debugger/SKILL.md

152.0.7936.13.2 KB
Original Source

Code Coverage Local Debugger

Use this skill to generate code coverage data on a local workstation using Chromium's Universal Test Runner (tools/utr). It wraps the exact recipe logic used by LUCI trybots, dynamically evaluating local Starlark and GN repairs.

When to Use This Skill

  • Automated tryjobs fail or underreport coverage on CQ.
  • Testing whether local GN argument or Starlark recipe repairs successfully restore code coverage before uploading patchsets.
  • Isolating whether test suite crashes occur in local hermetic environments.

Inputs

  • builder_name: The target CQ builder name (e.g., "linux-rel").
  • bucket: The builder bucket (default: "try").
  • test_suite: The target test target name (e.g., "net_unittests").
  • build_dir: Optional custom output directory (e.g., "out/Coverage").

Workflow

1. Regenerate Starlark Configurations

If prior agent debugging steps modified Starlark files under infra/config/, regenerate the global configuration files so UTR reads the latest state.

bash
lucicfg generate infra/config/main.star

2. Execute Universal Test Runner (UTR)

For general UTR command documentation, common flags, and authentication guidelines, refer to the utr skill.

When debugging code coverage specifically, invoke tools/utr/run.py to compile and execute the test target while replicating the exact LUCI builder recipe environment and evaluating Starlark code coverage GN arguments (e.g., use_clang_coverage = true):

bash
vpython3 tools/utr/run.py -p chromium -B {{bucket}} -b {{builder_name}} \
  -t {{test_suite}} compile-and-test
  • When to Use UTR for Code Coverage: Use this option when you need to verify that Starlark or GN argument repairs successfully restore code coverage instrumentation and .profdata generation before uploading a CL, or when isolating shard failures on platforms not accessible locally (e.g., Windows or ChromeOS).

3. Rapid Workstation Execution (Bypass Container)

To run a native workstation test binary directly against pinned LLVM tools without UTR container overhead, execute the rapid helper script:

bash
vpython3 tools/code_coverage/run_local_coverage.py \
  --binary {{build_dir}}/{{test_suite}} --source {{target_file}}

4. Inspect Local Verification Artifacts

  • Inspect Artifacts: Audit ResultDB / Milo links printed at the end of the UTR run (ci.chromium.org/ui/inv/...) to verify code coverage percentage resolution.
  • Symbol Validation: For rapid helper runs (run_local_coverage.py), verify that generated .profdata reports non-zero line execution counts matching edits.

References