Expand description
A rich test assertion library for Rust.
This library provides:
- A framework for writing matchers which can be combined to make a wide range of assertions on data,
- A rich set of matchers, and
- A new set of test assertion macros.
§Learning resources
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.
§Assertions and matchers
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 thegtest
attribute macro on the test itself.verify_that!
has no side effects and evaluates to aResult
whoseErr
variant 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.
}
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, with methods from MatcherBase
:
use googletest::prelude::*;
#[gtest]
fn strictly_between_9_and_11() {
let value = 10;
expect_that!(value, gt(9).and(not(ge(11))));
}
§Available matchers
The following matchers are provided in GoogleTest Rust:
Matcher | What it matches |
---|---|
all! | Anything matched by all given matchers. |
any! | Anything matched by at least one of the given matchers. |
anything | Any input. |
approx_eq | A floating point number within a standard tolerance of the argument. |
char_count | A string with a Unicode scalar count matching the argument. |
container_eq | Same as eq , but for containers (with a better mismatch description). |
contains | A container containing an element matched by the given matcher. |
contains_each! | A container containing distinct elements each of the arguments match. |
contains_regex | A string containing a substring matching the given regular expression. |
contains_substring | A string containing the given substring. |
derefs_to | A Deref which deref() s to a value that the argument matches. |
displays_as | A Display value whose formatted string is matched by the argument. |
each | A container all of whose elements the given argument matches. |
elements_are! | A container whose elements the arguments match, in order. |
empty | An empty collection. |
ends_with | A string ending with the given suffix. |
eq | A value equal to the argument, in the sense of the PartialEq trait. |
err | A Result containing an Err variant the argument matches. |
field! | A struct or enum with a given field whose value the argument matches. |
ge | A PartialOrd value greater than or equal to the given value. |
gt | A PartialOrd value strictly greater than the given value. |
has_entry | A HashMap containing a given key whose value the argument matches. |
is_contained_in! | A container each of whose elements is matched by some given matcher. |
is_nan | A floating point number which is NaN. |
le | A PartialOrd value less than or equal to the given value. |
len | A container whose number of elements the argument matches. |
lt | A PartialOrd value strictly less than the given value. |
matches_pattern! | A struct or enum whose fields are matched according to the arguments. |
matches_regex | A string matched by the given regular expression. |
near | A floating point number within a given tolerance of the argument. |
none | An Option containing None . |
not | Any value the argument does not match. |
ok | A Result containing an Ok variant the argument matches. |
pat! | Alias for matches_pattern! . |
points_to | A reference & which points to a value that the argument matches. |
pointwise! | A container whose contents the arguments match in a pointwise fashion. |
predicate | A value on which the given predicate returns true. |
some | An Option containing Some whose value the argument matches. |
starts_with | A string starting with the given prefix. |
subset_of | A container all of whose elements are contained in the argument. |
superset_of | A container containing all elements of the argument. |
unordered_elements_are! | A container whose elements the arguments match, in any order. |
§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 traits
Matcher
and MatcherBase
:
use googletest::{description::Description, matcher::{Matcher, MatcherBase, MatcherResult}};
use std::fmt::Debug;
#[derive(MatcherBase)]
struct MyEqMatcher<T> {
expected: T,
}
impl<T: PartialEq + Debug + Copy> Matcher<T> for MyEqMatcher<T> {
fn matches(&self, actual: T) -> MatcherResult {
if self.expected == actual {
MatcherResult::Match
} else {
MatcherResult::NoMatch
}
}
fn describe(&self, matcher_result: MatcherResult) -> Description {
match matcher_result {
MatcherResult::Match => {
format!("is equal to {:?} the way I define it", self.expected).into()
}
MatcherResult::NoMatch => {
format!("isn't equal to {:?} the way I define it", self.expected).into()
}
}
}
}
It is recommended to expose a function which constructs the matcher:
pub fn eq_my_way<T: PartialEq + Debug + Copy>(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));
}
§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.
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;
expect_that!(value, eq(2)); // Passes; test still considered passing.
verify_that!(value, eq(3))?; // Fails and aborts the test.
expect_that!(value, eq(3)); // Never executes, since the test already aborted.
Ok(())
}
§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
:
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.
§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:
#[test]
fn always_fails() -> Result<()> {
fail!("This test must fail with {}", "today")
}
§Conversion from Result::Err
and Option::None
To simplify error management during a test arrangement, Result<T>
provides a few conversion utilities.
If your setup function returns std::result::Result<T, E>
where E: std::error::Error
,
the std::result::Result<T, E>
can simply be handled with the ?
operator. If an Err(e)
is returned, the test will report a failure at the line where the ?
operator has been
applied (or the lowest caller without #[track_caller]
).
struct PngImage { h: i32, w: i32 /* ... */ }
impl PngImage {
fn new_from_file(file_name: &str) -> std::result::Result<Self, std::io::Error> {
Err(std::io::Error::new(std::io::ErrorKind::Other, "oh no!"))
}
fn rotate(&mut self) { std::mem::swap(&mut self.h, &mut self.w);}
fn dimensions(&self) -> (i32, i32) { (self.h, self.w)}
}
fn test_png_image_dimensions() -> googletest::Result<()> {
// Arrange
let mut png = PngImage::new_from_file("example.png")?;
verify_eq!(png.dimensions(), (128, 64))?;
// Act
png.rotate();
// Assert
expect_eq!(png.dimensions(), (64, 128));
Ok(())
}
If your setup function returns Option<T>
or std::result::Result<T, E>
where
E: !std::error::Error
, then you can convert these types with into_test_result()
from the IntoTestResult
extension trait.
impl PngImage {
fn new_from_binary(bin: &[u8]) -> std::result::Result<Self, String> {
Err("Parsing failed".into())
}
}
#[gtest]
fn test_png_image_binary() -> googletest::Result<()> {
// Arrange
let png_image = PngImage::new_from_binary(&PNG_BINARY).into_test_result()?;
/* ... */
}
impl PngImage {
fn new_from_cache(key: u64) -> Option<Self> {
None
}
}
#[gtest]
fn test_png_from_cache() -> googletest::Result<()> {
// Arrange
let png_image = PngImage::new_from_cache(123).into_test_result()?;
/* ... */
}
§Integrations with other crates
GoogleTest Rust includes integrations with the
Proptest crates to simplify turning
GoogleTest assertion failures into Proptest
TestCaseError
through the ?
operator.
Modules§
- The components required to implement matchers.
- Utilities to facilitate writing matchers.
- All built-in matchers of this crate are in submodules of this module.
- Re-exports of the symbols in this crate which are most likely to be used.
Macros§
- Macro that wraps the expression with
eq(...)
if the expression is not a matcher. - Matches a value where the result of
callable
applied to the value matches the inner matcher. - Matches a value where the reference to the result of
callable
applied to the value matches the inner matcher. - Generates a failure marking the test as failed but continue execution.
- Generates a failure at specified location marking the test as failed but continue execution.
- Asserts that the given predicate applied to the given arguments returns true, panicking if it does not.
- Matches the given value against the given matcher, panicking if it does not match.
- Marks test as failed and continues execution if the second argument is not equal to first argument.
- Marks test as failed and continue execution if the expression evaluates to true.
- Marks test as failed and continues execution if the float given by the first argument is not approximately equal to the float given by the second argument.
- Marks test as failed and continues execution if the first argument is not greater than or equal to the second argument.
- Marks test as failed and continues execution if the first argument is not greater than the second argument.
- Marks test as failed and continues execution if the first argument is greater than the second argument.
- Marks test as failed and continues execution if the first argument is greater or equal to second argument.
- Marks test as failed and continues execution if the second argument is equal to first argument.
- Marks the test as failed and continues execution if the float given by first argument is not equal to second argument with error tolerance of max_abs_error.
- Asserts that the given predicate applied to the given arguments returns true, failing the test but continuing execution if not.
- Matches the given value against the given matcher, marking the test as failed but continuing execution if it does not match.
- Marks test as failed and continue execution if the expression evaluates to false.
- Evaluates to a
Result
which contains anErr
variant with the given test failure message. - Generates a success. This does not make the overall test succeed. A test is only considered successful if none of its assertions fail during its execution.
- Checks whether the second argument is equal to the first argument.
- Verify if the condition evaluates to false and returns
Result
. - Checks whether the float given by first argument is approximately equal to second argument.
- Checks whether the first argument is greater than or equal to the second argument.
- Checks whether the first argument is greater than the second argument.
- Checks whether the first argument is less than or equal to the second argument.
- Checks whether the first argument is less than second argument.
- Checks whether the second argument is not equal to the first argument.
- Checks whether the float given by first argument is equal to second argument with error tolerance of max_abs_error.
- Asserts that the given predicate applied to the given arguments returns true.
- Checks whether the
Matcher
given by the second argument matches the first argument. - Verify if the condition evaluates to true and returns
Result
.
Traits§
- Adds to
Result
support for GoogleTest Rust functionality. - Provides an extension method for converting an arbitrary type into a
Result
.
Functions§
- Returns a
Result
corresponding to the outcome of the currently running test.
Type Aliases§
- A
Result
whoseErr
variant indicates a test failure.
Attribute Macros§
- Marks a test to be run by the Google Rust test runner.
- Alias for
googletest::gtest
.