Home

Awesome

ppx_inline_test

Syntax extension for writing in-line tests in ocaml code.

New syntactic constructs

The following constructs are now valid structure items:

let%test "name" = <boolean expr> (* true means ok, false or exn means broken *)
let%test_unit "name" = <unit expr> (* () means ok, exn means broken *)
module%test Name = <module_expr>  (* to group tests, e.g. to share setup *)
module%test [@name "name"] _ = <module_expr>  (* more flexible naming *)
let%test_module "name" = (module <module-expr>) (* legacy module syntax *)

We may write _ instead of "name" for anonymous tests. It is also possible to use [%name <string expr>] for a dynamically computed name.

When running tests, they will be executed when the control flow reaches the structure item (i.e. at toplevel for a toplevel test; when the functor is applied for a test defined in the body of a functor, etc.).

Tags

One can tag tests with the following construct:

let%test "name" [@tags "no-js"] = <expr>
let%test "name" [@tags "no-js", "other-tag"] = <expr>
let%test _ [@tags "no-js"] = <expr>
let%test _ [@tags "js-only"] = <expr>

Available tags are:

One can also tag entire test modules similarly:

module%test Name [@tags "no-js"] = struct end

The flags -drop-tag and -require-tag can be passed to the test runner to restrict which tests are run. We say the tags of a test are the union of the tags applied directly to that test using [@tags ...] and the tags of all enclosing modules. It is to this union that the predicates -drop-tag and -require-tag are applied.

If it is clear, from a test-module's tags, that none of the tests within will possibly match the tag predicates imposed by the command line flags, then additionally the top-level of that module will not be run.

Examples

prime.ml

let is_prime = <magic>

let%test _ = is_prime 5
let%test _ = is_prime 7
let%test _ = not (is_prime 1)
let%test _ = not (is_prime 8)

Tests in a functor.

module Make(C : S) = struct
     <magic>
     let%test _ = <some expression>
end

module M = Make(Int)

Grouping test and side-effecting initialisation.

Since the module defined under module%test is only initialised when we run the tests, it is ok to perform side-effects in the module-expression argument.

module%test _ = struct
  module UID = Unique_id.Int(struct end)

  let%test _ = UID.create() <> UID.create()
end

Building and running the tests with Dune

Inline tests can only be used in libraries, not executables.

To use this with dune, see dune's documentation. At the time of writing of the current document, the short version is:

(library
  (name foo)
  (inline_tests)
  (preprocess (pps ppx_inline_test)))

Building and running the tests without Dune

Code using this extension must be compiled and linked using the ppx_inline_test.runtime-lib library. The ppx_inline_test syntax extension will reject any test if it wasn't passed a -inline-test-lib libname flag.

Execution

Tests are only executed when both these conditions are met:

This libname is a way of restricting the tests run by the executable. The dependencies of your library (or executable) could also use ppx_inline_test, but you don't necessarily want to run their tests too. For instance, core is built by giving -inline-test-lib core and core_extended is built by giving -inline-test-lib core_extended. And now when an executable linked with both core and core_extended is run with a libname of core_extended, only the tests of core_extended are run.

Finally, after running tests, Ppx_inline_test_lib.exit () should be called (to exit with an error and a summary of the number of failed tests if there were errors or exit normally otherwise).

One can construct a dual-use binary that only runs the tests when prompted to (through the command line), by sticking the following piece of code in it, after the tests have run but before the binary starts doing non-test side effects. However be aware that Base.am_testing will be true even when not running tests, which may be undesirable.

match Ppx_inline_test_lib.testing with
| `Testing `Am_test_runner ->
  print_endline "Exiting test suite";
  Ppx_inline_test_lib.exit ()
| `Testing _ -> exit 0
| `Not_testing -> ()

Command line arguments

The executable that runs tests can take additional command line arguments. The most useful of these are:

These can be specified to jenga like this:

(library
  (...
   (inline_tests ((flags (-stop-on-error))))
   ...
  ))

and to dune like this:

(library
  ...
  (inline_tests (flags (-stop-on-error)))
  ...)

Parallelizing tests

If you pass arguments of the form -inline-test-lib lib:partition to ppx_inline_test, then you will be able to run tests from a given source file in parallel with tests from other source files. All the tests inside the same source file are still run sequentially.

You should pick different partition names for the different files in your library (the name of the .ml files for instance).

ppx_inline_test_lib currently requires some external system like a build system to run it multiple times in parallel, although we may make it possible to run the inline tests in parallel directly in the future.

If you do that, you can now use two new flags of the executable containing the tests:

A build system can combine these two commands by first listing partitions, and then running one command for each partition.