Skip to content

Commit

Permalink
Add clear examples of what tools to use locally to display lcov (#101)
Browse files Browse the repository at this point in the history
<!-- Reference any GitHub issues resolved by this PR -->

Closes #94

## Introduced changes

<!-- A brief description of the changes -->

- Used locally now features examples to better introduce users

## Checklist

<!-- Make sure all of these are complete -->

- [x] Linked relevant issue
- [x] Updated relevant documentation
- [ ] Added relevant tests
- [ ] Performed self-review of the code
- [ ] Added changes to `CHANGELOG.md`
  • Loading branch information
ksew1 authored Nov 28, 2024
1 parent f9a5549 commit c7595b6
Showing 1 changed file with 28 additions and 14 deletions.
42 changes: 28 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,30 +35,44 @@ curl -L https://raw.githubusercontent.com/software-mansion/cairo-coverage/main/s

## Usage

### Generate coverage report
### 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`.
To generate a coverage report, run the `cairo-coverage` command with one or more `<PATH_TO_TRACE_DATA>` arguments. These
arguments specify the paths to the JSON files containing the trace data to be used for generating the coverage report.

### Output format
```shell
cairo-coverage path/to/trace/1.json path/to/trace/2.json path/to/trace/3.json
```

Optionally, you can specify an output file path using the `--output-path <OUTPUT_PATH>` option. If not provided, the
output file will default to `coverage.lcov`.

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](./lcov.md).

#### Example
#### Using `snforge`:

Please refer to
the [Starknet Foundry documentation](https://foundry-rs.github.io/starknet-foundry/testing/coverage.html) for additional
information on using `cairo-coverage` with `snforge`.

### Viewing Report

Before you can view the coverage report as an HTML file, **the report must first be generated**. Please refer to
the [Generate Coverage Report](#generate-coverage-report) section above for detailed instructions.

Once you have generated the `coverage.lcov` file, a summary report with aggregated data can be produced by one of the
many tools that accept the `lcov` format.

In this example, we will use the `genhtml` tool from
the [lcov package](https://github.com/linux-test-project/lcov/tree/master) to generate an HTML report. If you don’t
already have `genhtml` installed, you can find installation instructions [here](https://command-not-found.com/genhtml).

```shell
cairo-coverage path/to/trace/1.json path/to/trace/2.json path/to/trace/3.json
genhtml -o coverage_report coverage.lcov
```

### 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](https://github.com/linux-test-project/lcov/blob/master/bin/genhtml),
a tool that generates an html summary report using the coverage data in an lcov file, `genhtml` is part of
the [lcov package](https://github.com/linux-test-project/lcov/tree/master).
You can now open the `index.html` file in the `coverage_report` directory to see the generated coverage report.

## Usage in GitHub actions

Expand Down

0 comments on commit c7595b6

Please sign in to comment.