Struct TestError 

pub struct TestError {
    pub kind: ErrorKind,
    pub message: Option<Cow<'static, str>>,
    pub location: &'static Location<'static>,
    pub context: Vec<ContextFrame>,
    pub trace: Vec<TraceEntry>,
    pub payload: Option<Box<Payload>>,
}

A test failure.

Every fallible test-better operation produces a TestError on the error path, so ? is the single control-flow operator of a test.

Note on the message field

An earlier design sketch had TestError without a top-level message. A dedicated message field is kept here instead of overloading the first context frame: the message answers what failed, while context frames answer while doing what. This deviation is recorded in CHANGELOG.md.

Fields

kind: ErrorKind

The failure category.

message: Option<Cow<'static, str>>

What failed, when there is a concise statement of it.

location: &'static Location<'static>

Where the failure originated (#[track_caller] capture).

context: Vec<ContextFrame>

The context chain, outermost first.

trace: Vec<TraceEntry>

The in-test breadcrumbs (Trace) that were active when this error was built, oldest first. Empty when no Trace was in scope.

payload: Option<Box<Payload>>

Structured detail, when applicable.

Boxed so TestError stays small: it is returned by value through every ? in a test, and Payload::ExpectedActual would otherwise inline three Strings into the struct.

Implementations

impl TestError

pub fn new(kind: ErrorKind) -> Self

Creates a bare error of the given kind, capturing the caller’s location.

pub fn assertion(message: impl Into<Cow<'static, str>>) -> Self

Creates an ErrorKind::Assertion error with the given message.

This is the common path for a hand-written failure: return Err(TestError::assertion("...")).

pub fn custom(message: impl Into<Cow<'static, str>>) -> Self

Creates an ErrorKind::Custom error with the given message, for a failure that does not fit a more specific kind.

pub fn from_expected_actual(expected: impl Debug, actual: impl Debug) -> Self

Creates an ErrorKind::Assertion error from a mismatched expected/actual pair, capturing each value’s Debug representation into a Payload::ExpectedActual.

pub fn with_message(self, message: impl Into<Cow<'static, str>>) -> Self

Sets the message, consuming and returning self.

pub fn with_kind(self, kind: ErrorKind) -> Self

Overrides the kind, consuming and returning self.

This is how a failure is re-categorized after the fact: the #[fixture] macro uses it to turn whatever a fixture body produced into an ErrorKind::Setup failure, so a setup problem never masquerades as an assertion miss.

pub fn with_location(self, location: &'static Location<'static>) -> Self

Overrides the location, consuming and returning self.

The #[track_caller] constructors capture the caller’s location for themselves, so this is rarely needed. It exists for the case where the location must be captured separately from where the error is built: an async fn cannot be #[track_caller], so the async check! methods capture Location::caller synchronously at the call site and thread it through here once the awaited assertion has a result.

pub fn with_payload(self, payload: Payload) -> Self

Sets the payload, consuming and returning self.

pub fn with_context_frame(self, frame: ContextFrame) -> Self

Appends a context frame, consuming and returning self.

pub fn push_context(&mut self, frame: ContextFrame)

Appends a context frame in place.

impl TestError

pub fn to_structured(&self) -> StructuredError

Converts this error into its structured, owned, serializable form.

This is the boundary between test-better and any tooling that consumes failures: tooling reads the structured form, never the rendered text.

Trait Implementations

impl Debug for TestError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Renders the full pretty failure message, so the stock cargo test harness (which prints returned errors with {:?}) is already useful. Unlike Display, this may emit ANSI color, gated by the process-wide ColorChoice.

When the cargo test-better runner is driving the run (it sets RUNNER_ENV), a trailing marker line carrying the structured failure is appended after the human-readable render, for the runner’s structured-output channel. An ordinary cargo test run never sets that variable, so it never sees that line.

impl Display for TestError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Renders the failure as plain text, never colored.

impl Error for TestError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.