unitest

Unitest is a drop-in replacement for gleeunit that adds random test ordering (with reproducible seeds), tagging, and CLI filtering.

Types

ExecutionMode

</>

Controls how tests are executed.

pub type ExecutionMode {
  RunSequential
  RunAsync
  RunParallel(workers: Int)
  RunParallelAuto
}

Constructors

```
RunSequential
```
Runs one test at a time.
```
RunAsync
```
Runs tests concurrently within each module.
```
RunParallel(workers: Int)
```
Runs the given number of module groups simultaneously, each with per-module concurrency up to the CPU core count.
```
RunParallelAuto
```
Auto-detects the number of module-group workers. Falls back to sequential when the test count is below the parallel threshold.

Options

</>

Configuration for the test runner.

Tests with any ignored_tags are skipped and reported as S. When check_results is True, tests returning Error(reason) are treated as failures (default False).

Example

unitest.run(Options(
  ..unitest.default_options(),
  ignored_tags: ["slow"],
  execution_mode: RunParallelAuto,
))

pub type Options {
  Options(
    seed: option.Option(Int),
    ignored_tags: List(String),
    test_directory: String,
    sort_order: @internal SortOrder,
    sort_reversed: Bool,
    check_results: Bool,
    execution_mode: ExecutionMode,
  )
}

Constructors

Options(
  seed: option.Option(Int),
  ignored_tags: List(String),
  test_directory: String,
  sort_order: @internal SortOrder,
  sort_reversed: Bool,
  check_results: Bool,
  execution_mode: ExecutionMode,
)

Values

default_options

</>

pub fn default_options() -> Options

Returns default options with no seed and no ignored tags.

guard

</>

pub fn guard(condition: Bool, next: fn() -> a) -> a

Conditionally skip a test at runtime based on a boolean condition.

Use with Gleam’s use syntax. If the condition is False, the test is skipped and reported as S in the output.

Example

pub fn otp28_feature_test() {
  use <- unitest.guard(otp_version() >= 28)
  // test runs only if OTP >= 28
}

Multiple guards can be chained:

pub fn linux_otp28_test() {
  use <- unitest.guard(is_linux())
  use <- unitest.guard(otp_version() >= 28)
  // runs only if both conditions are true
}

main

</>

pub fn main() -> Nil

Entry point using default options.

This is a drop-in replacement for gleeunit.main(). Call this from your test file’s main function if you don’t need custom options.

Example

pub fn main() {
  unitest.main()
}

run

</>

pub fn run(options: Options) -> Nil

Run tests with the given options.

Discovers test files, applies CLI filters, shuffles with the selected seed, executes, and prints results.

CLI Arguments

Pass arguments after -- when running gleam test:

<file> or <file>:<line>: Run tests in a file, optionally at a line
--test <module.fn>: Run a single test function
--tag <name>: Run only tests with this tag
--seed <int>: Reproducible ordering
--reporter <dot|table>: Output format (default: dot)
--sort <native|time|name>: Sort order for table reporter
--sort-rev: Reverse sort order
--workers <int>: Parallel module-group workers
--no-color: Disable colored output

Example

pub fn main() {
  unitest.run(Options(..unitest.default_options(), ignored_tags: ["slow"]))
}

tag

</>

pub fn tag(tag: String, next: fn() -> a) -> a

Mark a test with a single tag for filtering or skipping.

Use with Gleam’s use syntax at the start of a test function. Tags must be string literals for static analysis.

Example

pub fn database_integration_test() {
  use <- unitest.tag("integration")
  // test code here
}

Then run: gleam test -- --tag integration

Example

pub fn slow_integration_test() {
  use <- unitest.tags(["slow", "integration"])
  // test code here
}