Assert that an integer is at least a minimum value (>=).

Example

user.age
|> should()
|> be_at_least(18)
|> or_fail_with("User must be at least 18")

Assert that an integer is at most a maximum value (<=).

Example

password.length
|> should()
|> be_at_most(128)
|> or_fail_with("Password must be at most 128 characters")

Assert that an integer is between two values (exclusive).

The value must be strictly greater than min and strictly less than max.

Example

port
|> should()
|> be_between(1024, 65535)
|> or_fail_with("Port must be between 1024 and 65535")

Assert that a list is empty.

Example

get_errors()
|> should()
|> be_empty()
|> or_fail_with("Should have no errors")

Assert that a Result is Error and extract the error value.

If the assertion passes, the error value is passed to subsequent matchers.

Example

parse_int("not a number")
|> should()
|> be_error()
|> or_fail_with("Should fail to parse")

// With chaining:
validate(input)
|> should()
|> be_error()
|> equal(ValidationError("email required"))
|> or_fail_with("Should fail with email error")

Assert that a value is False.

Example

is_empty(list)
|> should()
|> be_false()
|> or_fail_with("List should not be empty")

Assert that an integer is greater than a threshold.

Example

count_items()
|> should()
|> be_greater_than(0)
|> or_fail_with("Should have at least one item")

Assert that a float is greater than a threshold.

Example

average
|> should()
|> be_greater_than_float(0.0)
|> or_fail_with("Average should be positive")

Assert that an integer is within a range (inclusive).

The value must be >= min and <= max.

Example

score
|> should()
|> be_in_range(0, 100)
|> or_fail_with("Score must be 0-100")

Assert that an integer is less than a threshold.

Example

response_time_ms
|> should()
|> be_less_than(100)
|> or_fail_with("Response should be under 100ms")

Assert that a float is less than a threshold.

Example

error_rate
|> should()
|> be_less_than_float(0.01)
|> or_fail_with("Error rate should be under 1%")

Assert that an Option is None.

Example

find_deleted_user(id)
|> should()
|> be_none()
|> or_fail_with("Deleted user should not exist")

Assert that a Result is Ok and extract its value.

If the assertion passes, the Ok value is passed to subsequent matchers. This enables chaining like be_ok() |> equal(42).

Example

parse_int("42")
|> should()
|> be_ok()
|> or_fail_with("Should parse successfully")

// With chaining:
parse_int("42")
|> should()
|> be_ok()
|> equal(42)
|> or_fail_with("Should parse to 42")

Assert that an Option is Some and extract its value.

If the assertion passes, the inner value is passed to subsequent matchers. This enables chaining like be_some() |> equal(42).

Example

find_user(id)
|> should()
|> be_some()
|> or_fail_with("User should exist")

// With chaining:
find_user(id)
|> should()
|> be_some()
|> equal(expected_user)
|> or_fail_with("Should find the expected user")

Assert that a value is True.

Example

is_valid(input)
|> should()
|> be_true()
|> or_fail_with("Input should be valid")

Delete a snapshot file.

Use this to force regeneration of a snapshot on the next test run.

Example

let _ = clear_snapshot("./test/snapshots/old.snap")

Delete all snapshot files in a directory.

Deletes all files with the .snap extension in the given directory.

Example

let _ = clear_snapshots_in_directory("./test/snapshots")

Assert that a list contains a specific item.

Example

[1, 2, 3]
|> should()
|> contain(2)
|> or_fail_with("List should contain 2")

Assert that a string contains a substring.

Example

log_message
|> should()
|> contain_string("error")
|> or_fail_with("Log should mention error")

Assert that a string ends with a suffix.

Example

filename
|> should()
|> end_with(".gleam")
|> or_fail_with("File should be a Gleam file")

Assert that a value equals the expected value.

Uses Gleam’s structural equality (==).

Example

add(2, 3)
|> should()
|> equal(5)
|> or_fail_with("2 + 3 should equal 5")

Explicitly fail a test with a message.

Use this when you need to fail a test in a conditional branch where the normal assertion chain doesn’t apply.

Example

case result {
  Ok(value) -> {
    value
    |> should()
    |> equal(expected)
    |> or_fail_with("Value should match")
  }
  Error(_) -> fail_with("Should have succeeded but got an error")
}

When to Use

• In case branches that represent unexpected states
• When testing that something does NOT happen
• As a placeholder for unimplemented test branches

Assert that a list has a specific length.

Example

get_users()
|> should()
|> have_length(3)
|> or_fail_with("Should have 3 users")

Assert that a string matches the content of a snapshot file.

• If snapshot doesn’t exist: creates it and passes
• If snapshot exists and matches: passes
• If snapshot exists but doesn’t match: fails

To update a snapshot: delete the file and re-run the test.

Example

render_html()
|> should()
|> match_snapshot("./test/snapshots/page.snap")
|> or_fail_with("HTML should match snapshot")

Assert that any value matches a snapshot (using string.inspect).

Serializes the value using string.inspect and compares against the stored snapshot. Useful for testing complex data structures.

Example

build_config()
|> should()
|> match_snapshot_inspect("./test/snapshots/config.snap")
|> or_fail_with("Config should match snapshot")

Assert that a list does not contain a specific item.

Example

["a", "b", "c"]
|> should()
|> not_contain("d")
|> or_fail_with("List should not contain 'd'")

Assert that a value does not equal the unexpected value.

Example

divide(10, 3)
|> should()
|> not_equal(3)
|> or_fail_with("10/3 should not equal 3 exactly")

Complete an assertion chain and provide a failure message.

This is the terminal operation that ends every assertion chain. It converts the MatchResult into an AssertionResult that the test runner understands.

If the assertion passed, returns AssertionOk. If it failed, returns AssertionFailed with the provided message.

Example

result
|> should()
|> equal(42)
|> or_fail_with("Result should be 42")

Writing Good Messages

Good failure messages explain what should have happened:

• ✓ “User should be authenticated after login”
• ✓ “Cart total should include tax”
• ✗ “wrong”
• ✗ “failed”

Start an assertion chain.

This wraps any value in a MatchResult so it can be piped into matchers. Every assertion chain should start with this function.

Example

42
|> should()
|> equal(42)
|> or_fail_with("Should be 42")

Assert that a string starts with a prefix.

Example

greeting
|> should()
|> start_with("Hello")
|> or_fail_with("Greeting should start with Hello")

Explicitly mark an assertion as successful.

Use this when you need to explicitly succeed in a conditional branch, as the counterpart to fail_with.

Example

case result {
  Ok(_) -> succeed()
  Error(_) -> fail_with("Should have succeeded")
}

When to Use

• In case branches where success is the expected outcome
• When all branches of a case must return an AssertionResult
• To make intent explicit rather than relying on implicit success