dream_test/reporters/bdd

BDD-style test report formatting.

This module formats TestResult values in a hierarchical, spec-like layout that mirrors your describe / it structure. It’s primarily used by the end-of-run BDD results reporter (runner.results_reporters([bdd.new()])), but it’s also useful directly when you want formatted output as a String (e.g. snapshot tests) or when you’re formatting results incrementally in a custom runner.

Types

FormatIncrementalPartsResult

</>

The result of formatting a single test result incrementally as separate parts.

Fields

headers: Any new suite/group lines required for this result
test_line: The test line (and any failure details) for this result
new_path: The describe/group path for this result. Pass this as previous_path when formatting the next result.

pub type FormatIncrementalPartsResult {
  FormatIncrementalPartsResult(
    headers: String,
    test_line: String,
    new_path: List(String),
  )
}

Constructors

FormatIncrementalPartsResult(
  headers: String,
  test_line: String,
  new_path: List(String),
)

FormatIncrementalResult

</>

The result of formatting a single test result incrementally.

Fields

text: The output to print for this test result (including any new suite/group headers)
new_path: The describe/group path for this result. Pass this as previous_path when formatting the next result.

pub type FormatIncrementalResult {
  FormatIncrementalResult(text: String, new_path: List(String))
}

Constructors

FormatIncrementalResult(text: String, new_path: List(String))

Values

color

</>

pub fn color(
  reporter reporter: types.ResultsReporter,
) -> types.ResultsReporter

Enable ANSI color output for the BDD report.

failures_only

</>

pub fn failures_only(
  reporter reporter: types.ResultsReporter,
) -> types.ResultsReporter

Print only repeated failures and the summary line at the end of the run.

format

</>

pub fn format(results results: List(types.TestResult)) -> String

Format test results as a BDD-style report string.

Returns the complete report including:

Hierarchical test results with status markers
Failure details with messages and diffs
Summary line with counts

Gherkin tests are automatically formatted using the Gherkin reporter style.

Use this when you need the report as a string (e.g., for testing the reporter itself or writing to a file).

Parameters

results: The test results to format

Returns

A single String containing the formatted report and trailing summary line.

Example

let report = bdd.format(sample_results())

report
|> should
|> match_snapshot("./test/snapshots/bdd_format_report.snap")
|> or_fail_with("expected formatted report snapshot match")

format_incremental

</>

pub fn format_incremental(
  result result: types.TestResult,
  previous_path previous_path: List(String),
) -> FormatIncrementalResult

Format a single test result as BDD output, suitable for streaming.

This is designed to be used with ReporterEvent.TestFinished so that BDD output can be printed as tests complete.

previous_path should be the describe-path (all but the leaf test name) of the previously printed result.
Returns the formatted output for this result, and the updated describe-path to use as previous_path for the next call.

Parameters

result: The test result to format
previous_path: The previous describe/group path (from the prior call)

Returns

A FormatIncrementalResult containing the text to print and the new describe/group path to pass as previous_path for the next call.

format_incremental_parts_with_test_indent

</>

pub fn format_incremental_parts_with_test_indent(
  result result: types.TestResult,
  previous_path previous_path: List(String),
  extra_test_indent extra_test_indent: Int,
) -> FormatIncrementalPartsResult

Example

let result = passing_result()
let bdd.FormatIncrementalResult(text: text, new_path: _new_path) =
  bdd.format_incremental_with_test_indent(result, [], 0)

text
|> should
|> match_snapshot(
  "./test/snapshots/bdd_format_incremental_with_test_indent.snap",
)
|> or_fail_with("expected incremental output snapshot match")

Format a single incremental result as two parts:

headers: any new describe/group lines required for this result
test_line: the test line (and any failure details)

This allows callers to insert additional lines (like lifecycle hooks) between headers and the test line while maintaining correct ordering.

Parameters

result: The test result to format
previous_path: The previous describe/group path (from the prior call)
extra_test_indent: Additional indentation to apply to the test line

Returns

A FormatIncrementalPartsResult containing:

headers: any new describe/group lines required for this result
test_line: the test line (and any failure details)
new_path: the updated describe/group path to pass as previous_path for the next call

format_incremental_with_test_indent

</>

pub fn format_incremental_with_test_indent(
  result result: types.TestResult,
  previous_path previous_path: List(String),
  extra_test_indent extra_test_indent: Int,
) -> FormatIncrementalResult

Example

use first <- result.try(first_result([passing_result()]))

let bdd.FormatIncrementalResult(text: _text, new_path: new_path) =
  bdd.format_incremental(first, [])

new_path
|> should
|> be_equal(["Example Suite"])
|> or_fail_with("expected new_path to be the describe path")

Format a single test result as BDD output, allowing an extra indent level for the test line.

Parameters

result: The test result to format
previous_path: The previous describe/group path (from the prior call)
extra_test_indent: Additional indentation to apply to the test line

Returns

A FormatIncrementalResult containing the text to print and the new describe/group path to pass as previous_path for the next call.

format_summary_only

</>

pub fn format_summary_only(
  results results: List(types.TestResult),
) -> String

Example

let result = passing_result()
let text =
  bdd.format_incremental_parts_with_test_indent(result, [], 0)
  |> incremental_parts_text

text
|> should
|> match_snapshot(
  "./test/snapshots/bdd_format_incremental_parts_with_test_indent.snap",
)
|> or_fail_with("expected incremental parts snapshot match")

Format only the trailing summary line (no per-test output).

Parameters

results: The test results to summarize

Returns

A single summary line as a String (including a trailing newline).

new

</>

pub fn new() -> types.ResultsReporter

Create a BDD results reporter.

This reporter prints at the end of the run, using the traversal-ordered results provided by the runner.

render

</>

pub fn render(
  config config: types.BddReporterConfig,
  results results: List(types.TestResult),
) -> String

Render the end-of-run BDD output for the given results.

report

</>

pub fn report(
  results results: List(types.TestResult),
  write write: fn(String) -> Nil,
) -> List(types.TestResult)

Print test results using a provided writer function.

This is the main entry point for most test runs. The writer function receives the formatted report string and can print it, log it, or handle it however needed.

Example

bdd.report([passing_result()], write_bdd_report_to_file)

use text <- result.try(
  file.read("test/tmp/bdd_report.txt")
  |> result.map_error(file.error_to_string),
)

text
|> should
|> match_snapshot("./test/snapshots/bdd_report_file_output.snap")
|> or_fail_with("expected report output snapshot match")

Parameters

results: List of test results from the runner
write: Function that handles the formatted output string

Returns

Returns the input results unchanged, enabling pipeline composition.

summary_only

</>

pub fn summary_only(
  reporter reporter: types.ResultsReporter,
) -> types.ResultsReporter

Print only the summary line at the end of the run.