Coverage collection

There are two main ways to calculate coverage of your @ton/sandbox tests.

Easy way

When using blueprint, the only thing you need to collect coverage is to run

blueprint test --coverage

Results will appear in coverage/ directory as HTML files with reports for each of your contracts.

Customizable way

There might be some reasons why you don’t want to simply use --coverage.

You don’t want to collect coverage for all contracts.
You use @ton/sandbox but don’t use @ton/blueprint.
Not all contracts have source code. (For example, for each transaction you deploy a new contract, and you don’t have wrappers for it).
You want to get the raw data and customize the output.

1. Enable coverage collection

Before running tests, add blockchain.enableCoverage() to collect coverage data:

import {Blockchain} from '@ton/sandbox';

describe('Contract Tests', () => {
    let blockchain: Blockchain;
    let contract: SandboxContract<MyContract>;

    beforeEach(async () => {
        blockchain = await Blockchain.create();

        blockchain.enableCoverage();
        // or for COVERAGE=true mode only
        // blockchain.enableCoverage(process.env["COVERAGE"] === "true");

        // Deploy your contract
        contract = blockchain.openContract(MyContract.fromInit());
        // ... deployment logic
    });

    // Your tests here...
});

2. Collect coverage after tests

afterAll(() => {
    const coverage = blockchain.coverage(contract);
    console.log(coverage?.summary());
})

3. Generate reports

import {writeFileSync} from 'fs';

afterAll(() => {
    const coverage = blockchain.coverage(contract);
    if (!coverage) return;

    // Generate HTML report for detailed analysis
    const htmlReport = coverage.report("html");
    writeFileSync("coverage.html", htmlReport);

    // Print text text report to console
    const textReport = coverage.report("text");
    console.log(textReport);
});

Understanding coverage data

Coverage summary

The coverage summary provides key metrics about your test coverage:

const summary = coverage.summary();

console.log(`Total lines: ${summary.totalLines}`);
console.log(`Covered lines: ${summary.coveredLines}`);
console.log(`Coverage percentage: ${summary.coveragePercentage.toFixed(2)}%`);
console.log(`Total gas consumed: ${summary.totalGas}`);
console.log(`Total hits: ${summary.totalHits}`);

// Instruction-level statistics
summary.instructionStats.forEach(stat => {
    console.log(`${stat.name}: ${stat.totalHits} hits, ${stat.totalGas} gas, avg ${stat.avgGas}`);
});

Coverage reports

HTML Report: Interactive report with highlighting and line-by-line coverage details
Text Report: Console-friendly report with coverage information and marked code

Advanced usage patterns

Multiple test suites

When running multiple test files, you might want to merge coverage data:

// In first test file
const coverage1 = blockchain.coverage(contract);
if (!coverage1) return;
const coverage1Json = coverage1.toJson();
writeFileSync("coverage1.json", coverage1Json);

// In second test file
const coverage2 = blockchain.coverage(contract);
if (!coverage2) return;
const coverage2Json = coverage2.toJson();
writeFileSync("coverage2.json", coverage2Json);

// Merge coverage data in separate script after tests
const savedCoverage1 = Coverage.fromJson(readFileSync("coverage1.json", "utf-8"));
const savedCoverage2 = Coverage.fromJson(readFileSync("coverage2.json", "utf-8"));
const totalCoverage = savedCoverage1.mergeWith(savedCoverage2);

console.log(`Combined coverage: ${totalCoverage.summary().coveragePercentage}%`);

Coverage for multiple contracts

When testing systems with multiple contracts:

not runnable

describe('Multi-Contract System', () => {
    let blockchain: Blockchain;
    let contract1: SandboxContract<Contract1>;
    let contract2: SandboxContract<Contract2>;

    beforeEach(async () => {
        blockchain = await Blockchain.create();
        blockchain.enableCoverage();

        // Deploy multiple contracts
        contract1 = blockchain.openContract(Contract1.fromInit());
        contract2 = blockchain.openContract(Contract2.fromInit());
    });

    afterAll(() => {
        // Get coverage for each contract separately
        const coverage1 = blockchain.coverage(contract1);
        const coverage2 = blockchain.coverage(contract2);

        if (!coverage1 || !coverage2) return;

        console.log('Contract 1 Coverage:', coverage1.summary().coveragePercentage);
        console.log('Contract 2 Coverage:', coverage2.summary().coveragePercentage);

        // Generate separate reports
        writeFileSync("contract1-coverage.html", coverage1.report("html"));
        writeFileSync("contract2-coverage.html", coverage2.report("html"));
    });
});

Interpret results

The usual report looks like this: Apart from the header statistics, the line-by-line coverage report is the most informative. Most fields are self‑explanatory; the code section shows per‑instruction hit counts (blue) and gas cost (red). This helps you analyze both coverage and gas efficiency.

Limitations

Note that when code of other contracts is stored directly in the code of contract (Tact does that automatically if a contract system does not contain circular dependencies), that affects the overall code coverage percentage. To mitigate this effect in coverage estimation, add a circular dependency. For example, import a file with the following content.

contract A {
    receive() {
        let x = initOf B();
        drop2(x);
    }
}

contract B(
) {
    receive() {
        let x = initOf A();
        drop2(x);
    }
}

asm fun drop2(x: StateInit) {
    DROP2
}

Step-by-step guides

Ecosystem

Standard contracts

Contract patterns

Languages

TVM: TON Virtual Machine

Blockchain foundations

Web3 services

Contribute

Coverage collection

Easy way

Customizable way

1. Enable coverage collection

2. Collect coverage after tests

3. Generate reports

Understanding coverage data

Coverage summary

Coverage reports

Advanced usage patterns

Multiple test suites

Coverage for multiple contracts

Interpret results

Limitations

​Easy way

​Customizable way

​1. Enable coverage collection

​2. Collect coverage after tests

​3. Generate reports

​Understanding coverage data

​Coverage summary

​Coverage reports

​Advanced usage patterns

​Multiple test suites

​Coverage for multiple contracts

​Interpret results

​Limitations

Easy way

Customizable way

1. Enable coverage collection

2. Collect coverage after tests

3. Generate reports

Understanding coverage data

Coverage summary

Coverage reports

Advanced usage patterns

Multiple test suites

Coverage for multiple contracts

Interpret results

Limitations