Bisect_ppx is a code coverage tool for OCaml. It helps you test thoroughly by showing which parts of your code are not tested. You can also use it for tracing: run one test, and see what is visited.
Most of these commands go in a
Makefile or other script, so that you only have
to run that script, then refresh your browser.
opam install bisect_ppx
You can also install without OPAM.
ocamlfind c -package bisect_ppx -c my_code.ml ocamlfind c -c my_tests.ml ocamlfind c -linkpkg -package bisect_ppx my_code.cmo my_tests.cmo
Run your test binary. In addition to testing your code, it will produce one or more files with names like
./a.out # Produces bisect0001.out
Generate the coverage report.
bisect-ppx-report -I build/ -html coverage/ bisect*.out`
You can submit a coverage report to Coveralls.io using ocveralls. Note that Bisect_ppx reports are more precise than Coveralls, which only considers whole lines as visited or not.
See also the advanced usage.
Bisect_ppx in practice
A small sample of projects using Bisect_ppx:
Relation to Bisect
Bisect_ppx is an advanced fork of the excellent Bisect by Xavier Clerc. As of the time of this writing, it appears that the original Bisect is no longer maintained.
Considerable work has been done on Bisect_ppx, so that it is now a distinct project. In terms of the interface, Bisect_ppx is still largely compatible with Bisect's ppx mode, but see here for a list of differences.
If you use Camlp4, you will want to use the original Bisect.
Bisect_ppx is distributed under the terms of the GPL license, version 3. Note, however, that Bisect_ppx does not "contaminate" your project with the terms of the GPL, because it is a development tool used only during testing. You would not want to link Bisect_ppx into your release files anyway, for performance reasons.
Bug reports and pull requests are warmly welcome. Bisect_ppx is developed on GitHub, so please open an issue.
To get the latest development version of Bisect_ppx using OPAM, run
opam source --dev-repo --pin bisect_ppx
You will now have a
bisect_ppx subdirectory to work in.