cairo-coverage

cairo-coverage is a utility designed to generate coverage reports for code written in the Cairo programming language.

⚠️ IMPORTANT: Please note that this repository is actively being developed and is currently in an alpha release stage. If you encounter any issues, please report them to us via the issues tab on our GitHub repository.

We currently don't support:

• Branch coverage

Things that might not work as expected:

• Counters for how many times line was executed

Installation

To install the latest stable version of cairo-coverage, run:

curl -L https://raw.githubusercontent.com/software-mansion/cairo-coverage/main/scripts/install.sh | sh

If you want to install a specific version, run the following command with the requested version:

curl -L https://raw.githubusercontent.com/software-mansion/cairo-coverage/main/scripts/install.sh | sh -s -- v0.1.0

Integrated tools

• Starknet Foundry - check how to use it with cairo-coverage here
• Cairo Test

Usage

Generate coverage report

To generate the report, run cairo-coverage with one or more <PATH_TO_TRACE_DATA> arguments, which specify the paths to the json files containing the trace data to be used for generating the coverage report. Optionally, you can provide the path to the output file using --output-path <OUTPUT_PATH>. If not specified, the output file will default to being saved as coverage.lcov.

Output format

The generated output file is in the lcov format. For your convenience, you can find an explanation along with a simple example of the lcov format here.

Example

cairo-coverage path/to/trace/1.json path/to/trace/2.json path/to/trace/3.json

Coverage statistics

Various tools exist that can produce coverage statistics based on an lcov file. One of the most well-known among these is genhtml, a tool that generates an html summary report using the coverage data in an lcov file, genhtml is part of the lcov package.

Usage in GitHub actions

A variety of GitHub actions are available for analyzing coverage data for continuous integration purposes, which can accept input in the form of an lcov file. Examples of such actions include CodeCov and Coveralls.

The example workflow below illustrates how to use coverage report generated by snforge in conjunction with CodeCov:

name: Example cairo coverage workflow
on:
  pull_request:
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: foundry-rs/setup-snfoundry@v3

      - name: Install cairo-coverage
        run: curl -L https://raw.githubusercontent.com/software-mansion/cairo-coverage/main/scripts/install.sh | sh

      - name: Run tests and generate report
        run: snforge test --coverage

      - name: Upload coverage to Codecov
        uses: codecov/codecov-action@v4
        with:
          file: ./coverage.lcov
          token: ${{ secrets.CODECOV_TOKEN }}

External tools integration

cairo-coverage is tool-agnostic which means that it accepts input from any tool. However, these tools need to generate trace data in a specific expected format - the same format which is accepted by the cairo-profiler. For the exact code implementation of this format, please refer to this page. For a practical example of how this format appears in a file, consider examining this json file.