### Example of Custom Options Usage

Source: https://github.com/mirage/alcotest/blob/main/README.md

Demonstrates the command-line usage and output when passing a custom option to tests.

```sh-session
$ test.exe test
test.exe: required option -n is missing

$ test.exe test -n 42
Testing foo.
[OK]                all          0   int.
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/mirage/alcotest/blob/main/CONTRIBUTING.md

Clone the Alcotest repository and install its dependencies using Opam. Optionally, create a local Opam switch for the project.

```sh
git clone https://github.com/mirage/alcotest.git    # Get the repository
cd alcotest

opam switch create ./ ocaml-base-compiler.5.0.0    # OPTIONAL: install a project-local Opam switch
opam install -t --deps-only .

```

--------------------------------

### Install js_of_ocaml-compiler

Source: https://github.com/mirage/alcotest/blob/main/CONTRIBUTING.md

Install the js_of_ocaml-compiler package to enable running the test suite with Node.js.

```sh
opam install -t js_of_ocaml-compiler
```

--------------------------------

### Lwt Test Case Example

Source: https://github.com/mirage/alcotest/blob/main/README.md

Wraps Lwt test cases using `Alcotest_lwt`. Provides resource management via switches and handles async exceptions.

```ocaml
let free () = print_endline "freeing all resources"; Lwt.return ()

let test_lwt switch () = 
  Lwt_switch.add_hook (Some switch) free;
  Lwt.async (fun () -> failwith "All is broken");
  Lwt_unix.sleep 10.

let () = 
  Lwt_main.run @@ Alcotest_lwt.run "foo" [
    "all", [
      Alcotest_lwt.test_case "one" `Quick test_lwt
    ]
  ]
```

--------------------------------

### Define and Run OCaml Unit Tests with Alcotest

Source: https://github.com/mirage/alcotest/blob/main/README.md

This example demonstrates how to define a test suite using Alcotest's API, including test cases for string and list manipulations. It shows how to group tests and run them with different priority levels (`Quick`, `Slow`).

```ocaml
(* Build with `ocamlbuild -pkg alcotest simple.byte` *)

(* A module with functions to test *)
module To_test = struct
  let lowercase = String.lowercase_ascii
  let capitalize = String.capitalize_ascii
  let str_concat = String.concat ""
  let list_concat = List.append
end

(* The tests *)
let test_lowercase () =
  Alcotest.(check string) "same string" "hello!" (To_test.lowercase "hELLO!")

let test_capitalize () =
  Alcotest.(check string) "same string" "World." (To_test.capitalize "world.")

let test_str_concat () =
  Alcotest.(check string) "same string" "foobar" (To_test.str_concat ["foo"; "bar"])

let test_list_concat () =
  Alcotest.(check (list int)) "same lists" [1; 2; 3] (To_test.list_concat [1] [2; 3])

(* Run it *)
let () =
  let open Alcotest
  in
  run "Utils" [
      "string-case", [
          test_case "Lower case"     `Quick test_lowercase;
          test_case "Capitalization" `Quick test_capitalize;
        ];
      "string-concat", [ test_case "String mashing" `Quick test_str_concat  ];
      "list-concat",   [ test_case "List mashing"   `Slow  test_list_concat ];
    ]
```

--------------------------------

### Install Alcotest with Opam and Dune

Source: https://github.com/mirage/alcotest/blob/main/README.md

Instructions for adding Alcotest as a development dependency in your project using Opam and Dune. This ensures Alcotest is available when building and running tests.

```sh
$ opam install --deps-only --with-test .
```

--------------------------------

### Alcotest Async/Lwt Monadic Test Case Example

Source: https://github.com/mirage/alcotest/blob/main/CHANGES.md

Demonstrates the usage of the new `Alcotest.async.test_case` and `Alcotest.lwt.test_case` API, which now return monadic values. These must be run with the corresponding `run` functions.

```ocaml
let () = Alcotest_lwt.run "my test suite" [ ("test 1", `Quick, `Alcotest_async.test_case "test 1" `Quick (fun () -> Lwt.return ())) ]
```

--------------------------------

### Alcotest Float Check Semantics

Source: https://github.com/mirage/alcotest/blob/main/CHANGES.md

Demonstrates the updated semantics for checking floating-point numbers, which now include proper handling of NaN and infinities. This example showcases the new behavior.

```ocaml
let () = Alcotest.run "floats" [ ("check floats", `Quick, test_case "" `Quick (fun () ->
    let open Alcotest in
    check (float "-") "equal" 1.0 1.0;
    check (float "-") "nan" nan nan;
    check (float "-") "inf" infinity infinity;
    check (float "-") "-inf" neg_infinity neg_infinity))
]
```

--------------------------------

### Sanitized Output Placeholders in Expect Tests

Source: https://github.com/mirage/alcotest/blob/main/CONTRIBUTING.md

Examples of sanitized output in expect tests, showing placeholders for non-portable elements like test duration and UUIDs.

```text
The full test results are available in `<build-context>/_build/_tests/<uuid>`.
Test Successful in <test-duration>s. 4 tests run.
```

--------------------------------

### Run Quick and Slow Tests

Source: https://github.com/mirage/alcotest/blob/main/README.md

Use `./test.exe -q` to run only quick tests. Run `./test.exe` to execute both quick and slow tests.

```sh-session
$ ./test.exe -q # run only the quick tests
$ ./test.exe    # run quick and slow tests
```

--------------------------------

### Project Structure Overview

Source: https://github.com/mirage/alcotest/blob/main/CONTRIBUTING.md

An overview of the Alcotest project's directory structure, highlighting key directories and files.

```sh
├── src/
│   ├── alcotest-engine/
│   │   ├── core.ml           # The main test runner, parameterised over...
│   │   ├── monad.ml          # ... a concurrency monad
│   │   ├── platform.ml       # ... a platform implementation / OS bindings
│   │   │
│   │   ├── cli.ml            # Extends `core.ml` with a command-line API
│   │   │
│   │   ├── pp.ml             # Pretty-printers for Alcotest output
│   │   ├── test.ml           # Combinators for test assertions (with `Alcotest.check`)
│   │   └── utils.ml          # Standard-library extension
│   │
│   │                         # Specific backends:
│   ├── alcotest/             # - Unix-specific API (compatible with js_of_ocaml)
│   ├── alcotest-async/       # - Extends `alcotest/` for test-suites using Async concurrency
│   ├── alcotest-lwt/         # - Extends `alcotest/` for test-suites using Lwt concurrency
│   └── alcotest-mirage/      # - MirageOS-specific API
│
├── test/                     # Project tests (see '§ Expect tests' below)
│
├── dune-project              # Project metadata (opam files are generated from
├── alcotest-async.opam       # data in the `dune-project` file by running
├── alcotest-lwt.opam         # `dune build @install`).
├── alcotest-mirage.opam
├── alcotest.opam
│
├── alcotest-help.txt         # Manpage output (generated by `dune test --auto-promote`)
├── dune
│
├── CHANGES.md                # All user-facing changes get an entry here
└── README.md

```

--------------------------------

### Adding a New Expect Test

Source: https://github.com/mirage/alcotest/blob/main/CONTRIBUTING.md

Steps to add a new expect test by creating a new file pair and using `dune test --auto-promote` to generate necessary Dune rules.

```sh
dune test --auto-promote
```

--------------------------------

### Standard Dune Commands

Source: https://github.com/mirage/alcotest/blob/main/CONTRIBUTING.md

Common Dune commands for building, testing, and cleaning the Alcotest project. Use `@runtest-js` to run tests with js_of_ocaml.

```sh
dune build              # Build all libraries, executables and tests
dune test               # Run the test-suite
dune build @runtest-js  # Run the test-suite on nodejs (using js_of_ocaml)
dune clean              # Delete all artefacts
```

--------------------------------

### Run Dune Tests

Source: https://github.com/mirage/alcotest/blob/main/README.md

Command to execute the tests defined in your project using the Dune build system. This command will discover and run tests, including those using Alcotest.

```sh
$ dune runtest
```

--------------------------------

### Expect Test Structure

Source: https://github.com/mirage/alcotest/blob/main/CONTRIBUTING.md

Structure of an expect test case, including the test file, expected output, and optional command-line options.

```sh
test/e2e/alcotest/passing/
├── basic.ml          # The test case
├── basic.expected    # The expected output of the test case
└── basic.opts        # OPTIONAL: command-line options to pass to the test
```

--------------------------------

### Pass Custom Options to Tests

Source: https://github.com/mirage/alcotest/blob/main/README.md

Define a custom command-line term for an extra parameter to be passed to test functions. Only optional arguments are supported.

```ocaml
let test_nice i = Alcotest.(check int) "Is it a nice integer?" i 42

let int = 
  let doc = "What is your preferred number?" in
  Cmdliner.Arg.(required & opt (some int) None & info ["n"] ~doc ~docv:"NUM")

let () = 
  Alcotest.run_with_args "foo" int [
    "all", ["nice", `Quick, test_nice]
  ]
```

--------------------------------

### Updating Expect Test Snapshots

Source: https://github.com/mirage/alcotest/blob/main/CONTRIBUTING.md

Workflow for updating expect test snapshots after changes to Alcotest output. This involves running tests, verifying diffs, and promoting changes.

```sh
1. run `dune test` to get a list of diffs to the tests,
1. check that the diffs are as expected,
1. run `dune promote` to update the snapshots in the repository.
```

--------------------------------

### Filter Alcotest Tests by Name and Number

Source: https://github.com/mirage/alcotest/blob/main/README.md

Demonstrates how to selectively run Alcotest tests using command-line arguments. You can filter tests by a regular expression matching their names and optionally specify test numbers or ranges.

```sh
$ ./simple.native test '.*concat*'
```

```sh
$ ./simple.native test 'string-case' '1..3'
```

--------------------------------

### Lwt Test Failure Output

Source: https://github.com/mirage/alcotest/blob/main/README.md

Shows the output when an Lwt test case fails due to an async exception.

```sh-session
$ test.exe
Testing foo.
[ERROR]             all          0   one.
-- all.000 [one.] Failed --
in _build/_tests/all.000.output:
freeing all resources
[failure] All is broken
```

--------------------------------

### Configure ALCOTEST_COLOR in Dune

Source: https://github.com/mirage/alcotest/blob/main/CHANGES.md

Set the ALCOTEST_COLOR environment variable within a Dune file to control terminal output colorization. This overrides the default behavior of `--color=always` when running inside Dune.

```dune
(env
 (_
  (env-vars
   (ALCOTEST_COLOR auto))))
```