Crate behave 

behave

A BDD testing framework for Rust with a zero-keyword DSL.

behave provides a behave! macro for writing readable test suites and an expect! macro for expressive assertions. Test suites compile to standard #[test] functions — no custom test runner needed.

Quick Start

use behave::prelude::*;

behave! {
    "arithmetic" {
        "addition" {
            expect!(2 + 2).to_equal(4)?;
        }

        "subtraction" {
            expect!(10 - 3).to_equal(7)?;
        }
    }
}

Every matcher returns Result<(), MatchError>, so use ? to propagate failures with clear diagnostics. When an assertion fails you see:

expect!(2 + 2)
  actual: 4
expected: to equal 5

Matcher Reference

All matchers are methods on Expectation. Use expect! to create one. Every matcher supports negation via .not().

Matcher	Description
Equality
.to_equal(v)	Exact equality (==)
.to_not_equal(v)	Exact inequality (!=)
Boolean
.to_be_true()	Value is true
.to_be_false()	Value is false
Ordering
.to_be_greater_than(v)	Strictly greater
.to_be_less_than(v)	Strictly less
.to_be_at_least(v)	Greater or equal (>=)
.to_be_at_most(v)	Less or equal (<=)
Option
.to_be_some()	Value is Some(_)
.to_be_none()	Value is None
.to_be_some_with(v)	Value is Some(v)
Result
.to_be_ok()	Value is Ok(_)
.to_be_err()	Value is Err(_)
.to_be_ok_with(v)	Value is Ok(v)
.to_be_err_with(v)	Value is Err(v)
Collections (Vec<T>, &[T])
.to_contain(v)	Contains element
.to_contain_all_of(&[..])	Contains every element
.to_be_empty()	Length is zero
.to_not_be_empty()	Length is non-zero
.to_have_length(n)	Exact length
Strings
.to_start_with(s)	Has prefix
.to_end_with(s)	Has suffix
.to_contain_substr(s)	Contains substring
.to_have_str_length(n)	Byte length
Floating-Point
.to_approximately_equal(v)	Within default epsilon
.to_approximately_equal_within(v, e)	Within custom epsilon
Regex (requires regex feature)
.to_match_regex(pat)	Full-string regex match
.to_contain_regex(pat)	Substring regex match
General
.to_satisfy(f, desc)	Custom predicate function
.to_match(m)	Custom BehaveMatch impl
expect_panic!	Expression panics
expect_no_panic!	Expression does not panic
Composition (combinators)
all_of	All matchers must pass
any_of	At least one must pass
not_matching	Inverts one matcher
Map (HashMap, BTreeMap)
.to_contain_key(k)	Map has key
.to_contain_value(v)	Map has value
.to_contain_entry(k, v)	Map has key-value pair
Soft Assertions (SoftErrors)
SoftErrors::check	Collect result without stopping
SoftErrors::finish	Report all collected failures

Negation

Any matcher can be negated with .not() or .negate():

use behave::prelude::*;

expect!(42).not().to_equal(99)?;
expect!(vec![1, 2]).not().to_contain(9)?;

Negated failures read naturally:

expect!(value)
  actual: 42
expected: not to equal 42

DSL Features

The behave! macro supports these constructs:

• setup { ... } — shared setup code inherited by nested tests
• teardown { ... } — cleanup code that runs after each test
• each [...] |args| { ... } — parameterized test generation
• pending "name" { ... } — mark tests as ignored
• focus "name" { ... } — mark tests with a __FOCUS__ prefix in generated names
• tag "name1", "name2" — attach metadata tags for CLI filtering
• xfail "name" { ... } — mark a test as expected-to-fail
• matrix [...] x [...] |a, b| { ... } — Cartesian product test generation
• tokio; — generate async tests (requires tokio feature)
• timeout <ms>; — fail tests that exceed a deadline (inherits through nesting)
• skip_when!(condition, "reason") — skip a test conditionally at runtime

Feature Flags

Feature	Default	Description
std	Yes	Standard library support
cli	No	Enables cargo-behave binary
color	No	ANSI-colored diff output for assertion failures
regex	No	to_match_regex and to_contain_regex matchers
tokio	No	Re-exports tokio for tokio; async test generation

Modules

clicli

CLI runner for cargo-behave.

combinators

Matcher combinators for composing multiple matchers.

prelude

Prelude module that re-exports everything needed for writing tests.

Macros

behave

Defines BDD-style test suites using a zero-keyword DSL.

expect

Creates an Expectation capturing the expression and its value.

expect_no_panicstd

Asserts that the given expression does not panic.

expect_panicstd

Asserts that the given expression panics.

skip_whenstd

Conditionally skips a test at runtime with a reason.

Structs

Expectation

Wraps a value with metadata for expressive assertions.

MatchError

Error returned when an expectation matcher fails.

SoftErrorsstd

Collects MatchErrors from soft assertions and reports them together.

SoftMatchErrorstd

Error returned by SoftErrors::finish when assertions failed.

Traits

BehaveMatch

Trait for implementing custom matchers.