package bisect_ppx

  1. Overview
  2. Docs
Code coverage for OCaml

Install

Dune Dependency

Authors

Maintainers

Sources

1.3.1.tar.gz
sha256=1e646eafe6eb7a3ee36428dee8b772ac3e926d505dfd0d8178412e2c66b489dc
md5=9b76f6f192307ec7098ded5e36670df2

Description

Bisect_ppx helps you test thoroughly. It is a small preprocessor that inserts instrumentation at places in your code, such as if-then-else and match expressions. After you run tests, Bisect_ppx gives a nice HTML report showing which places were visited and which were missed.

Usage is simple - add package bisect_ppx when building tests, then run the report tool on the generated visitation files.

This is an advanced fork of the original Bisect coverage tool. It has many improvements and updates.

  • Much more thorough code instrumentation, so you can find more gaps in your testing.
  • Fast operation by default.
  • More legible and appealing HTML reports.
  • Various bugfixes.
  • No camlp4 dependency.

Published: 07 Oct 2017

README

Bisect_ppx  

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.


For a live demonstration, see the coverage report Bisect_ppx generates for itself. You may also want to see projects that use Bisect_ppx.


Instructions

Most of these commands go in a Makefile or other script, so that you only have to run that script, then refresh your browser.

  1. Install Bisect_ppx.

     opam install bisect_ppx
    

    You can also install without OPAM.

  2. When compiling for testing, include Bisect_ppx. Instructions are also available for Ocamlbuild, OASIS and Jbuilder.

     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
    
  3. Run your test binary. In addition to testing your code, it will produce one or more files with names like bisect0001.out.

     ./a.out             # Produces bisect0001.out
    
  4. Generate the coverage report.

     bisect-ppx-report -I _build/ -html coverage/ bisect*.out`
    
  5. Open coverage/index.html!

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.


License

Bisect_ppx is available under the Mozilla Public License 2.0 (MPL). To summarize, you can incorporate Bisect_ppx into proprietary projects. If you make modifications to Bisect_ppx, you have to open-source them. The rest of your project remains proprietary.

Essentially, this is like the BSD or MIT licenses, except that if you include a customized Bisect_ppx in a release (as opposed to private use), you have to make the altered source visible. This can be done by contributing the changes back, keeping Bisect_ppx in a visible fork, or if your bigger project itself also happens to be open source.

Besides proprietary licenses, MPL is compatible with BSD/MIT/Apache- and (L)GPL-licensed projects. See the MPL 2.0 FAQ.

The Ocamlbuild plugin is dedicated to the public domain.


Contributing

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.

OCaml

Innovation. Community. Security.