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.66.
⚠️ The API is not fully stable and may still be changed until we publish version 1.0.Moreover, any items or modules starting with
__(double underscores) must not be used directly. Those items or modules are only for internal uses and their API may change without a major version update.
If you're just getting started with googletest, consider going through
the first chapter of
"Advanced testing for Rust applications",
a self-guided Rust course: it provides a guided introduction to the library,
with exercises to help you get comfortable with googletest macros,
its matchers and its overall philosophy.
The core of GoogleTest is its matchers. Matchers indicate what aspect of an actual value one is asserting: (in-)equality, containment, regular expression matching, and so on.
To make an assertion using a matcher, GoogleTest offers three macros:
assert_that!panics if the assertion fails, aborting the test.expect_that!logs an assertion failure, marking the test as having failed, but allows the test to continue running (called a non-fatal assertion). It requires the use of thegtestattribute macro on the test itself.verify_that!has no side effects and evaluates to aResult<()>whoseErrvariant describes the assertion failure, if there is one. In combination with the?operator, this can be used to abort the test on assertion failure without panicking. It is also the building block for the other two macros above.
For example:
use googletest::prelude::*;
#[test]
fn fails_and_panics() {
let value = 2;
assert_that!(value, eq(4));
}
#[gtest]
fn two_logged_failures() {
let value = 2;
expect_that!(value, eq(4)); // Test now failed, but continues executing.
expect_that!(value, eq(5)); // Second failure is also logged.
}
#[test]
fn fails_immediately_without_panic() -> Result<()> {
let value = 2;
verify_that!(value, eq(4))?; // Test fails and aborts.
verify_that!(value, eq(2))?; // Never executes.
Ok(())
}
#[test]
fn simple_assertion() -> Result<()> {
let value = 2;
verify_that!(value, eq(4)) // One can also just return the last assertion.
}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 googletest::prelude::*;
#[gtest]
fn contains_at_least_one_item_at_least_3() {
let value = vec![1, 2, 3];
expect_that!(value, contains(ge(3)));
}They can also be logically combined:
use googletest::prelude::*;
#[gtest]
fn strictly_between_9_and_11() {
let value = 10;
expect_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:
use googletest::prelude::*;
struct AStruct {
a_field: i32,
another_field: i32,
a_third_field: &'static str,
}
#[test]
fn struct_has_expected_values() {
let value = AStruct {
a_field: 10,
another_field: 100,
a_third_field: "A correct value",
};
expect_that!(value, matches_pattern!(AStruct {
a_field: eq(10),
another_field: gt(50),
a_third_field: contains_substring("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:
struct MyEqMatcher<T> {
expected: T,
}
impl<T: PartialEq + Debug + Copy> Matcher<T> for MyEqMatcher<T> {
fn matches(&self, actual: T) -> MatcherResult {
(self.expected == actual).into()
}
fn describe(&self, matcher_result: MatcherResult) -> String {
match matcher_result {
MatcherResult::Match => {
format!("is equal to {:?} the way I define it", self.expected)
}
MatcherResult::NoMatch => {
format!("isn't equal to {:?} the way I define it", self.expected)
}
}
}
}It is recommended to expose a function which constructs the matcher:
pub fn eq_my_way<T: PartialEq + Debug>(expected: T) -> impl Matcher<T> {
MyEqMatcher { expected }
}The new matcher can then be used in the assertion macros:
#[gtest]
fn should_be_equal_by_my_definition() {
expect_that!(10, eq_my_way(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 gtest instead of the Rust-standard #[test].
use googletest::prelude::*;
#[gtest]
fn three_non_fatal_assertions() {
let value = 2;
expect_that!(value, eq(2)); // Passes; test still considered passing.
expect_that!(value, eq(3)); // Fails; logs failure and marks the test failed.
expect_that!(value, eq(4)); // A second failure, also logged.
}This can be used in the same tests as verify_that!, in which case the test
function must also return Result<()>:
use googletest::prelude::*;
#[gtest]
fn failing_non_fatal_assertion() -> Result<()> {
let value = 2;
expect_that!(value, eq(3)); // Just marks the test as having failed.
verify_that!(value, eq(2))?; // Passes, so does not abort the test.
Ok(()) // Because of the failing expect_that! call above, the
// test fails despite returning Ok(())
}use googletest::prelude::*;
#[gtest]
fn failing_fatal_assertion_after_non_fatal_assertion() -> Result<()> {
let value = 2;
verify_that!(value, eq(3))?; // Fails and aborts the test.
expect_that!(value, eq(3)); // Never executes, since the test already aborted.
Ok(())
}You can use the #[gtest] macro together with many other libraries
such as rstest. Just apply both attribute
macros to the test:
#[gtest]
#[rstest]
#[case(1)]
#[case(2)]
#[case(3)]
fn rstest_works_with_google_test(#[case] value: u32) -> Result<()> {
verify_that!(value, gt(0))
}Make sure to put #[gtest] 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:
#[gtest]
#[tokio::test]
async fn should_work_with_tokio() -> Result<()> {
verify_that!(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:
fn stuff_is_correct(x: i32, y: i32) -> bool {
x == y
}
let x = 3;
let y = 4;
verify_pred!(stuff_is_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:
#[test]
fn always_fails() -> Result<()> {
fail!("This test must fail with {}", "today")
}This library is configurable through environment variables. Since the
configuration does not impact whether a test fails or not but how a failure is
displayed, we recommend setting those variables in the personal
~/.cargo/config.toml instead of in the project-scoped Cargo.toml.
| Variable name | Description |
|---|---|
| NO_COLOR | Disables colored output. See https://no-color.org/. |
| FORCE_COLOR | Forces colors even when the output is piped to a file. |
Please read CONTRIBUTING.md for details on how to contribute to this project.
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent