testing

OCaml Testing

Test Directory Structure

Use test/ directory with:

• test.ml - Main runner controlling initialization order
• test_x.ml - One file per module x.ml being tested, exports suite

lib/
├── foo.ml
└── bar.ml
test/
├── dune
├── test.ml          # Main runner
├── test_foo.ml      # suite : (string * unit Alcotest.test_case list) list
└── test_bar.ml

For single-module libraries, a single test_foo.ml as runner is acceptable.

Dune Configuration

(test
 (name test)
 (libraries mylib alcotest logs logs.fmt fmt.tty))

Main Runner Pattern (test.ml)

The main test.ml controls initialization order for side effects:

(* 1. Initialize RNG before any test module is loaded *)
let () = Crypto_rng_unix.use_default ()

(* 2. Set up logging *)
let () = Fmt_tty.setup_std_outputs ()
let () = Logs.set_reporter (Logs_fmt.reporter ())
let () = Logs.set_level (Some Logs.Debug)

(* 3. Run all test suites *)
let () = Alcotest.run "mylib" Test_foo.suite

For multiple modules:

let () = Crypto_rng_unix.use_default ()
let () = Alcotest.run "mylib" (Test_foo.suite @ Test_bar.suite)

Module Test File Pattern (test_x.ml)

Each module exports a suite value. Do not initialize RNG or run Alcotest here.

(** Tests for Foo module. *)

let test_basic () =
  let result = Foo.process "input" in
  Alcotest.(check string) "expected output" "output" result

let test_empty () =
  let result = Foo.process "" in
  Alcotest.(check string) "empty input" "" result

let suite =
  [
    ( "process",
      [
        Alcotest.test_case "basic" `Quick test_basic;
        Alcotest.test_case "empty" `Quick test_empty;
      ] );
  ]

Lazy State for Module-Level Values

If a test module needs RNG at load time, use lazy evaluation:

let key = lazy (Crypto_rng.generate 32)
let key () = Lazy.force key

let test_encrypt () =
  let ciphertext = Foo.encrypt ~key:(key ()) plaintext in
  ...

This defers RNG use until tests actually run, after test.ml initializes the RNG.