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.

Assertions and matchers

Most assertions are made through the macro verify_that!. 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 googletest::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).

For example, for fatal assertions:

use googletest::prelude::*;

#[test]
fn more_than_one_failure() -> Result<()> {
    let value = 2;
    verify_that!(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.

Matchers are composable:

use googletest::prelude::*;

#[test]
fn contains_at_least_one_item_at_least_3() -> Result<()> {
    let value = vec![1, 2, 3];
    verify_that!(value, contains(ge(3)))
}

They can also be logically combined:

use googletest::prelude::*;

#[test]
fn strictly_between_9_and_11() -> Result<()> {
    let value = 10;
    verify_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.
anything	Any input.
approx_eq	A floating point number within a standard tolerance of 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.
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.
eq_deref_of	A value equal to the dereferenced value of the argument.
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	Any Deref such as &, Rc, etc. whose value 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.
tuple!	A tuple whose elements the arguments match.
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 trait Matcher:

use googletest::matcher::{Matcher, MatcherResult};
use std::fmt::Debug;

struct MyEqMatcher<T> {
    expected: T,
}

impl<T: PartialEq + Debug> Matcher for MyEqMatcher<T> {
    type ActualT = T;

    fn matches(&self, actual: &Self::ActualT) -> MatcherResult {
        if self.expected == *actual {
            MatcherResult::Matches
        } else {
            MatcherResult::DoesNotMatch
        }
    }

    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:

pub fn eq_my_way<T: PartialEq + Debug>(expected: T) -> impl Matcher<ActualT = T> {
   MyEqMatcher { expected }
}

The new matcher can then be used in verify_that!:

#[test]
fn should_be_equal_by_my_definition() -> Result<()> {
    verify_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]. It must return [Result<()>].

use googletest::prelude::*;

#[googletest::test]
fn more_than_one_failure() -> Result<()> {
    let value = 2;
    expect_that!(value, eq(3));  // Just marks the test as having failed.
    verify_that!(value, eq(2))?;  // Passes, but the test already failed.
    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")
}

Modules

• assertions
• matcher
• 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

• all
  Matches a value which all of the given matchers match.
• assert_pred
  Asserts that the given predicate applied to the given arguments returns true, panicing if it does not.
• assert_that
  Matches the given value against the given matcher, panicing if it does not match.
• contains_each
  Matches a container containing elements matched by the given matchers.
• elements_are
  Matches a container’s elements to each matcher in order.
• 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.
• fail
  Evaluates to a Result which contains an Err variant with the given test failure message.
• field
  Matches a structure or enum with a given field which is matched by a given matcher.
• is_contained_in
  Matches a container all of whose elements are matched by the given matchers.
• matches_pattern
  Matches a value according to a pattern of matchers.
• pat
  An alias for matches_pattern.
• pointwise
  Generates a matcher which matches a container each of whose elements match the given matcher name applied respectively to each element of the given container.
• property
  Matches an object which, upon calling the given method on it with the given arguments, produces a value matched by the given inner matcher.
• tuple
  Matches a tuple whose elements are matched by each of the given matchers.
• unordered_elements_are
  Matches a container whose elements in any order have a 1:1 correspondence with the provided element matchers.
• 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.

Traits

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

Type Definitions

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

Attribute Macros

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