This library brings the rich assertion types of Google's C++ testing library GoogleTest to Rust. It provides:
We recommend using Rust 1.66 or later with this library. It does not work smoothly with prior versions.
:warning: The API is not fully stable and may still be changed until we publish version 1.0.
Most assertions are made through the macro [verify_that!] which evaluates to a
[Result<()>]. It takes two arguments: an actual value to be tested and a
[Matcher].
Unlike the macros used in other test assertion libraries in Rust, verify_that!
does not panic when the test assertion fails. Instead, it evaluates to Result,
which the caller can choose to handle by:
? operator (a fatal
assertion), orFatal assertions are analogous to the ASSERT_* family of macros in GoogleTest.
For example, for fatal assertions:
```rust use googletest::{matchers::eq, verify_that, Result};
fn morethanonefailure() -> Result<()> { let value = 2; verifythat!(value, eq(4))?; // Fails and ends execution of the test. verify_that!(value, eq(2)) // One can also just return the assertion result. } ```
In case one wants behaviour closer to other Rust test libraries, the macro [
assert_that!] has the same parameters as [verify_that!] but panics on failure.
This library includes a rich set of matchers, covering:
Matchers are composable:
```rust use googletest::{matchers::{contains, ge}, verify_that, Result};
fn containsatleastoneitematleast3() -> Result<()> { let value = vec![1, 2, 3]; verifythat!(value, contains(ge(3))) } ```
They can also be logically combined:
```rust use googletest::{matchers::{gt, lt, not, AndMatcherExt}, verify_that, Result};
fn strictlybetween9and11() -> Result<()> { let value = 10; verify_that!(value, gt(9).and(not(ge(11)))) } ```
One can use the macro [matches_pattern!] to create a composite matcher for a
struct or enum that matches fields with other matchers:
```rust use googletest::{ matchers::{containssubstring, eq, gt}, matchespattern, verify_that, Result, };
struct AStruct { afield: i32, anotherfield: i32, athirdfield: &'static str, }
fn structhasexpectedvalues() -> Result<()> { let value = AStruct { afield: 10, anotherfield: 100, athirdfield: "A correct value", }; verifythat!(value, matchespattern!(AStruct { afield: eq(10), anotherfield: gt(50), athirdfield: containssubstring("correct"), })) } ```
One can extend the library by writing additional matchers. To do so, create a
struct holding the matcher's data and have it implement the trait [Matcher]:
```rust
struct MyEqMatcher
impl
fn describe(&self, matcher_result: MatcherResult) -> String {
match matcher_result {
MatcherResult::Matches => {
format!("is equal to {:?} the way I define it", self.expected)
}
MatcherResult::DoesNotMatch => {
format!("isn't equal to {:?} the way I define it", self.expected)
}
}
}
} ```
It is recommended to expose a function which constructs the matcher:
rust
pub fn eq_my_way<T: PartialEq + Debug>(expected: T) -> impl Matcher<T> {
MyEqMatcher { expected }
}
The new matcher can then be used in verify_that!:
```rust
fn shouldbeequalbymydefinition() -> Result<()> { verifythat!(10, eqmyway(10)) } ```
Using non-fatal assertions, a single test is able to log multiple assertion failures. Any single assertion failure causes the test to be considered having failed, but execution continues until the test completes or otherwise aborts.
This is analogous to the EXPECT_* family of macros in GoogleTest.
To make a non-fatal assertion, use the macro [expect_that!]. The test must
also be marked with [google_test] instead of the Rust-standard #[test]. It
must return [Result<()>].
```rust use googletest::{ expectthat, googletest, matchers::eq, Result };
fn morethanonefailure() -> Result<()> { let value = 2; expectthat!(value, eq(3)); // Just marks the test as having failed. verify_that!(value, eq(2))?; // Passes, but the test already failed. Ok(()) } ```
You can use the #[google_test] macro together with many other libraries such
as rstest. Just apply both attribute macros
to the test:
```rust
fn rstestworkswithgoogletest(#[case] value: u32) -> Result<()> { verify_that!(value, gt(0)) } ```
The macro also works together with async tests with Tokio in the same way:
```rust
async fn shouldworkwithtokio() -> Result<()> { verifythat!(3, gt(0)) } ```
There is one caveat when running async tests: test failure reporting through
and_log_failure will not work properly if the assertion occurs on a different
thread than runs the test.
The macro [verify_pred!] provides predicate assertions analogous to
GoogleTest's EXPECT_PRED family of macros. Wrap an invocation of a predicate
in a verify_pred! invocation to turn that into a test assertion which passes
precisely when the predicate returns true:
```rust fn stuffiscorrect(x: i32, y: i32) -> bool { x == y }
let x = 3; let y = 4; verifypred!(stuffis_correct(x, y))?; ```
The assertion failure message shows the arguments and the values to which they evaluate:
stuff_is_correct(x, y) was false with
x = 3,
y = 4
The verify_pred! invocation evaluates to a [Result<()>] just like
[verify_that!]. There is also a macro [expect_pred!] to make a non-fatal
predicaticate assertion.
The macro [fail!] unconditionally evaluates to a Result indicating a test
failure. It can be used analogously to [verify_that!] and [verify_pred!] to
cause a test to fail, with an optional formatted message:
```rust
fn always_fails() -> Result<()> { fail!("This test must fail with {}", "today") } ```
Please read CONTRIBUTING.md for details on how to contribute to this project.