snapshot

Snapshot matchers for dream_test.

Snapshot testing compares output against a stored “golden” file.

On first run (missing snapshot), the snapshot is created and the test passes.
On later runs, the output is compared against the file; differences fail.

Snapshot tests are useful when the output is large or awkward to specify by hand (rendered HTML, JSON, error messages, logs, etc.).

Example

let path = "./test/tmp/match_snapshot_example.snap"
"hello"
|> should
|> match_snapshot(path)
|> or_fail_with("expected snapshot match")

Values

clear_snapshot

</>

pub fn clear_snapshot(
  snapshot_path: String,
) -> Result(Nil, String)

Delete a snapshot file to force regeneration.

Use this to programmatically clear a snapshot. The next test run will create a fresh snapshot with the current output.

Parameters

snapshot_path - Path to the snapshot file to delete

Returns

Ok(Nil) - Snapshot was deleted (or didn’t exist)
Error(String) - Human-readable error message

Example

let path = "./test/tmp/clear_snapshot_example.snap"

// Setup: create a snapshot file (no assertions during setup)
use _ <- result.try(
  file.write(path, "hello") |> result.map_error(file.error_to_string),
)

clear_snapshot(path)
|> should
|> be_equal(Ok(Nil))
|> or_fail_with("expected clear_snapshot to succeed")

clear_snapshots_in_directory

</>

pub fn clear_snapshots_in_directory(
  directory: String,
) -> Result(Int, String)

Delete all .snap files in a directory.

Clears all snapshot files in the given directory (non-recursively). Useful for resetting all snapshots before a major refactor.

Parameters

directory - Path to the directory containing snapshots

Returns

Ok(Int) - Number of snapshot files deleted
Error(String) - Human-readable error message

Example

let directory = "./test/tmp/clear_snapshots_in_directory_example"
let a = directory <> "/a.snap"
let b = directory <> "/b.snap"

// Setup: create two snapshot files (no assertions during setup)
use _ <- result.try(
  file.write(a, "a") |> result.map_error(file.error_to_string),
)
use _ <- result.try(
  file.write(b, "b") |> result.map_error(file.error_to_string),
)

clear_snapshots_in_directory(directory)
|> should
|> be_equal(Ok(2))
|> or_fail_with("expected two deleted snapshots")

match_snapshot

</>

pub fn match_snapshot(
  value_or_result value_or_result: types.MatchResult(String),
  snapshot_path snapshot_path: String,
) -> types.MatchResult(String)

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

This is the primary snapshot matcher. Use it when you have string output (JSON, HTML, plain text, etc.) that you want to compare against a snapshot.

Behavior

Snapshot doesn’t exist: Creates it and the test passes
Snapshot exists and matches: Test passes
Snapshot exists but differs: Test fails with detailed diff

Parameters

value_or_result - The MatchResult(String) from the assertion chain
snapshot_path - Path to the snapshot file (will be created if missing)

Example

let path = "./test/tmp/match_snapshot_example.snap"
"hello"
|> should
|> match_snapshot(path)
|> or_fail_with("expected snapshot match")

Returns

A MatchResult(String):

On success, preserves the original string for further chaining.
On failure, the chain becomes failed and later matchers are skipped.

match_snapshot_inspect

</>

pub fn match_snapshot_inspect(
  value_or_result value_or_result: types.MatchResult(value),
  snapshot_path snapshot_path: String,
) -> types.MatchResult(value)

Assert that any value matches a snapshot when serialized.

Use this when testing complex data structures that aren’t strings. The value is converted to a string using string.inspect, which produces Gleam’s debug representation.

When to Use This

Testing return values of functions (records, tuples, lists)
Comparing parsed AST structures
Verifying complex state after operations

Parameters

value_or_result - The MatchResult(value) from the assertion chain
snapshot_path - Path to the snapshot file

Example

let path = "./test/tmp/match_snapshot_inspect_example.snap"
Some(1)
|> should
|> match_snapshot_inspect(path)
|> or_fail_with("expected inspect snapshot match")

Returns

A MatchResult(value):

On success, preserves the original value for further chaining.
On failure, the chain becomes failed and later matchers are skipped.