diff --git a/COVERAGE_SETUP.md b/COVERAGE_SETUP.md index 0e95ac5c..9845df8b 100644 --- a/COVERAGE_SETUP.md +++ b/COVERAGE_SETUP.md @@ -21,11 +21,14 @@ The ocaml-containers project uses a custom preprocessor (`cpp.exe`) for OCaml ve ### CBOR Library (`src/cbor/dune`) ```ocaml -(preprocess (pps bisect_ppx)) +(instrumentation (backend bisect_ppx)) ``` **Result:** Full coverage instrumentation (100%) +**Note:** CBOR uses `instrumentation` stanza (cleaner) while core uses `pps` +(required for per-module preprocessing compatibility) + ## Modules Excluded from Coverage Only 3 modules require cpp preprocessing: @@ -40,24 +43,26 @@ These modules use `[@@@ifge 4.8]` style conditionals for OCaml version compatibi ### Generate Coverage Data ```bash -# Run tests with coverage -BISECT_FILE=_coverage/bisect dune runtest +# Run tests with coverage using instrumentation +dune runtest --instrument-with bisect_ppx # Or run specific test suite -BISECT_FILE=_coverage/bisect dune runtest tests/cbor +dune runtest tests/cbor --instrument-with bisect_ppx + +# Coverage files are written to _build/default/tests/*/*.coverage ``` ### Generate Reports ```bash # Summary -bisect-ppx-report summary --coverage-path=_coverage +bisect-ppx-report summary --coverage-path=_build # Per-file breakdown -bisect-ppx-report summary --coverage-path=_coverage --per-file +bisect-ppx-report summary --coverage-path=_build --per-file # HTML report -bisect-ppx-report html --coverage-path=_coverage -o _coverage/html +bisect-ppx-report html --coverage-path=_build -o _coverage/html ``` ### View HTML Report @@ -122,20 +127,20 @@ bisect-ppx-report html --coverage-path=_coverage -o _coverage/html ### Example Workflow ```bash # Initial run -BISECT_FILE=_coverage/bisect dune runtest tests/cbor -bisect-ppx-report summary --coverage-path=_coverage --per-file +dune runtest tests/cbor --instrument-with bisect_ppx +bisect-ppx-report summary --coverage-path=_build --per-file # View gaps -bisect-ppx-report html --coverage-path=_coverage -o _coverage/html +bisect-ppx-report html --coverage-path=_build -o _coverage/html firefox _coverage/html/src/cbor/containers_cbor.ml.html # Add tests to cover gaps # ... edit tests/core/t_cbor.ml ... -# Re-run -rm _coverage/*.coverage -BISECT_FILE=_coverage/bisect dune runtest tests/cbor -bisect-ppx-report summary --coverage-path=_coverage +# Re-run (dune automatically regenerates coverage) +dune clean +dune runtest tests/cbor --instrument-with bisect_ppx +bisect-ppx-report summary --coverage-path=_build ``` ## Benefits Achieved @@ -156,9 +161,13 @@ The `instrumentation` stanza cannot be combined with `(preprocess (action ...))` via per-module configuration. -### Why not `--conditional`? +### Why mix `instrumentation` and `pps bisect_ppx`? -We tried `(pps bisect_ppx --conditional)` initially, but it requires `BISECT_ENABLE=yes` to be set, which is less ergonomic. Without `--conditional`, coverage is always collected (small performance overhead but simpler workflow). +- **CBOR:** Uses `instrumentation` stanza (cleaner, dune's recommended approach) +- **Core:** Uses `pps bisect_ppx` in per-module preprocessing (works with action preprocessing) + +The `instrumentation` stanza is preferred but cannot be used with `(preprocess (action ...))`. +We use it where possible (CBOR) and fall back to `pps` where needed (core). ### Alternative Approaches Considered diff --git a/src/cbor/dune b/src/cbor/dune index 0d11d1f8..0c455443 100644 --- a/src/cbor/dune +++ b/src/cbor/dune @@ -1,5 +1,5 @@ (library (name containers_cbor) (libraries containers) - (preprocess (pps bisect_ppx)) + (instrumentation (backend bisect_ppx)) (public_name containers.cbor))