unitest

Unitest is a Gleam test runner with random ordering, tagging, and CLI filtering.

Drop-in replacement for gleeunit with additional features:

Random test ordering with reproducible seeds
Test tagging for selective execution
CLI filtering by module, test, or tag

Types

Options

</>

Configuration options for the test runner.

Fields

seed: Optional seed for deterministic test ordering. When None, a random seed is generated automatically.
ignored_tags: Tests with any of these tags will be skipped and reported as S in the output.
test_directory: Directory containing test files.

Example

unitest.run(Options(
  seed: Some(12345),
  ignored_tags: ["slow", "integration"],
  test_directory: "test",
))

pub type Options {
  Options(
    seed: option.Option(Int),
    ignored_tags: List(String),
    test_directory: String,
  )
}

Constructors

Options(
  seed: option.Option(Int),
  ignored_tags: List(String),
  test_directory: String,
)

Values

default_options

</>

pub fn default_options() -> Options

Returns default options with no seed and no ignored tags.

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 all test files in the test directory, applies CLI arguments for filtering, shuffles tests using the selected seed, executes them, and prints results.

CLI Arguments

Pass arguments after -- when running gleam test:

--seed <int>: Use specific seed for reproducible ordering
--module <name>: Run only tests in matching module
--test <module.fn>: Run a single test function
--tag <name>: Run only tests with this tag

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
}