Tarpaulin

https://github.com/xd009642/tarpaulin
Admin
Tarpaulin is a code coverage reporting tool for Rust projects that uses line coverage analysis and...
Tokens:12,629
Snippets:149
Trust Score:9.2
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install Tarpaulin via cargo-binstall

Source: https://github.com/xd009642/tarpaulin/blob/develop/README.md

Installs the Tarpaulin binary using the cargo-binstall utility.

```text
cargo binstall cargo-tarpaulin
```

--------------------------------

### Run Tarpaulin on Example Project

Source: https://github.com/xd009642/tarpaulin/blob/develop/README.md

Execute Tarpaulin in the current working directory to generate coverage reports for an example project. This command will build and test the project, then report coverage.

```bash
cargo tarpaulin
Jan 30 21:43:33.715  INFO cargo_tarpaulin::config: Creating config
Jan 30 21:43:33.908  INFO cargo_tarpaulin: Running Tarpaulin
Jan 30 21:43:33.908  INFO cargo_tarpaulin: Building project
Jan 30 21:43:33.908  INFO cargo_tarpaulin::cargo: Cleaning project
   Compiling simple_project v0.1.0 (/home/daniel/personal/tarpaulin/tests/data/simple_project)
    Finished test [unoptimized + debuginfo] target(s) in 0.51s
Jan 30 21:43:34.631  INFO cargo_tarpaulin::process_handling::linux: Launching test
Jan 30 21:43:34.631  INFO cargo_tarpaulin::process_handling: running /home/daniel/personal/tarpaulin/tests/data/simple_project/target/debug/deps/simple_project-417a21905eb8be09

running 1 test
test tests::bad_test ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.02s

Jan 30 21:43:35.563  INFO cargo_tarpaulin::report: Coverage Results:
|| Uncovered Lines:
|| src/lib.rs: 6
|| src/unused.rs: 4-6
|| Tested/Total Lines:
|| src/lib.rs: 3/4
|| src/unused.rs: 0/3
||
42.86% coverage, 3/7 lines covered
```

--------------------------------

### Configure Travis CI for Tarpaulin

Source: https://github.com/xd009642/tarpaulin/blob/develop/README.md

Example configuration for running Tarpaulin on Travis CI, including dependency installation and conditional coverage reporting.

```yml
language: rust
# tarpaulin has only been tested on bionic and trusty other distros may have issues
dist: bionic
addons:
    apt:
        packages:
            - libssl-dev
cache: cargo
rust:
  - stable
  - beta
  - nightly
matrix:
  allow_failures:
    - rust: nightly

before_script: |
  if [[ "$TRAVIS_RUST_VERSION" == stable ]]; then
    cargo install cargo-tarpaulin
  fi

script:
- cargo clean
- cargo build
- cargo test

after_success: |
  if [[ "$TRAVIS_RUST_VERSION" == stable ]]; then
    # Uncomment the following line for coveralls.io
    # cargo tarpaulin --ciserver travis-ci --coveralls $TRAVIS_JOB_ID

    # Uncomment the following two lines create and upload a report for codecov.io
    # cargo tarpaulin --out xml
    # bash <(curl -s https://codecov.io/bash)
  fi
```

--------------------------------

### Install Tarpaulin with Vendored OpenSSL

Source: https://github.com/xd009642/tarpaulin/blob/develop/TROUBLESHOOTING.md

Install Tarpaulin with the `vendored-openssl` feature to resolve issues with missing libssl.so.1.1.

```bash
cargo install --features vendored-openssl cargo-tarpaulin
```

--------------------------------

### Install Tarpaulin via Cargo

Source: https://github.com/xd009642/tarpaulin/blob/develop/README.md

Installs the Tarpaulin binary into the development environment using a locked dependency configuration.

```text
cargo install --locked cargo-tarpaulin
```

--------------------------------

### Get Tarpaulin Help

Source: https://github.com/xd009642/tarpaulin/blob/develop/README.md

Call this command to display detailed help on available arguments for Tarpaulin.

```bash
cargo tarpaulin --help
```

--------------------------------

### Configure GitHub Actions for Coverage

Source: https://context7.com/xd009642/tarpaulin/llms.txt

Example workflow for running Tarpaulin in a container and uploading results to codecov.io.

```yaml
# .github/workflows/coverage.yml
name: coverage

on: [push]
jobs:
  test:
    name: coverage
    runs-on: ubuntu-latest
    container:
      image: xd009642/tarpaulin:develop-nightly
      options: --security-opt seccomp=unconfined
    steps:
      - name: Checkout repository
        uses: actions/checkout@v2

      - name: Generate code coverage
        run: |
          cargo +nightly tarpaulin --verbose --all-features --workspace --timeout 120 --out xml

      - name: Upload to codecov.io
        uses: codecov/codecov-action@v5
        with:
          token: ${{secrets.CODECOV_TOKEN}}
          fail_ci_if_error: true
```

--------------------------------

### Debugging and Verbose Output

Source: https://context7.com/xd009642/tarpaulin/llms.txt

Get detailed information about coverage runs for troubleshooting.

```APIDOC
## Debugging and Verbose Output

### Description
Get detailed information about coverage runs for troubleshooting.

### Command Examples

- **Enable verbose output**
  ```bash
  cargo tarpaulin --verbose
  ```

- **Enable debug output for diagnosing issues**
  ```bash
  cargo tarpaulin --debug
  ```

- **Dump trace events to a JSON file**
  ```bash
  cargo tarpaulin --dump-traces
  ```

- **Print tarpaulin logs to stderr (test output to stdout)**
  ```bash
  cargo tarpaulin --stderr
  ```

- **Print RUSTFLAGS that will be used**
  ```bash
  cargo tarpaulin --print-rust-flags
  ```

- **Print RUSTDOCFLAGS for doctests**
  ```bash
  cargo tarpaulin --print-rustdoc-flags
  ```
```

--------------------------------

### Configure CircleCI for Coverage

Source: https://context7.com/xd009642/tarpaulin/llms.txt

Example configuration for running Tarpaulin via Docker in a CircleCI pipeline.

```yaml
# .circleci/config.yml
jobs:
  coverage:
    machine: true
    steps:
      - checkout
      - run:
          name: Coverage with docker
          command: |
            docker run --rm --security-opt seccomp=unconfined \
              -v "${PWD}:/volume" xd009642/tarpaulin \
              cargo tarpaulin --out Xml
      - store_artifacts:
          path: cobertura.xml
```

--------------------------------

### Tarpaulin Linux State Machine Diagram

Source: https://github.com/xd009642/tarpaulin/wiki/Developers

This diagram illustrates the state transitions for Tarpaulin's test execution loop on Linux. It includes states like START, INIT, WAIT, STOP, and END, along with transitions and conditions.

```text
                       +
                       |
                       |  +---------+
                       |  |         |
                 +-----v--v--+      |
     +-----------+   START   +------+
     |           +----+------+
     |                |
     |                |
     |           +----v------+
     |           |   INIT    +----------------+
     |           +----+------+
     |                |
     |                |    +-----------+
     |                |    |           |
     |          +-+---v----+-+         |
     |   +------>    WAIT    <---+     |
     |   |      +-----+--+---+   |
     |   |            |  |
     |   |            |  +-------+
     |   |            |
     |   |      +-----v------+
     |   +------|    STOP    +
     |          +-----+------+
     |                |
     |                |
     |         +------v------+
     +--------->     END     <--------+
               +-------------+
```

--------------------------------

### Define Tarpaulin Configuration in TOML

Source: https://github.com/xd009642/tarpaulin/blob/develop/README.md

Use a TOML file to define multiple coverage setups and report output formats.

```toml
[feature_a_coverage]
features = "feature_a"

[feature_a_and_b_coverage]
features = "feature_a feature_b"
release = true

[report]
coveralls = "coveralls_key"
out = ["Html", "Xml"]
```

--------------------------------

### Rust Derive Macro Example

Source: https://github.com/xd009642/tarpaulin/wiki/Developers

This Rust code demonstrates a derive macro. Tarpaulin may partially map generated code to the derive statement, but executable lines outside the project source can cause missed line flags.

```Rust
#[derive(Debug)]
struct SomeStruct;
```

--------------------------------

### Tarpaulin Linux State Machine Happy Path

Source: https://github.com/xd009642/tarpaulin/wiki/Developers

This diagram represents the simplified 'happy path' of Tarpaulin's state machine, assuming no errors and no waiting for signals. It outlines the core sequence of states from START to END.

```text
             +
             |
             |
        +----v------+
        |   START   |
        +----+------+
             |
             |
        +----v------+
        |   INIT    |
        +----+------+
             |
             |
       +-----v------+
+------>    WAIT    |
|      +-----+------+
|            |
|            |
|            |
|      +-----v------+
+------+    STOP    |
       +-----+------+
             |
             |
      +------v------+
      |     END     |
      +-------------+
```

--------------------------------

### Rust Generic Function Example

Source: https://github.com/xd009642/tarpaulin/wiki/Developers

This Rust code defines a generic function. Unused meta-programming code, like this unused generic function, needs to be included in statistics via source analysis as it doesn't generate assembly.

```Rust
fn foo<T>(t: T) {
    // Some code
}
```

--------------------------------

### Run Basic Coverage

Source: https://context7.com/xd009642/tarpaulin/llms.txt

Execute a standard coverage run using default settings in the project directory.

```bash
cargo tarpaulin
```

--------------------------------

### Select Coverage Engine

Source: https://context7.com/xd009642/tarpaulin/llms.txt

Choose the underlying tracing backend for coverage collection.

```bash
cargo tarpaulin --engine llvm
cargo tarpaulin --engine ptrace
cargo tarpaulin --engine auto
```

--------------------------------

### Integrate with Coveralls

Source: https://context7.com/xd009642/tarpaulin/llms.txt

Upload coverage results to Coveralls.io using various CI server configurations.

```bash
# Upload to coveralls with repo token
cargo tarpaulin --coveralls $COVERALLS_TOKEN

# Specify CI server for proper integration
cargo tarpaulin --coveralls $TRAVIS_JOB_ID --ciserver travis-ci

# Use custom report URI
cargo tarpaulin --coveralls $TOKEN --report-uri https://custom.endpoint.com/report

# Supported CI servers: travis-ci, travis-pro, circle-ci, codeship, jenkins, semaphore
cargo tarpaulin --coveralls $TOKEN --ciserver circle-ci
```

--------------------------------

### Configure Workspace and Packages

Source: https://context7.com/xd009642/tarpaulin/llms.txt

Manage coverage scope for multi-package workspaces and specific project paths.

```bash
cargo tarpaulin --workspace
cargo tarpaulin --packages my_crate --packages my_other_crate
cargo tarpaulin --workspace --exclude my_excluded_crate
cargo tarpaulin --manifest-path /path/to/Cargo.toml
cargo tarpaulin --root /path/to/project
```

--------------------------------

### Follow Executions with Ptrace Engine

Source: https://github.com/xd009642/tarpaulin/blob/develop/TROUBLESHOOTING.md

Employ the `--follow-exec` flag with the ptrace engine if your tests involve a significant number of process spawns.

```bash
--follow-exec
```

--------------------------------

### Use LLVM Engine on Linux

Source: https://github.com/xd009642/tarpaulin/blob/develop/TROUBLESHOOTING.md

If encountering issues with the default ptrace engine on Linux, try using the `--engine llvm` flag.

```bash
--engine llvm
```

--------------------------------

### Generate Coverage Reports

Source: https://context7.com/xd009642/tarpaulin/llms.txt

Specify output formats and directories using the --out and --output-dir flags.

```bash
cargo tarpaulin --out Html
cargo tarpaulin --out Xml
cargo tarpaulin --out Lcov
cargo tarpaulin --out Json
cargo tarpaulin --out Markdown
cargo tarpaulin --out Html --out Xml --out Json
cargo tarpaulin --out Html --output-dir ./coverage_reports
```

--------------------------------

### Enforce Coverage Thresholds

Source: https://context7.com/xd009642/tarpaulin/llms.txt

Set a minimum percentage requirement to fail the build if coverage is insufficient.

```bash
cargo tarpaulin --fail-under 80
cargo tarpaulin --fail-under 75 --out Xml
```

--------------------------------

### Configure Tarpaulin Performance and Timeouts

Source: https://context7.com/xd009642/tarpaulin/llms.txt

Use these command-line flags to manage test execution time, parallel jobs, and build cleanup behavior.

```bash
# Set test timeout to 5 minutes
cargo tarpaulin --timeout 300

# Set number of parallel build jobs
cargo tarpaulin --jobs 4

# Skip the clean step to speed up subsequent runs
cargo tarpaulin --skip-clean

# Force a clean build
cargo tarpaulin --force-clean

# Build in release mode
cargo tarpaulin --release
```

--------------------------------

### Define Tarpaulin Configuration File

Source: https://context7.com/xd009642/tarpaulin/llms.txt

Create a tarpaulin.toml file in the project root to manage reusable settings for different environments and reporting needs.

```toml
# tarpaulin.toml

[default]
# Basic configuration
manifest-path = "./Cargo.toml"
timeout = "10m"
output-dir = "./coverage"

# Test configuration
run-types = ["Tests", "Doctests"]
count = true

# Feature configuration
all-features = false
features = "feature_a feature_b"

# File filtering
exclude-files = ["tests/data/*", "benches/*"]

# Engine selection
engine = "Llvm"

[ci]
# CI-specific configuration
workspace = true
out = ["Html", "Xml"]
fail-under = 80.0
skip-clean = true

[feature_a_coverage]
# Run coverage with specific feature enabled
features = "feature_a"
out = ["Html"]

[release_coverage]
# Coverage in release mode
release = true
features = "feature_a feature_b"
out = ["Xml"]

[report]
# Report-only configuration (doesn't run tests)
coveralls = "your_coveralls_key"
out = ["Html", "Xml"]
```

--------------------------------

### Generate Cobertura Report

Source: https://github.com/xd009642/tarpaulin/blob/develop/README.md

Run this command to generate a cobertura.xml file for use with external tools like pycobertura.

```text
cargo tarpaulin --out xml
```

--------------------------------

### Advanced Test Execution CLI Options

Source: https://context7.com/xd009642/tarpaulin/llms.txt

Fine-tune test execution behavior, including handling ignored tests, failure thresholds, and build profiles.

```bash
# Run ignored tests as well
cargo tarpaulin --ignored

# Continue running after test failures
cargo tarpaulin --no-fail-fast

# Fail immediately after first test failure
cargo tarpaulin --fail-immediately

# Include test function lines in coverage statistics
cargo tarpaulin --include-tests

# Ignore panic macros in tests
cargo tarpaulin --ignore-panics

# Pass arguments to test executables
cargo tarpaulin -- --nocapture --test-threads=1

# Follow executed processes for coverage
cargo tarpaulin --follow-exec

# Use specific build profile
cargo tarpaulin --profile release-with-debug

# Avoid adding --cfg=tarpaulin to RUSTFLAGS
cargo tarpaulin --avoid-cfg-tarpaulin
```

--------------------------------

### Run Tarpaulin with Coverage Change Reporting

Source: https://github.com/xd009642/tarpaulin/blob/develop/README.md

Execute Tarpaulin to report coverage changes between runs. This output shows an increase in coverage for specific files.

```text
cargo tarpaulin
Jan 30 21:45:37.611  INFO cargo_tarpaulin::config: Creating config
Jan 30 21:45:37.623  INFO cargo_tarpaulin: Running Tarpaulin
Jan 30 21:45:37.623  INFO cargo_tarpaulin: Building project
Jan 30 21:45:37.623  INFO cargo_tarpaulin::cargo: Cleaning project
   Compiling simple_project v0.1.0 (/home/daniel/personal/tarpaulin/tests/data/simple_project)
    Finished test [unoptimized + debuginfo] target(s) in 0.40s
Jan 30 21:45:38.085  INFO cargo_tarpaulin::process_handling::linux: Launching test
Jan 30 21:45:38.085  INFO cargo_tarpaulin::process_handling: running /home/daniel/personal/tarpaulin/tests/data/simple_project/target/debug/deps/simple_project-417a21905eb8be09

running 2 tests
test unused::blah ... ok
test tests::bad_test ... ok

test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.02s

Jan 30 21:45:38.990  INFO cargo_tarpaulin::report: Coverage Results:
|| Uncovered Lines:
|| src/lib.rs: 6
|| Tested/Total Lines:
|| src/lib.rs: 3/4 +0.00%
|| src/unused.rs: 3/3 +100.00%
||
85.71% coverage, 6/7 lines covered, +42.86% change in coverage
```

--------------------------------

### Forward Unix Signals with Ptrace Engine

Source: https://github.com/xd009642/tarpaulin/blob/develop/TROUBLESHOOTING.md

Use the `--forward-signals` flag when using the ptrace engine to mitigate issues where tarpaulin might steal Unix signals.

```bash
--forward-signals
```

--------------------------------

### Run Tarpaulin in Docker

Source: https://github.com/xd009642/tarpaulin/blob/develop/README.md

Execute Tarpaulin within a Docker container, mounting the current directory to the volume.

```text
docker run --rm --security-opt seccomp=unconfined -v "${PWD}:/volume" xd009642/tarpaulin
```

```text
docker run --rm --security-opt seccomp=unconfined -v "${PWD}:/volume" xd009642/tarpaulin:develop-nightly
```

```text
docker run --rm --security-opt seccomp=unconfined -v "${PWD}:/volume" xd009642/tarpaulin sh -c "apt-get install xxx && cargo tarpaulin"
```

--------------------------------

### TraceMap API

Source: https://context7.com/xd009642/tarpaulin/llms.txt

Work with coverage data programmatically using the TraceMap structure.

```APIDOC
## TraceMap API

### Description
Work with coverage data programmatically using the TraceMap structure.

### Rust Code Example

```rust
use cargo_tarpaulin::traces::{TraceMap, Trace, CoverageStat};
use std::path::Path;
use std::collections::HashSet;

// Create a new trace map
let mut tracemap = TraceMap::new();

// Add traces for a file
let mut address = HashSet::new();
address.insert(0x1000);
let trace = Trace::new(42, address, 4);  // line 42, address, length
tracemap.add_trace(Path::new("src/lib.rs"), trace);

// Query coverage statistics
let total_coverable = tracemap.total_coverable();
let total_covered = tracemap.total_covered();
let percentage = tracemap.coverage_percentage();

println!("Coverage: {:.2}% ({}/{})",
    percentage * 100.0, total_covered, total_coverable);

// Iterate over files
for file in tracemap.files() {
    let covered = tracemap.covered_in_path(file);
    let coverable = tracemap.coverable_in_path(file);
    println!("{}: {}/{}", file.display(), covered, coverable);
}

// Merge results from multiple runs
let mut other_tracemap = TraceMap::new();
// ... add traces to other_tracemap
tracemap.merge(&other_tracemap);
tracemap.dedup();  // Remove duplicate entries
```
```

--------------------------------

### Configure Gitlab CI Coverage

Source: https://github.com/xd009642/tarpaulin/blob/develop/README.md

Add the coverage regex to your .gitlab-ci.yml file to display results in Gitlab pipelines.

```yml
job: ...
  coverage: '/^\d+.\d+% coverage/'
```

--------------------------------

### Run Tarpaulin in Docker

Source: https://context7.com/xd009642/tarpaulin/llms.txt

Execute coverage analysis within a Docker container to ensure consistent environments.

```bash
# Basic docker run
docker run --rm --security-opt seccomp=unconfined \
  -v "${PWD}:/volume" xd009642/tarpaulin

# Use specific version with nightly compiler
docker run --rm --security-opt seccomp=unconfined \
  -v "${PWD}:/volume" xd009642/tarpaulin:develop-nightly

# Install dependencies and run
docker run --rm --security-opt seccomp=unconfined \
  -v "${PWD}:/volume" xd009642/tarpaulin \
  sh -c "apt-get install -y libssl-dev && cargo tarpaulin"

# Run with specific options
docker run --rm --security-opt seccomp=unconfined \
  -v "${PWD}:/volume" xd009642/tarpaulin \
  cargo tarpaulin --out Html --all-features
```

--------------------------------

### Debug and Verbose CLI Flags

Source: https://context7.com/xd009642/tarpaulin/llms.txt

Use these flags to troubleshoot coverage runs, dump trace events, or inspect environment variables.

```bash
# Enable verbose output
cargo tarpaulin --verbose

# Enable debug output for diagnosing issues
cargo tarpaulin --debug

# Dump trace events to a JSON file
cargo tarpaulin --dump-traces

# Print tarpaulin logs to stderr (test output to stdout)
cargo tarpaulin --stderr

# Print RUSTFLAGS that will be used
cargo tarpaulin --print-rust-flags

# Print RUSTDOCFLAGS for doctests
cargo tarpaulin --print-rustdoc-flags
```

--------------------------------

### Programmatic Library API Usage

Source: https://context7.com/xd009642/tarpaulin/llms.txt

Integrate Tarpaulin into custom Rust applications by configuring and running the coverage engine programmatically.

```rust
use cargo_tarpaulin::config::{Config, ConfigWrapper, OutputFile, RunType, TraceEngine};
use cargo_tarpaulin::{run, trace, launch_tarpaulin, setup_logging};
use cargo_tarpaulin::config::Color;

fn main() -> Result<(), cargo_tarpaulin::errors::RunError> {
    // Set up logging
    setup_logging(Color::Auto, false, true, false);

    // Create configuration
    let mut config = Config::default();
    config.set_manifest(std::path::PathBuf::from("./Cargo.toml"));
    config.generate = vec![OutputFile::Html, OutputFile::Json];
    config.run_types = vec![RunType::Tests];
    config.set_engine(TraceEngine::Llvm);

    // Run coverage collection
    let configs = vec![config];
    run(&configs)?;

    Ok(())
}
```

--------------------------------

### Advanced Test Execution Options

Source: https://context7.com/xd009642/tarpaulin/llms.txt

Fine-tune test execution behavior.

```APIDOC
## Advanced Test Execution Options

### Description
Fine-tune test execution behavior.

### Command Examples

- **Run ignored tests as well**
  ```bash
  cargo tarpaulin --ignored
  ```

- **Continue running after test failures**
  ```bash
  cargo tarpaulin --no-fail-fast
  ```

- **Fail immediately after first test failure**
  ```bash
  cargo tarpaulin --fail-immediately
  ```

- **Include test function lines in coverage statistics**
  ```bash
  cargo tarpaulin --include-tests
  ```

- **Ignore panic macros in tests**
  ```bash
  cargo tarpaulin --ignore-panics
  ```

- **Pass arguments to test executables**
  ```bash
  cargo tarpaulin -- --nocapture --test-threads=1
  ```

- **Follow executed processes for coverage**
  ```bash
  cargo tarpaulin --follow-exec
  ```

- **Use specific build profile**
  ```bash
  cargo tarpaulin --profile release-with-debug
  ```

- **Avoid adding --cfg=tarpaulin to RUSTFLAGS**
  ```bash
  cargo tarpaulin --avoid-cfg-tarpaulin
  ```
```

--------------------------------

### Configure Cargo Features

Source: https://context7.com/xd009642/tarpaulin/llms.txt

Control feature flags during the coverage build process.

```bash
cargo tarpaulin --all-features
cargo tarpaulin --no-default-features
cargo tarpaulin --features "feature_a feature_b"
cargo tarpaulin --no-default-features --features "my_feature"
```

--------------------------------

### Library API Usage

Source: https://context7.com/xd009642/tarpaulin/llms.txt

Use Tarpaulin programmatically in Rust code for custom coverage tooling.

```APIDOC
## Library API Usage

### Description
Use Tarpaulin programmatically in Rust code for custom coverage tooling.

### Rust Code Example

```rust
use cargo_tarpaulin::config::{Config, ConfigWrapper, OutputFile, RunType, TraceEngine};
use cargo_tarpaulin::{run, trace, launch_tarpaulin, setup_logging};
use cargo_tarpaulin::config::Color;

fn main() -> Result<(), cargo_tarpaulin::errors::RunError> {
    // Set up logging
    setup_logging(Color::Auto, false, true, false);

    // Create configuration
    let mut config = Config::default();
    config.set_manifest(std::path::PathBuf::from("./Cargo.toml"));
    config.generate = vec![OutputFile::Html, OutputFile::Json];
    config.run_types = vec![RunType::Tests];
    config.set_engine(TraceEngine::Llvm);

    // Run coverage collection
    let configs = vec![config];
    run(&configs)?;

    Ok(())
}
```
```

--------------------------------

### Configure Gitlab Coverage Report Artifacts

Source: https://github.com/xd009642/tarpaulin/blob/develop/README.md

Define the coverage report artifact in .gitlab-ci.yml to enable coverage visualization in merge request diffs.

```yml
job: ...
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: cobertura.xml
```

--------------------------------

### Configure CircleCI for Tarpaulin

Source: https://github.com/xd009642/tarpaulin/blob/develop/README.md

Job configuration for running Tarpaulin inside a Docker container on CircleCI using the machine executor.

```yml
jobs:
  coverage:
    machine: true
    steps:
      - checkout
      - run:
          name: Coverage with docker
          command: docker run --rm --security-opt seccomp=unconfined -v "${PWD}:/volume" xd009642/tarpaulin
```

--------------------------------

### Configure GitHub Actions for Codecov

Source: https://github.com/xd009642/tarpaulin/blob/develop/README.md

Workflow configuration for running Tarpaulin in a Docker container within GitHub Actions and uploading results to Codecov.

```yml
name: coverage

on: [push]
jobs:
  test:
    name: coverage
    runs-on: ubuntu-latest
    container:
      image: xd009642/tarpaulin:develop-nightly
      options: --security-opt seccomp=unconfined
    steps:
      - name: Checkout repository
        uses: actions/checkout@v2

      - name: Generate code coverage
        run: |
          cargo +nightly tarpaulin --verbose --all-features --workspace --timeout 120 --out xml

      - name: Upload to codecov.io
        uses: codecov/codecov-action@v5
        with:
          token: ${{secrets.CODECOV_TOKEN}}
          fail_ci_if_error: true
```

--------------------------------

### TraceMap API for Coverage Data

Source: https://context7.com/xd009642/tarpaulin/llms.txt

Manipulate and query coverage data structures directly using the TraceMap API.

```rust
use cargo_tarpaulin::traces::{TraceMap, Trace, CoverageStat};
use std::path::Path;
use std::collections::HashSet;

// Create a new trace map
let mut tracemap = TraceMap::new();

// Add traces for a file
let mut address = HashSet::new();
address.insert(0x1000);
let trace = Trace::new(42, address, 4);  // line 42, address, length
tracemap.add_trace(Path::new("src/lib.rs"), trace);

// Query coverage statistics
let total_coverable = tracemap.total_coverable();
let total_covered = tracemap.total_covered();
let percentage = tracemap.coverage_percentage();

println!("Coverage: {:.2}% ({}/{})",
    percentage * 100.0, total_covered, total_coverable);

// Iterate over files
for file in tracemap.files() {
    let covered = tracemap.covered_in_path(file);
    let coverable = tracemap.coverable_in_path(file);
    println!("{}: {}/{}", file.display(), covered, coverable);
}

// Merge results from multiple runs
let mut other_tracemap = TraceMap::new();
// ... add traces to other_tracemap
tracemap.merge(&other_tracemap);
tracemap.dedup();  // Remove duplicate entries
```

--------------------------------

### Configure Tarpaulin in GitLab CI

Source: https://context7.com/xd009642/tarpaulin/llms.txt

Use this YAML configuration to run Tarpaulin in a GitLab CI pipeline and export Cobertura reports.

```yaml
coverage:
  image: xd009642/tarpaulin:develop-nightly
  script:
    - cargo tarpaulin --out Xml
  coverage: '/^\d+.\d+% coverage/'
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: cobertura.xml
```

--------------------------------

### Filter Files

Source: https://context7.com/xd009642/tarpaulin/llms.txt

Include or exclude specific files or directories using glob patterns.

```bash
cargo tarpaulin --exclude-files "tests/*" --exclude-files "**/generated/*"
cargo tarpaulin --include-files "src/core/*" --include-files "src/lib.rs"
cargo tarpaulin --exclude-files "fuzz/*" --exclude-files "src/test_utils/*"
```

--------------------------------

### Configure Test Types

Source: https://context7.com/xd009642/tarpaulin/llms.txt

Filter which test targets or types are included in the coverage run.

```bash
cargo tarpaulin --tests
cargo tarpaulin --doc
cargo tarpaulin --all-targets --doc
cargo tarpaulin --benches
cargo tarpaulin --examples
cargo tarpaulin --lib
cargo tarpaulin --bins
cargo tarpaulin --test integration_tests
cargo tarpaulin --bin my_binary
cargo tarpaulin --example my_example
```

--------------------------------

### Disable Dead Code Linking

Source: https://github.com/xd009642/tarpaulin/blob/develop/TROUBLESHOOTING.md

Use the `--no-dead-code` argument to resolve compilation errors related to dead-code linking when tarpaulin fails to compile your project.

```bash
--no-dead-code
```

--------------------------------

### Ignore Code with Nightly Tool Attribute

Source: https://github.com/xd009642/tarpaulin/blob/develop/README.md

Utilize nightly Rust features with `#[tarpaulin::skip]` to exclude code from coverage statistics. This requires enabling the `register_tool` and `tool_attributes` features.

```rust
#![feature(register_tool)]
#![register_tool(tarpaulin)]

#[tarpaulin::skip]
fn main() {
    println!("I won't be in coverage stats");
}
```

--------------------------------

### Ignore Test by Default with Tarpaulin

Source: https://github.com/xd009642/tarpaulin/blob/develop/README.md

Use `#[cfg_attr(tarpaulin, ignore)]` to have a test included in the binary but ignored by Tarpaulin by default. This allows the test to be run normally but skipped during coverage analysis.

```rust
#[test]
#[cfg_attr(tarpaulin, ignore)]
fn ignored_by_tarpaulin() {

}
```

--------------------------------

### Ignore Main Function with cfg attribute

Source: https://github.com/xd009642/tarpaulin/blob/develop/README.md

Use the `#[cfg(not(tarpaulin_include))]` attribute to exclude the main function from coverage reports. This attribute prevents the function from being included in the coverage statistics.

```rust
#[cfg(not(tarpaulin_include))]
fn main() {
    println!("I won't be included in results");
}

// Also supports the nightly rustc `coverage(off)` attribute.
#[coverage(off)]
fn not_included() {

}
```

--------------------------------

### Conditionally Exclude Test from Tarpaulin Build

Source: https://github.com/xd009642/tarpaulin/blob/develop/README.md

Use `#[cfg(not(tarpaulin))]` to prevent a test from being compiled when Tarpaulin is building the project. This is useful for tests that are slow or incompatible with Tarpaulin.

```rust
#[test]
#[cfg(not(tarpaulin))]
fn big_test_not_for_tarpaulin() {
    // Something that would be very slow in tarpaulin or not work
}
```

--------------------------------

### Avoid Inlining with Tarpaulin

Source: https://github.com/xd009642/tarpaulin/blob/develop/TROUBLESHOOTING.md

Use this attribute to prevent inlining for Tarpaulin-specific builds, ensuring better debug information for coverage analysis.

```rust
#[cfg_attr(tarpaulin, inline(never))]
```

--------------------------------

### Exclude Code from Coverage Analysis

Source: https://context7.com/xd009642/tarpaulin/llms.txt

Apply these attributes to functions or tests to prevent them from being included in coverage reports.

```rust
// Exclude a function from coverage using cfg attribute
#[cfg(not(tarpaulin_include))]
fn main() {
    println!("I won't be included in coverage results");
}

// Use nightly coverage(off) attribute
#[coverage(off)]
fn not_included() {
    // This function is excluded from coverage
}

// Conditionally compile code only when NOT running under tarpaulin
#[test]
#[cfg(not(tarpaulin))]
fn big_test_not_for_tarpaulin() {
    // This test won't run under tarpaulin
}

// Ignore test when running under tarpaulin
#[test]
#[cfg_attr(tarpaulin, ignore)]
fn ignored_by_tarpaulin() {
    // Test runs normally but ignored during coverage
}

// Using tool attributes (nightly only)
#![feature(register_tool)]
#![register_tool(tarpaulin)]

#[tarpaulin::skip]
fn skipped_function() {
    println!("I won't be in coverage stats");
}
```
Tokens:
Raw