Macro fail

macro_rules! fail {
    ($($message:expr),+ $(,)?) => { ... };
    () => { ... };
}

Evaluates to a Result which contains an Err variant with the given test failure message.

This can be used to force the test to fail if its execution reaches a particular point. For example:

match some_value {
    ExpectedVariant => {...}
    UnwantedVaraint => {
        fail!("This thing which should not happen happened anyway")?;
    }
}

One may include formatted arguments in the failure message:

match some_value {
    ExpectedVariant => {...}
    UnwantedVaraint => {
        fail!("This thing which should not happen happened anyway: {}", some_value)?;
    }
}

One may also omit the message, in which case the test failure message will be generic:

match some_value {
    ExpectedVariant => {...}
    UnwantedVaraint => {
        fail!()?;
    }
}

Unlike panic! but analogously to verify_that and verify_pred, this macro has no effect on the flow of control but instead returns a Result which must be handled by the invoking function. This can be done with the question mark operator (as above) or the method and_log_failure.