behave

behave is a behavior-driven testing library for Rust. It gives you a behave! macro for nested, readable test suites and an expect! API for expressive assertions, while still compiling down to ordinary #[test] functions.

What It Is

Use behave when you want test code that reads like scenarios instead of a flat list of unrelated unit tests:

• nested groups instead of large test modules
• setup blocks that flow into child scenarios
• each blocks for parameterized/table-driven tests
• matrix blocks for Cartesian product test generation
• xfail for expected-failure tests
• tag metadata for grouping and filtering tests
• skip_when! for runtime conditional skipping
• built-in matchers for equality, strings, collections, options, results, and floats
• pending and focus markers for test workflow
• optional cargo-behave CLI with tree/JSON/JUnit output, watch mode, tag filtering, and flaky-test detection

How It Works

behave! is a proc macro. At compile time it turns your scenario tree into standard Rust test functions, so cargo test still runs the suite and there is no custom runtime to keep alive.

Start Fast

Add the crate as a dev-dependency:

cargo add behave --dev

Create tests/behave_smoke.rs:

use behave::prelude::*;

behave! {
    "checkout totals" {
        setup {
            let prices = [120, 80, 40];
            let subtotal: i32 = prices.iter().sum();
        }

        "adds line items" {
            expect!(subtotal).to_equal(240)?;
        }

        "renders a receipt line" {
            let receipt = format!("subtotal={subtotal}");
            expect!(receipt).to_contain_substr("240")?;
        }
    }

    pending "applies coupon codes" {}
}

Run it:

cargo test

That is the whole onboarding path. The generated tests are normal #[test] items, so you can keep using the usual Rust tooling around them.

Parameterized Tests

Use each to generate one test per case. Each case becomes its own #[test] function, so failures tell you exactly which input broke:

use behave::prelude::*;

behave! {
    "addition" {
        each [
            (2, 2, 4),
            (0, 0, 0),
            (-1, 1, 0),
        ] |a, b, expected| {
            expect!(a + b).to_equal(expected)?;
        }
    }
}

This generates addition::case_0, addition::case_1, and addition::case_2.

Single-parameter cases work too:

use behave::prelude::*;

behave! {
    "Fibonacci numbers are positive" {
        each [1, 1, 2, 3, 5, 8, 13] |n| {
            expect!(n).to_be_greater_than(0)?;
        }
    }
}

each inherits setup, teardown, and tokio; from the parent group:

use behave::prelude::*;

behave! {
    "tax calculation" {
        setup {
            let tax_rate = 0.08_f64;
        }

        "computes total with tax" {
            each [
                (100.0_f64, 108.0_f64),
                (50.0_f64, 54.0_f64),
                (0.0_f64, 0.0_f64),
            ] |price, expected| {
                let total = price.mul_add(tax_rate, price);
                expect!(total).to_approximately_equal(expected)?;
            }
        }
    }
}

See examples/parameterized.rs for the full working example.

Setup Inheritance

setup bindings flow from parent groups into child scenarios and child setup blocks. This avoids duplicating shared state:

use behave::prelude::*;

behave! {
    "order pricing" {
        setup {
            let items = vec![1200, 800, 350];
            let total: i64 = items.iter().sum();
        }

        "subtotal sums line items" {
            expect!(total).to_equal(2350)?;
        }

        "with 10% discount" {
            setup {
                let discounted = total - (total * 10 / 100);
            }

            "applies percentage" {
                expect!(discounted).to_equal(2115)?;
            }

            "with shipping" {
                setup {
                    let final_total = discounted + 500;
                }

                "adds flat fee" {
                    expect!(final_total).to_equal(2615)?;
                }
            }
        }
    }
}

See examples/setup_inheritance.rs for a fuller version with helper functions and shadowing.

Teardown

teardown blocks run after every test in the group, even if the test panics (sync tests) or returns an error (async tests). Use them for cleanup:

use behave::prelude::*;

behave! {
    "database tests" {
        setup {
            let pool = vec!["conn_1"];
        }

        teardown {
            // Runs after the test body (panic-safe in sync mode).
            drop(pool);
        }

        "connection is available" {
            expect!(pool).to_have_length(1)?;
        }
    }
}

Inner teardowns run before outer teardowns (like destructors). See examples/teardown.rs for nested teardown patterns.

Copy-Paste Commands

Create a new project and try behave in one go:

cargo new behave-demo
cd behave-demo
cargo add behave --dev
mkdir -p tests

Then put the Quick Start example above into tests/behave_smoke.rs and run cargo test.

Install the optional CLI:

cargo install behave --features cli

Run the suite with tree output:

cargo behave

Run only tests tagged slow:

cargo behave --tag slow

Watch for file changes and re-run:

cargo behave --watch

Emit a machine-readable report:

cargo behave --output json
cargo behave --output junit

Features

Macros

Matchers

All matchers respect .not() / .negate().

The matcher docs live in docs/matchers/ with one page per matcher (plus a quick index).

Real Examples

What You Can And Cannot Do

You can:

• nest groups freely
• share bindings from a parent setup into child scenarios
• shadow a setup binding with a later let in a child setup or scenario body
• use each blocks for parameterized/table-driven test generation
• use teardown blocks for cleanup after each test (panic-safe in sync, error-safe in async)
• declare tokio; in a group to generate #[tokio::test] async tests (requires tokio feature)
• use cargo test normally because generated tests are ordinary #[test] functions
• use cargo behave for tree output, filters, and libtest flags
• use cargo behave --output json or cargo behave --output junit for CI-friendly reports
• use cargo behave --manifest-path path/to/Cargo.toml or --package name in workspaces
• use cargo behave --tag slow to run only tagged tests, --exclude-tag flaky to exclude
• use cargo behave --focus to run only focused tests
• use cargo behave --fail-on-focus to reject focused tests in CI
• use cargo behave --watch to re-run on file changes
• use skip_when!(condition, "reason") to conditionally skip tests at runtime

Current limitations:

• one setup block per group, one teardown block per group
• DSL order within a group: tokio; → timeout → setup {} → teardown {} → children
• pending blocks must be empty
• async teardown is error-safe but not panic-safe (no catch_unwind across .await points)

Why Rely On It

The current trust signals are intentionally concrete:

• behave! compiles to ordinary #[test] functions
• runnable examples live in examples/ and are exercised in tests
• public docs, doctests, Clippy, and rustdoc warnings are checked together
• unsafe is forbidden by lint configuration
• limitations are documented explicitly instead of left implicit
• security reporting is documented in SECURITY.md

For the fuller trust and maintenance picture, see docs/RELIABILITY.md.

Flaky Test Detection

Create behave.toml in your project root:

[flaky_detection]
enabled = true
history_file = ".behave/history.json"
consecutive_passes = 5

When enabled, cargo behave records past outcomes and warns when a test fails after many consecutive passes without source changes in the selected package set.

Add .behave/ to .gitignore.

Documentation

• User Guide
• Macro Reference — behave! | expect! | expect_panic! | expect_no_panic! | skip_when!
• Matcher Reference
• CLI Guide
• Reliability
• Architecture
• Contributing
• API docs on docs.rs

Security

See SECURITY.md for the reporting process.

License

Licensed under the Apache License, Version 2.0. See LICENSE.