package ppx_inline_test

  1. Overview
  2. Docs
Syntax extension for writing in-line tests in ocaml code

Install

Dune Dependency

Authors

Maintainers

Sources

ppx_inline_test-v0.13.1.tbz
sha256=e75c9df9b33e20655fd2f728df5e332794bdd9a2f5a62fc08e44fb6ca1beda6c
sha512=402e4d6113368da37464d64ae145f5a58af751275bb92d4a4bdd16f41fbada9311ca9f8da7aeb86537bdf25710fcb1df3cd983717935f1cd5ca663f27aaa3b6b

Description

Part of the Jane Street's PPX rewriters collection.

Published: 30 Mar 2020

README

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 *)
let%test_module "name" = (module <module-expr>)  (* to group tests (to share
                                                    some setup for instance) *)

We may write _ instead of "name" for anonymous tests.

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:

  • no-js for tests that should not run when compiling Ocaml to Javascript

  • js-only for tests that should only run in Javascript

  • 32-bits-only for tests that should only run in 32 bits architectures

  • 64-bits-only for tests that should only run in 64 bits architectures

  • x-library-inlining-sensitive for tests that might only pass when compiling with cross library inlining switched on

One can also tag entire test modules similarly:

let%test_module "name" [@tags "no-js"] = (module 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 passed as an argument to let%test_module is only initialised when we run the tests, it is ok to perform side-effects in the module-expression argument.

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

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

Building and running the tests at jane street

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

The standard build rules create an executable script inline_tests_runner which runs all tests in the directory. This script takes optional arguments (see below) to restrict which tests are run.

The full set of tests are run when building the jenga runtest alias.

jenga .runtest

Building and running the tests outside of jane street

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.

To integrate this in your build system, you should look at the instruction provided for the ppx_driver ocamlbuild plugin. There are a few working example using oasis in the Jane Street tests.

Execution

Tests are executed when the executable containing the tests is called with command line arguments:

your.exe inline-test-runner libname [options]

otherwise they are ignored.

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.Runtime.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).

Command line arguments

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

  • -verbose

    to see the tests as they run

  • -only-test location

    where location is either a filename -only-test main.ml, a filename with a line number -only-test main.ml:32, or with the syntax that the compiler uses: File "main.ml", or File "main.ml", line 32 or File "main.ml", line 32, characters 2-6 (characters are ignored). The position that matters is the position of the let%test or let%test_unit.

    The positions shown by -verbose are valid inputs for -only-test.

    If no -only-test flag is given, all the tests are run. Otherwise all the tests matching any of the locations are run.

  • -drop-tag tag

    drop all the tests tagged with tag.

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:

  • -list-partitions

    lists all the partitions that contain at least one test, one per line.

  • -partition P

    only run the tests of the library that are encountered at toplevel of the source file that was preprocessed with the given partition P (the tests need not be syntactically in the file, they could be the result of applying a functor)

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

Dependencies (4)

  1. ppxlib >= "0.9.0" & < "0.14.0"
  2. dune >= "1.10"
  3. base >= "v0.13" & < "v0.14"
  4. ocaml >= "4.04.2"

Dev Dependencies

None

Used by (96)

  1. alba >= "0.4.1" & < "0.4.3"
  2. autofonce
  3. autofonce_config
  4. autofonce_core
  5. autofonce_lib
  6. autofonce_m4
  7. autofonce_misc
  8. autofonce_patch
  9. autofonce_share
  10. aws-s3 >= "4.0.0" & != "4.5.0"
  11. bio_io >= "0.2.1" & < "0.5.1"
  12. bitpack_serializer
  13. bitwuzla >= "1.0.0"
  14. bitwuzla-c
  15. bitwuzla-cxx
  16. caisar >= "0.2.1"
  17. caisar-ir
  18. coq-lsp >= "0.1.9+8.17" & < "0.2.2+8.17"
  19. core_kernel >= "v0.13.0" & < "v0.14.0"
  20. drom
  21. drom_lib
  22. drom_toml
  23. electrod >= "0.1.6" & < "0.5"
  24. embedded_ocaml_templates >= "0.6"
  25. encoding < "0.0.4"
  26. ez_cmdliner >= "0.2.0"
  27. ez_config >= "0.2.0"
  28. ez_file >= "0.2.0"
  29. ez_hash < "0.5.3"
  30. ez_opam_file
  31. ez_search
  32. ez_subst
  33. fiber-lwt
  34. fmlib < "0.5.0"
  35. fmlib_browser
  36. fmlib_js < "0.5.0"
  37. fmlib_parse
  38. fmlib_pretty
  39. fmlib_std
  40. GT >= "0.5.0"
  41. guardian < "0.0.5"
  42. hdf5 >= "0.1.5"
  43. header-check
  44. idds
  45. knights_tour
  46. lablqml >= "0.7"
  47. learn-ocaml >= "0.16.0"
  48. learn-ocaml-client >= "0.16.0"
  49. little_logger < "0.3.0"
  50. module-graph
  51. mula
  52. mysql8
  53. netkat
  54. nuscr < "2.0.0"
  55. OCanren >= "0.3.0~alpha1"
  56. OCanren-ppx >= "0.3.0~alpha1"
  57. ocaml-protoc-plugin
  58. ocp-search
  59. ocplib_stuff >= "0.3.0"
  60. opam-bin >= "0.9.5"
  61. opam-check-npm-deps
  62. opam_bin_lib >= "0.9.5"
  63. pp-binary-ints
  64. ppx_bench = "v0.13.0"
  65. ppx_deriving_cad
  66. ppx_deriving_decoders
  67. ppx_deriving_scad
  68. ppx_expect >= "v0.13.0" & < "v0.14.0"
  69. ppx_jane = "v0.13.0"
  70. ppx_partial
  71. ppx_protocol_conv_json >= "5.0.0"
  72. ppx_ts
  73. psmt2-frontend >= "0.3.0"
  74. pyml_bindgen
  75. res_tailwindcss
  76. sel
  77. simple63
  78. solidity-alcotest
  79. solidity-common
  80. solidity-parser
  81. solidity-test
  82. solidity-typechecker
  83. splittable_random = "v0.13.0"
  84. sqlite3 >= "5.0.1"
  85. tezos-client-009-PsFLoren >= "10.2" & < "14.0"
  86. tezos-client-010-PtGRANAD < "14.0"
  87. tezos-client-011-PtHangz2 < "14.0"
  88. tezos-client-012-Psithaca < "14.0"
  89. tezos-client-013-PtJakart < "14.0"
  90. tezos-client-alpha >= "10.2" & < "14.0"
  91. tezos-micheline >= "9.0" & < "14.0"
  92. tezos-stdlib >= "9.0" & < "14.0"
  93. tezos-test-helpers = "13.0"
  94. toplevel_expect_test = "v0.13.0"
  95. vscoq-language-server
  96. zanuda

Conflicts

None

OCaml

Innovation. Community. Security.