Crate googletest

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 the googletest::test attribute macro on the test itself.
• verify_that! has no side effects and evaluates to a Result whose Err 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));
}

#[googletest::test]
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::*;

#[googletest::test]
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::*;

#[googletest::test]
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:

#[googletest::test]
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 googletest::test instead of the Rust-standard #[test].

use googletest::prelude::*;

#[googletest::test]
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::*;

#[googletest::test]
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::*;

#[googletest::test]
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())
  }
}

#[googletest::test]
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
  }
}

#[googletest::test]
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

• description
• matcher
  The components required to implement matchers.
• matcher_support
  Utilities to facilitate writing matchers.
• matchers
  All built-in matchers of this crate are in submodules of this module.
• prelude
  Re-exports of the symbols in this crate which are most likely to be used.

Macros

• __auto_eq
  Macro that wraps the expression with eq(...) if the expression is not a matcher.
• add_failure
  Generates a failure marking the test as failed but continue execution.
• add_failure_at
  Generates a failure at specified location marking the test as failed but continue execution.
• assert_pred
  Asserts that the given predicate applied to the given arguments returns true, panicking if it does not.
• assert_that
  Matches the given value against the given matcher, panicking if it does not match.
• expect_eq
  Marks test as failed and continues execution if the second argument is not equal to first argument.
• expect_false
  Marks test as failed and continue execution if the expression evaluates to true.
• expect_float_eq
  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.
• expect_ge
  Marks test as failed and continues execution if the first argument is not greater than or equal to the second argument.
• expect_gt
  Marks test as failed and continues execution if the first argument is not greater than the second argument.
• expect_le
  Marks test as failed and continues execution if the first argument is greater than the second argument.
• expect_lt
  Marks test as failed and continues execution if the first argument is greater or equal to second argument.
• expect_ne
  Marks test as failed and continues execution if the second argument is equal to first argument.
• expect_near
  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.
• expect_pred
  Asserts that the given predicate applied to the given arguments returns true, failing the test but continuing execution if not.
• expect_that
  Matches the given value against the given matcher, marking the test as failed but continuing execution if it does not match.
• expect_true
  Marks test as failed and continue execution if the expression evaluates to false.
• fail
  Evaluates to a Result which contains an Err variant with the given test failure message.
• succeed
  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.
• verify_eq
  Checks whether the second argument is equal to the first argument.
• verify_false
  Verify if the condition evaluates to false and returns Result.
• verify_float_eq
  Checks whether the float given by first argument is approximately equal to second argument.
• verify_ge
  Checks whether the first argument is greater than or equal to the second argument.
• verify_gt
  Checks whether the first argument is greater than the second argument.
• verify_le
  Checks whether the first argument is less than or equal to the second argument.
• verify_lt
  Checks whether the first argument is less than second argument.
• verify_ne
  Checks whether the second argument is not equal to the first argument.
• verify_near
  Checks whether the float given by first argument is equal to second argument with error tolerance of max_abs_error.
• verify_pred
  Asserts that the given predicate applied to the given arguments returns true.
• verify_that
  Checks whether the Matcher given by the second argument matches the first argument.
• verify_true
  Verify if the condition evaluates to true and returns Result.

Traits

• GoogleTestSupport
  Adds to Result support for GoogleTest Rust functionality.
• IntoTestResult
  Provides an extension method for converting an arbitrary type into a Result.

Functions

• verify_current_test_outcome
  Returns a Result corresponding to the outcome of the currently running test.

Type Aliases

• Result
  A Result whose Err variant indicates a test failure.

Attribute Macros

• test
  Marks a test to be run by the Google Rust test runner.