testing/libfuzzer/blackbox_coverage.md

# Generating Local Code Coverage for Blackbox Fuzzers

This document explains how to generate a local code coverage report for a
blackbox fuzzer. A local coverage report helps you visualize which code paths
your fuzzer exercises.

The [view_fuzzer_coverage.py](https://chromium.googlesource.com/chromium/src/+/HEAD/tools/code_coverage/view_fuzzer_coverage.py)
script automates building the target with coverage instrumentation, running the
target against the test corpus
generated by your blackbox fuzzer, and generating an HTML report.

## Prerequisites

This guide assumes you have already run your blackbox fuzzer to generate the
output files that you want to run against the coverage-enabled target.

## Run the coverage script

Run the `view_fuzzer_coverage.py` script and provide the path to your test
corpus directory. The script will automatically configure the build, compile the
target, run it, and generate the report.

In your terminal, navigate to the `src` directory and run:

```shell
tools/code_coverage/view_fuzzer_coverage.py \
  --fuzzer-type blackbox \
  --target <target_binary> \
  --corpora-dir <path_to_corpora_dir> \
  --testcase-timeout <seconds> \
  --retain-build-dir
```

`view_fuzzer_coverage.py` runs with `vpython3`, which is required to use `xvfb`
when targeting chrome.

## View the report

Once the script finishes, it will automatically attempt to open the generated
HTML report (`index.html`) in Chrome.

If you are running this on a remote machine, you can start an HTTP server in the
 output HTML directory to view the report from your local browser:

```shell
cd out/coverage-html
python3 -m http.server 8000
```

Then open a browser on your local machine and navigate to
`<REMOTE_IP>:8000/index.html`. Replace `<REMOTE_IP>` with your remote machine's
IP address or hostname.