Formatters

Behave's runner is decoupled from its output: every line it prints is emitted through a formatter. The default selection (when --format is not given) is progress (compact dot-stream output). You can swap in any class that composes the BDD::Behave::Formatter role to render runs differently: indented tree, hierarchical documentation, JSON, JUnit XML, and so on.

Selecting a formatter

Pass --format NAME to behave:

$ behave --format tree specs/users-spec.raku

NAME must be a registered formatter. The built-in formatters are documentation, html, json, json-events, junit, progress, tap, and tree. (json-events is the line-delimited event stream parallel workers use to report back to the parent. It is registered and selectable but rarely useful on its own.) An unknown name fails fast:

$ behave --format nope
Error: unknown --format 'nope' (available: documentation, html, json, json-events, junit, progress, tap, tree)

When --format is omitted, progress is selected. The currently registered names are also listed in behave --help.

Built-in formatters

progress

The default. Compact single-line output, one character per example. See the dedicated entry below.

tree

Behave's classic indented tree output (formerly called default): one line per describe/context/it, a green SUCCESS / red FAILURE marker per example, and an inline SLOW annotation when --slow-threshold fires. Useful for debugging: you can see exactly which example is running when something hangs or hits a long step.

documentation

A clean, document-style rendering of the spec tree. Each describe/context is printed as a heading (no quotes, no arrow markers) and each example is printed as an indented line beneath its enclosing group. Non-passing outcomes get a parenthetical suffix:

The Failures: block, counts line, profile/benchmark sections, and the multi-file Overall: block all print exactly as they do under tree, except in multi-file mode the per-file Failures: + counts line is deferred. Every spec file's tree streams uninterrupted under its own filename heading, and a single Failures: block plus the Overall: counts print once at the end.

$ behave --format documentation specs/calc-spec.raku
Calculator
  addition
    adds two positive numbers
    overflows on MAX_INT (FAILED)
    handles negative-zero (PENDING)
  subtraction
    subtracts a positive from a positive

Failures:

  [ ✗ ] specs/calc-spec.raku:24
      Expected: 2147483648
      to be: -2147483648

5 examples, 1 failed, 1 pending, 3 passed

html

A self-contained HTML5 report with collapsible describe/context nesting (native <details>/<summary>, no JavaScript required) and color-coded examples. Designed to be redirected to a file and opened in a browser:

$ behave --format html specs/ > report.html
$ open report.html

Structure:

Inline <style> provides the default theme. Colors are hard-coded (no external CSS). All user descriptions and file paths are HTML-escaped (<, >, &, "). In multi-file mode every spec file gets an <h2 class="suite-file"> heading and a single HTML document covers the entire run.

json

Emits a single JSON document on stdout after the run finishes, designed for CI dashboards and tool integration. No per-example or per-group output is printed, so the document is the only thing on stdout (load errors and CLI flag errors are still emitted to stderr as usual).

Top-level shape:

{
  "version": 1,
  "order": "random",
  "seed": 42,
  "aborted": false,
  "examples": [...],
  "load_errors": [...],
  "summary": {
    "total": 5,
    "passed": 2,
    "failed": 1,
    "pending": 1,
    "skipped": 1,
    "duration": 0.045
  },
  "summary_line": "5 examples, 1 failed, 1 pending, 1 skipped, 2 passed"
}

Each entry in examples carries:

In multi-file mode the document is emitted once, after every spec file has run, with summary reflecting the merged counts. Per-suite intermediate emission is suppressed.

junit

JUnit XML format consumable by Jenkins, GitLab CI, CircleCI, and other CI dashboards that ingest the testsuites/testsuite/testcase schema.

<?xml version="1.0" encoding="UTF-8"?>
<testsuites name="behave" tests="5" failures="1" errors="0" skipped="2" time="0.045000">
  <testsuite name="calc-spec.raku" tests="5" failures="1" errors="0" skipped="2" time="0.045000" timestamp="..." file="specs/calc-spec.raku">
    <testcase classname="Calculator" name="adds positive numbers" file="specs/calc-spec.raku" line="4" time="0.001000"/>
    <testcase classname="Calculator &gt; addition" name="overflows" file="specs/calc-spec.raku" line="9" time="0.001000">
      <failure type="Expectation" message="Expected 2147483648 to be -2147483648"><![CDATA[
specs/calc-spec.raku:9
  Expected: 2147483648
  to be:    -2147483648
      ]]></failure>
    </testcase>
    <testcase classname="Calculator" name="todo" file="specs/calc-spec.raku" line="12" time="0.000000">
      <skipped message="pending: not yet implemented"/>
    </testcase>
  </testsuite>
</testsuites>

Conventions:

The classname attribute joins the enclosing describe/context chain with > so CI dashboards that group by class produce a sensible hierarchy. Special characters (<, >, &, ", ') in attribute values are XML-escaped. CDATA bodies have ]]> re-encoded as ]]]]><![CDATA[> so they survive arbitrary payloads. In multi-file mode every spec file produces its own <testsuite> element under a single <testsuites> root.

tap

Test Anything Protocol version 13 output for compatibility with TAP consumers (prove, tappy, etc.):

TAP version 13
1..5
ok 1 - Calculator addition adds positive numbers
not ok 2 - Calculator addition overflows on MAX_INT
  ---
  severity: 'fail'
  file: 'specs/calc-spec.raku'
  line: 24
  message: 'Expected 2147483648 to be -2147483648'
  got: '2147483648'
  expected: '-2147483648'
  ...
ok 3 - Calculator addition handles negative-zero # TODO not yet implemented
ok 4 - Calculator addition obsoleted # SKIP skipped
ok 5 - Calculator subtraction subtracts a positive from a positive

Conventions:

The full describe/context chain is prefixed onto each description (joined by spaces). # characters embedded in user descriptions are escaped as \# so a TAP parser cannot mistake them for the start of a directive. In multi-file mode a single TAP document covers all spec files (one plan line, one numbering sequence).

progress

Compact single-line output, one character per example:

Group descriptions, it descriptions, and inline slow markers are suppressed. The failures detail block, counts line, profile/benchmark sections, and the multi-file Overall: block still print exactly as they do under tree, except in multi-file mode the per-file Failures: + counts line is deferred. Dots stream continuously across every spec file, then a single Failures: block plus the Overall: counts print once at the end.

$ behave --format progress specs/
.....FF*.S....

Failures:

  [ ✗ ] specs/calc-spec.raku:24
      Expected: 1
      to be: 2
  [ ✗ ] specs/db-spec.raku:11
      exception in Database connect refuses without credentials: connection refused

14 examples, 2 failed, 1 pending, 1 skipped, 10 passed

Both expectation mismatches and exception-based failures (an example body that dies or throws) appear in the Failures: block with their source file:line, so a progress run is enough to diagnose what to fix without re-running under tree.

The BDD::Behave::Formatter role

BDD::Behave::Formatter is a Raku role that declares a hook for every interesting event the runner emits. All hooks have no-op default bodies, so custom formatters only need to override the events they care about.

Lifecycle hooks

Summary hooks

Writing a custom formatter

use BDD::Behave::Formatter;
use BDD::Behave::Formatter::Registry;

class DotsFormatter does BDD::Behave::Formatter {
  method name(--> Str) { 'dots' }

  method example-pass($example)                   { print '.' }
  method example-fail($example, :$failure-info)   { print 'F' }
  method example-pending($example)                { print '*' }
  method example-skipped($example)                { print 'S' }
  method run-summary($result, *%) {
    say "";
    say "{$result.total} examples, {$result.failed} failed, {$result.passed} passed";
  }
}

BDD::Behave::Formatter::Registry.register('dots', DotsFormatter);

Once registered, the formatter is available to --format:

$ behave --format dots

The registry

BDD::Behave::Formatter::Registry is a name-to-class lookup the CLI consults when resolving --format.

use BDD::Behave::Formatter::Registry;

BDD::Behave::Formatter::Registry.names;
# → (documentation html json json-events junit progress tap tree)

BDD::Behave::Formatter::Registry.register('dots', DotsFormatter);
BDD::Behave::Formatter::Registry.registered('dots');   # True
BDD::Behave::Formatter::Registry.lookup('dots');       # DotsFormatter
BDD::Behave::Formatter::Registry.create('dots');       # DotsFormatter instance

BDD::Behave::Formatter::Registry.reset;                # back to the built-ins

Duplicate registrations and classes that do not compose the role are rejected with a clear error.

Passing a formatter directly to the runner

The runner accepts a :formatter argument for embedded use cases (custom CLIs, IDE integrations, etc.):

use BDD::Behave::Runner;
use BDD::Behave::Formatter::Tree;

my $f = BDD::Behave::Formatter::Tree.new;
my $runner = BDD::Behave::Runner::Runner.new(:formatter($f));
$runner.run($suite);

When :formatter is omitted, a BDD::Behave::Formatter::Tree instance is constructed automatically. (Note that the behave CLI selects progress by default when --format is not supplied. The runner constructor's default is Tree because tree output is the most useful for embedded/IDE consumers programmatically inspecting events.)