Code coverage

Code coverage is a metric that reports how much contract source is executed during tests. It helps identify untested parts of the codebase.

Acton's test runner reports line, branch, and blended score metrics:

• Line coverage: executable source lines that were hit during test runs
• Branch coverage: observed branch outcomes that were hit at runtime
• Score: a blended metric that combines both numbers for quick comparison

Additionally, it can export coverage data in LCOV or text format and present the Test UI coverage view in the browser.

Enable coverage

Command-line flag

Run tests with --coverage:

acton test --coverage

That collects coverage for the selected tests and prints a summary table afterward.

Coverage in the Test UI

Run tests with --coverage and --ui together:

acton test --coverage --ui

When both flags are enabled, Test UI shows a Coverage tab with:

• overall coverage summary
• sortable file list
• per-file source view with annotated lines

The browser view does not require --coverage-format lcov; the UI receives coverage for the current run automatically.

Coverage with filters

Combine --coverage with file paths or --filter as usual:

# Run one or more selected test files with coverage
acton test counter.test.tolk wallet.test.tolk --coverage

# Run tests matching a pattern with coverage
acton test --filter "test increase" --coverage

By default, Acton excludes:

• files under tests/
• .test.tolk files
• files under the @wrappers mapping

Pass these flags to include those sources in the report:

acton test --coverage --coverage-include-tests
acton test --coverage --coverage-include-wrappers

Read coverage reports

With --coverage, Acton prints a table after the run:

───────────────────────────────────────────────────────────────────────────────────────────
 File      Covered   Total Lines   % Lines   Covered   Total Branches   % Branches   Score
───────────────────────────────────────────────────────────────────────────────────────────
 All files       4             4    100.0%         2                2       100.0%   100.0%
 math.tolk       4             4    100.0%         2                2       100.0%   100.0%

Coverage columns

• Covered Lines: Number of lines that were executed during testing
• Total Lines: Total number of executable lines in the file
• % Lines: Percentage of executable lines that were covered
• Covered Branches: Number of observed branch outcomes that were hit
• Total Branches: Number of observed branch outcomes recorded for that file
• % Branches: Percentage of observed branch outcomes that were hit
• Score: Blended metric used for sorting and quick comparison across files

Text report annotations

The text artifact is line-summary-first, but branch detail still appears inline on executable lines:

7 ✓ |                 if (x > 0) {                        | hits:2 branches:true=1 false=1

When multiple branch sites map to the same source line, Acton keeps them separate:

31 ✓ | return foo != null ? foo : 100; | hits:1 branches:site0 true=0 false=1; site1 true=1 false=0

Export coverage data

LCOV format

Acton can write LCOV for external tools such as:

• VS Code Coverage Gutters
• IntelliJ IDEA Coverage
• LCOV tools and report generators

To emit lcov.info in the project root:

acton test --coverage --coverage-format lcov

That writes lcov.info in the project root.

For both the browser view and an LCOV artifact on disk, pass all three flags:

acton test --coverage --ui --coverage-format lcov

Text format

Acton can also write a line-by-line text artifact:

acton test --coverage --coverage-format text

That writes coverage.txt in the project root. Use --coverage-file to choose a different path for either format:

acton test --coverage --coverage-format text --coverage-file build/reports/coverage.txt
acton test --coverage --coverage-format lcov --coverage-file build/reports/lcov.info

LCOV with other tools

After lcov.info exists, typical follow-ups include:

# Generate HTML report
genhtml lcov.info -o coverage-report/

# View coverage in VS Code with Coverage Gutters extension
# The lcov.info file will be automatically detected

# Use with other CI/CD tools that support LCOV

Minimum coverage gate

Use --coverage-minimum-percent to fail the run when the blended coverage score drops below a threshold:

acton test --coverage --coverage-minimum-percent 80

The threshold uses the Score column, not line coverage alone. It is applied after the report is printed and accepts values from 0 to 100.

Guidelines

1. Set realistic coverage targets

• Aim for high, ≥80% line coverage on critical paths; 100% is rarely worth the cost.
• Spend effort on complex branches and error paths.

2. Treat coverage as a signal, not proof

• Coverage does not measure assertion quality.
• Full line coverage does not imply absence of bugs.
• Pair coverage with edge-case tests and, when needed, mutation testing.

Interpretation caveats

• Executable lines come from source-map debug locations, not from every physical line in the file.
• The text coverage artifact summarizes only line totals at the top. Branch detail appears inline on annotated executable lines.
• % Branches can be n/a for files where no branch sites were observed.
• Branch totals are runtime-observed, not a full static control-flow denominator for untouched code.
• --coverage-minimum-percent is ignored with --ui.

Performance

• Coverage adds execution overhead.
• For large test suites, run coverage selectively or export LCOV once with --coverage-format lcov and inspect offline.

Summary

Coverage helps with:

1. Measuring reachability: see which code lines are tested;
2. Spotting gaps: find untouched paths or branches;
3. Prioritizing tests: focus on low-coverage hot spots;
4. Maintaining quality: ensure new code does not reduce the coverage.