dream_test

<div align="center">
  <img src="https://raw.githubusercontent.com/TrustBound/dream/main/ricky_and_lucy.png" alt="Dream Logo" width="180">
  <h1>Dream Test</h1>
  <p><strong>A testing framework for Gleam that gets out of your way.</strong></p>
  <a href="https://hex.pm/packages/dream_test">
    <img src="https://img.shields.io/hexpm/v/dream_test?color=8e4bff&label=hex" alt="Hex.pm">
  </a>
  <a href="https://hexdocs.pm/dream_test/">
    <img src="https://img.shields.io/badge/docs-hexdocs-8e4bff" alt="Documentation">
  </a>
  <a href="https://github.com/TrustBound/dream_test/blob/main/LICENSE">
    <img src="https://img.shields.io/badge/license-MIT-blue" alt="License">
  </a>
</div>
<br>
```gleam
import dream_test/unit.{describe, it}
import dream_test/assertions/should.{be_error, be_ok, equal, or_fail_with, should}
pub fn tests() {
  describe("Calculator", [
    it("adds two numbers", fn() {
      add(2, 3)
      |> should()
      |> equal(5)
      |> or_fail_with("2 + 3 should equal 5")
    }),
    it("handles division", fn() {
      divide(10, 2)
      |> should()
      |> be_ok()
      |> equal(5)
      |> or_fail_with("10 / 2 should equal 5")
    }),
    it("returns error for division by zero", fn() {
      divide(1, 0)
      |> should()
      |> be_error()
      |> or_fail_with("Division by zero should error")
    }),
  ])
}
```
```
Calculator
  ✓ adds two numbers
  ✓ handles division
  ✓ returns error for division by zero
3 tests, 0 failures
```
<sub>🧪 [Tested source](examples/snippets/test/hero.gleam)</sub>
---
## Installation
```toml
# gleam.toml
[dev-dependencies]
dream_test = "~> 1.0"
```
---
## Why Dream Test?
| Feature                 | What you get                                                                   |
| ----------------------- | ------------------------------------------------------------------------------ |
| **Parallel by default** | Tests run concurrently across all cores—100 tests finish ~4x faster on 4 cores |
| **Crash-proof**         | Each test runs in an isolated BEAM process; one crash doesn't kill the suite   |
| **Timeout-protected**   | Hanging tests get killed automatically; no more stuck CI pipelines             |
| **Lifecycle hooks**     | `before_all`, `before_each`, `after_each`, `after_all` for setup/teardown      |
| **Gleam-native**        | Pipe-first assertions that feel natural; no macros, no reflection, no magic    |
| **Familiar syntax**     | If you've used Jest, RSpec, or Mocha, you already know the basics              |
| **Type-safe**           | Your tests are just Gleam code; the compiler catches mistakes early            |
| **Self-hosting**        | Dream Test tests itself; we eat our own cooking                                |
---
## Quick Start
### 1. Write tests with `describe` and `it`
```gleam
// test/my_app_test.gleam
import dream_test/unit.{describe, it, to_test_cases}
import dream_test/runner.{run_all}
import dream_test/reporter/bdd.{report}
import dream_test/assertions/should.{should, equal, or_fail_with}
import gleam/io
import gleam/string
pub fn tests() {
  describe("String utilities", [
    it("trims whitespace", fn() {
      "  hello  "
      |> string.trim()
      |> should()
      |> equal("hello")
      |> or_fail_with("Should remove surrounding whitespace")
    }),
    it("finds substrings", fn() {
      "hello world"
      |> string.contains("world")
      |> should()
      |> equal(True)
      |> or_fail_with("Should find 'world' in string")
    }),
  ])
}
pub fn main() {
  to_test_cases("my_app_test", tests())
  |> run_all()
  |> report(io.print)
}
```
<sub>🧪 [Tested source](examples/snippets/test/quick_start.gleam)</sub>
### 2. Run with gleam test
```sh
gleam test
```
### 3. See readable output
```
String utilities
  ✓ trims whitespace
  ✓ finds substrings
2 tests, 0 failures
```
---
## The Assertion Pattern
Every assertion follows the same pattern:
```gleam
value |> should() |> matcher() |> or_fail_with("message")
```
### Chaining matchers
Matchers can be chained. Each one passes its unwrapped value to the next:
```gleam
// Unwrap Some, then check the value
Some(42)
|> should()
|> be_some()
|> equal(42)
|> or_fail_with("Should contain 42")
// Unwrap Ok, then check the value
Ok("success")
|> should()
|> be_ok()
|> equal("success")
|> or_fail_with("Should be Ok with 'success'")
```
<sub>🧪 [Tested source](examples/snippets/test/chaining.gleam)</sub>
### Available matchers
| Category        | Matchers                                                                                    |
| --------------- | ------------------------------------------------------------------------------------------- |
| **Equality**    | `equal`, `not_equal`                                                                        |
| **Boolean**     | `be_true`, `be_false`                                                                       |
| **Option**      | `be_some`, `be_none`                                                                        |
| **Result**      | `be_ok`, `be_error`                                                                         |
| **Collections** | `contain`, `not_contain`, `have_length`, `be_empty`                                         |
| **Comparison**  | `be_greater_than`, `be_less_than`, `be_at_least`, `be_at_most`, `be_between`, `be_in_range` |
| **String**      | `start_with`, `end_with`, `contain_string`                                                  |
### Explicit failures
When you need to fail unconditionally:
```gleam
import dream_test/assertions/should.{fail_with}
case result {
  Ok(_) -> fail_with("Should have returned an error")
  Error(_) -> handle_expected_error()
}
```
<sub>🧪 [Tested source](examples/snippets/test/explicit_failures.gleam)</sub>
### Skipping tests
Use `skip` instead of `it` to temporarily disable a test:
```gleam
import dream_test/unit.{describe, it, skip}
describe("Feature", [
  it("works correctly", fn() { ... }),
  skip("not implemented yet", fn() { ... }),  // Skipped
  it("handles edge cases", fn() { ... }),
])
```
```
Feature
  ✓ works correctly
  - not implemented yet
  ✓ handles edge cases
Summary: 3 run, 0 failed, 2 passed, 1 skipped
```
The test body is preserved but not executed—just change `skip` back to `it` when ready.
<sub>🧪 [Tested source](examples/snippets/test/skipping_tests.gleam)</sub>
---
## Lifecycle Hooks
Setup and teardown logic for your tests. Dream_test supports four lifecycle hooks
that let you run code before and after tests.
```gleam
import dream_test/unit.{describe, it, before_each, after_each, before_all, after_all}
import dream_test/types.{AssertionOk}
describe("Database tests", [
  before_all(fn() {
    start_database()
    AssertionOk
  }),
  before_each(fn() {
    begin_transaction()
    AssertionOk
  }),
  it("creates a user", fn() { ... }),
  it("deletes a user", fn() { ... }),
  after_each(fn() {
    rollback_transaction()
    AssertionOk
  }),
  after_all(fn() {
    stop_database()
    AssertionOk
  }),
])
```
<sub>🧪 [Tested source](examples/snippets/test/lifecycle_hooks.gleam)</sub>
### Hook Types
| Hook          | Runs                              | Use case                          |
| ------------- | --------------------------------- | --------------------------------- |
| `before_all`  | Once before all tests in group    | Start services, create temp files |
| `before_each` | Before each test                  | Reset state, begin transaction    |
| `after_each`  | After each test (even on failure) | Rollback, cleanup temp data       |
| `after_all`   | Once after all tests in group     | Stop services, remove temp files  |
### Two Execution Modes
Choose the mode based on which hooks you need:
| Mode  | Function                      | Hooks supported             |
| ----- | ----------------------------- | --------------------------- |
| Flat  | `to_test_cases` → `run_all`   | `before_each`, `after_each` |
| Suite | `to_test_suite` → `run_suite` | All four hooks              |
**Flat mode** — simpler, faster; use when you only need per-test setup:
```gleam
import dream_test/unit.{describe, it, before_each, to_test_cases}
import dream_test/runner.{run_all}
to_test_cases("my_test", tests())
|> run_all()
|> report(io.print)
```
**Suite mode** — preserves group structure; use when you need once-per-group setup:
```gleam
import dream_test/unit.{describe, it, before_all, after_all, to_test_suite}
import dream_test/runner.{run_suite}
to_test_suite("my_test", tests())
|> run_suite()
|> report(io.print)
```
<sub>🧪 [Tested source](examples/snippets/test/execution_modes.gleam)</sub>
### Hook Inheritance
Nested `describe` blocks inherit parent hooks. Hooks run outer-to-inner for
setup, inner-to-outer for teardown:
```gleam
describe("Outer", [
  before_each(fn() {
    io.println("1. outer setup")
    AssertionOk
  }),
  after_each(fn() {
    io.println("4. outer teardown")
    AssertionOk
  }),
  describe("Inner", [
    before_each(fn() {
      io.println("2. inner setup")
      AssertionOk
    }),
    after_each(fn() {
      io.println("3. inner teardown")
      AssertionOk
    }),
    it("test", fn() {
      io.println("(test)")
      AssertionOk
    }),
  ]),
])
// Output: 1. outer setup → 2. inner setup → (test) → 3. inner teardown → 4. outer teardown
```
<sub>🧪 [Tested source](examples/snippets/test/hook_inheritance.gleam)</sub>
### Hook Failure Behavior
If a hook fails, Dream Test handles it gracefully:
| Failure in    | Result                                            |
| ------------- | ------------------------------------------------- |
| `before_all`  | All tests in group marked `SetupFailed`, skipped  |
| `before_each` | That test marked `SetupFailed`, skipped           |
| `after_each`  | Test result preserved; hook failure recorded      |
| `after_all`   | Hook failure recorded; all test results preserved |
```gleam
describe("Handles failures", [
  before_all(fn() {
    case connect_to_database() {
      Ok(_) -> AssertionOk
      Error(e) -> fail_with("Database connection failed: " <> e)
    }
  }),
  // If before_all fails, these tests are marked SetupFailed (not run)
  it("test1", fn() { AssertionOk }),
  it("test2", fn() { AssertionOk }),
])
```
<sub>🧪 [Tested source](examples/snippets/test/hook_failure.gleam)</sub>
---
## BEAM-Powered Test Isolation
Every test runs in its own BEAM process:
| Feature                | What it means                                                |
| ---------------------- | ------------------------------------------------------------ |
| **Crash isolation**    | A `panic` in one test doesn't affect others                  |
| **Timeout handling**   | Slow tests get killed; suite keeps running                   |
| **Parallel execution** | Tests run concurrently (configurable)                        |
| **Automatic cleanup**  | Resources linked to the test process are freed automatically |
```gleam
// This test crashes, but others keep running
it("handles edge case", fn() {
  panic as "oops"  // Other tests still execute and report
})
// This test hangs, but gets killed after timeout
it("fetches data", fn() {
  infinite_loop()  // Killed after 5 seconds (default)
})
```
### Configuring execution
```gleam
import dream_test/runner.{run_all_with_config, RunnerConfig}
let config = RunnerConfig(
  max_concurrency: 8,
  default_timeout_ms: 10_000,
)
let test_cases = to_test_cases("my_test", tests())
run_all_with_config(config, test_cases)
|> report(io.print)
```
<sub>🧪 [Tested source](examples/snippets/test/runner_config.gleam)</sub>
---
## How It Works
Dream_test uses an explicit pipeline—no hidden globals, no magic test discovery.
### Flat Mode (most common)
```
describe/it  →  to_test_cases  →  run_all  →  report
   (DSL)         (flatten)       (execute)   (format)
```
1. **Define** tests with `describe`/`it` — builds a test tree
2. **Convert** with `to_test_cases` — flattens to runnable cases
3. **Run** with `run_all` — executes in parallel with isolation
4. **Report** with your choice of formatter — outputs results
### Suite Mode (for `before_all`/`after_all`)
```
describe/it  →  to_test_suite  →  run_suite  →  report
   (DSL)         (preserve)       (execute)    (format)
```
Suite mode preserves the group hierarchy so hooks can run at group boundaries.
### Under the Hood
Each test runs in its own BEAM process:
```mermaid
flowchart TB
    runner[Test Runner]
    runner --> t1[Test 1]
    runner --> t2[Test 2]
    runner --> t3[Test 3]
    runner --> t4[Test 4]
    t1 --> collect[Collect Results]
    t2 --> collect
    t3 --> collect
    t4 --> collect
    collect --> report[Report]
```
Benefits:
- A crashing test doesn't affect others
- Timeouts are enforced via process killing
- Resources linked to test processes are cleaned up automatically
---
## Documentation
| Document                                      | Audience                    |
| --------------------------------------------- | --------------------------- |
| **[Hexdocs](https://hexdocs.pm/dream_test/)** | API reference with examples |
| **[CONTRIBUTING.md](CONTRIBUTING.md)**        | How to contribute           |
| **[STANDARDS.md](STANDARDS.md)**              | Coding conventions          |
---
## Status
**Stable** — v1.0 release. API is stable and ready for production use.
| Feature                           | Status    |
| --------------------------------- | --------- |
| Core DSL (`describe`/`it`/`skip`) | ✅ Stable |
| Lifecycle hooks                   | ✅ Stable |
| Assertions (`should.*`)           | ✅ Stable |
| BDD Reporter                      | ✅ Stable |
| Parallel execution                | ✅ Stable |
| Process isolation                 | ✅ Stable |
| Crash handling                    | ✅ Stable |
| Timeout handling                  | ✅ Stable |
| Polling helpers                   | ✅ Stable |
---
## Contributing
```sh
git clone https://github.com/TrustBound/dream_test
cd dream_test
make all  # build, test, format
```
See [CONTRIBUTING.md](CONTRIBUTING.md) for development workflow and guidelines.
---
## License
MIT — see [LICENSE.md](LICENSE.md)
---
<div align="center">
  <sub>Part of the <a href="https://github.com/TrustBound/dream">Dream</a> ecosystem for Gleam</sub>
  <br>
  <sub>Built in Gleam, on the BEAM, by the Dream Team ❤️</sub>
</div>