cosmoline

Crates.iocosmoline
lib.rscosmoline
version0.1.1
sourcesrc
created_at2021-07-08 19:55:28.800638
updated_at2021-07-08 19:55:28.800638
descriptionCommand line tool to generate HTML code coverage reports for rust projects
homepage
repositoryhttps://github.com/inferiorhumanorgans/cosmoline
max_upload_size
id420455
size88,433
(inferiorhumanorgans)

documentation

README

cosmoline

What is it?

Cosmoline is a quick and dirty code coverage report generator for rust. It takes advantage of the source-based code coverage that landed in nightly back in November 2020.

How does it work?

Input: JSON from llvm-cov export (or its convenient wrapper cargo cov)

Output: Pretty HTML reports are rendered with handlebars-rs. The templates are located in the template directory and compiled into the cosmoline binary.

How do I use it?

Install the prerequsities

Instructions on how to configure nightly to build profiling data in the Rust Unstable Book.

Install jq (useful, but not strictly necessary):

On e.g. macOS:

brew install jq

Or Debian:

sudo apt-get install jq

Or FreeBSD:

sudo pkg install jq

Build and install cosmoline

# Check out this repo
git clone https://github.com/inferiorhumanorgans/cosmoline

# Install it with cargo
cargo +nightly install --path ./cosmoline

Export the JSON coverage data

For a single library from llvm using jq:

# Back in the directory for our own project
cd /path/to/my-app
export OUT_DIR="$(PWD)/coverage-report"
export APP_NAME="my-app"

# Run tests, save results as JUnit data
LLVM_PROFILE_FILE="${OUT_DIR}/${APP_NAME}-%m.profraw" RUSTFLAGS="-Z instrument-coverage" cargo +nightly test --lib -- -Z unstable-options --format=junit > ${OUT_DIR}/junit.xml

# Grab test executable
COV_EXEC=$(RUSTFLAGS="-Z instrument-coverage" cargo +nightly test --message-format=json --lib --no-run | jq -r "select(.profile.test == true) | .filenames[]" | head -1)

# Merge sparse files
cargo +nightly profdata -- merge --sparse "${OUT_DIR}/${APP_NAME}-"*.profraw -o "${OUT_DIR}/${APP_NAME}.profdata"

# Extract JSON formatted details
cargo +nightly cov -- export "${COV_EXEC}" -instr-profile="${OUT_DIR}/${APP_NAME}.profdata" > "${OUT_DIR}/${APP_NAME}.coverage.json"

Feed it into cosmoline

cosmoline --input "${OUT_DIR}/${APP_NAME}.coverage.json" --source-directory "$(PWD)" --output-directory "${OUT_DIR}/report"

The resulting report is self-contained and will be placed in ${OUT_DIR}/report/index.html.

View the results

A typical report might look like this:

Report Index

Note that the percentages listed will be colored red, yellow, or green depending on the proportion of the file that's been covered.

Clicking on a filename will take you to an annotated rendering of that file's contents:

File Detail

Code that's been instrumented is highlighted in red if it was not executed and green if the code's been executed. Code that has not been instrumented remains white.

TODO

  • render clippy warnings?
  • refactor CSS
  • include cargo and git metadata
Commit count: 13

cargo fmt