GoogleTest Rust
This library brings the rich assertion types of Google's C++ testing library GoogleTest to Rust. It provides:
- A framework for writing matchers which can be combined to make a wide range of assertions on data,
- A rich set of matchers providing similar functionality to those included in GoogleTest, and
- A new set of assertion macros offering similar functionality to those of GoogleTest.
The minimum supported Rust version is 1.59. We recommend using at least version 1.66 for the best developer experience.
:warning: The API is not fully stable and may still be changed until we publish version 1.0.
Assertions and matchers
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:
- Returning immediately from the function with the
?
operator (a fatal assertion), or - Logging the failure, marking the test as failed, and allowing execution to continue (see Non-fatal assertions below).
Fatal assertions are analogous to the ASSERT_*
family of macros in GoogleTest.
For example, for fatal assertions:
use *;
In case one wants behaviour closer to other Rust test libraries, the macro
assert_that!
has the same parameters asverify_that!
but panics on failure.
This library includes a rich set of matchers, covering:
- Equality, numeric inequality, and approximate equality;
- Strings and regular expressions;
- Containers and set-theoretic matching.
Matchers are composable:
use *;
They can also be logically combined:
use *;
Pattern-matching
One can use the macro matches_pattern!
to create a composite matcher for a
struct or enum that matches fields with other matchers:
use *;
Writing matchers
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
:
It is recommended to expose a function which constructs the matcher:
The new matcher can then be used in verify_that!
:
Non-fatal assertions
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 googletest::test
instead of the Rust-standard #[test]
.
It must return Result<()>
.
use *;
Interoperability
You can use the #[googletest::test]
macro together with many other libraries
such as rstest. Just apply both attribute
macros to the test:
Make sure to put #[googletest::test]
before #[rstest]
. Otherwise the
annotated test will run twice, since both macros will attempt to register a test
with the Rust test harness.
The macro also works together with async tests with Tokio in the same way:
async
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.
Predicate assertions
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
:
let x = 3;
let y = 4;
verify_pred!?;
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.
Unconditionally generating a test failure
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:
Contributing Changes
Please read CONTRIBUTING.md for details on how to contribute to this project.