Breaking Changes

None

New Features

• Change NearMatcher to support references to the target type in #628

Bug Fixes

• Fix the parsing logic of matches_pattern! to support _ at the top level in top-level structs in #627
• Fix the parsing logic of matches_pattern! to support _ at the top level in braced enums in #634
• Fix Clippy warnings: variables can be used directly in the format! string in #639

Other Minor Changes

• Update documentation for expect_true, expect_false, assert_pred and expect_pred macros, which accept formatting args in #617
• Refactor and split similar tests in matches_pattern_test.rs to multiple files in #635

Full Changelog: v0.14.0...v0.14.1

Many thanks to @carlwhamilton, @kezhuw, @calder, @eopb for contributing to this release!

API Changes

• Rename into_test_result to or_fail (2720c76).

New Features

• Make matches_pattern support _ at the top level in tuple and braced structs (a1e9bac, 3d65dea).
• Make matches_pattern enforce exhaustive field checks for tuple and braced structs by default (https://sgithub.com/google/googletest-rust/commit/2ba098e02388d3fce91f445defb2e2f167898f10, 99bcfaa, a17b655).
• Add a container_eq(...).ignore_order() matcher (48ffd20).
• Add StrMatcher::ignoring_unicode_case (25322c8).
• Add support for the Bazel test sharing protocol (b8d251a, ef06f3f, cb8eaf9).
• Add is_finite and is_infinite matchers (9a6712c, 4e35e2c).
• Make googletest-rust usable from #![no_std] crates (7ca2fb5).
• Append generated test macro so that other test macros are aware of it (ee4996d).
• Improve the macro hygiene of expect_that! (1a6ef3d).
• Implement the Bazel TESTBRIDGE_TEST_ONLY protocol for test filtering with globs (a834f86, 43d5976, 8fa7024).
• Allow passing of failure messages and formatting arguments to expect_true!, expect_false!, assert_pred!, and expect_pred! (2986294, bbae567).

Bug Fixes

• Fix issue where macros do not compile without use googletest::prelude::*; by making calls between macros fully qualified (7a54871).
• Improve test hermeticity by calling Command::env_clear() in integration tests (b90142a).

Full Changelog: v0.13.0...v0.14.0

API Changes

• Note that the minimum supported Rust version has increased from 1.66 to 1.70.

• Rename #[googletest::test] to #[googletest::gtest] and add it to the prelude.

  Note that #[googletest::test] will not be deprecated because this spelling is useful for compatibility with the rstest crate.

• Add assert_pred! to prelude.

New Features

• Add test fixture support for synchronous tests.

  Various traits to represent different types of test fixtures have been added. The core Fixture trait may be used like this:

  struct MyFixture {...}
  
  impl Fixture for MyFixture {
      fn set_up() -> Result<MyFixture> {
          Ok(MyFixture {...})
      }
  
      fn tear_down(self) -> Result<()> {
          Ok(())
      }
  }
  
  #[googletest::test]
  fn test_with_fixture(my_fixture: &MyFixture) {...}
  

  ConsumableFixture has only a set_up method and no tear_down method.

  FixtureOf<T> adapts a T: Default into a ConsumableFixture.

  StaticFixture has a set_up_once method which is called only once before any tests are run.

• Add impl Matcher<&()> for ().

• Handle the printing of arguments passed to gtest macros that do not implement Debug using inherent method specialization.

• Generalize verify_pred! such that it can take any expression and provide meaningful output of intermediate values on failure.

• Add support for printing the two sides of a binary operator and traversing inside a unary operator in verify_pred!.

  For example, an assertion of the form verify_pred!(a == b) will print both the left and right-hand sides when it fails.

• Add support for sequences (ordered and unordered) to expect_that! and assert_that!.

• Add result_of! and result_of_ref! matchers for matching with a function applied to the value first.

  Example: verify_that!(100, result_of!(|value| value + 1, eq(101)))?; will pass.

• Add special cases to verify_eq! so that, when doing eq matching on sequences of tuple elements, the matcher applies tuple matching, distributing eq pointwise.

  This improves the ergonomics of tests that check for tuple contents, such as:

  let hash_map: std::collections::HashMap<String, String> =
      std::collections::HashMap::from([
          ("a".into(), "A".into()),
          ("b".into(), "B".into())]);
  verify_eq!(hash_map, {("a", "A"), ("b", "B")})

  because the matcher for &str is compatible with &String.

  The specialization applies on the inner structure; without it, the general matcher on tuples doesn't apply in the above case due to the definition of PartialEq on whole tuples, which is currently limited by rust-lang/rust#105092.

• Add is_true! and is_false! Boolean matchers.

Bug Fixes

• Fix #[gtest] failing to compile when a user-declared std or core module is in scope.

• Fix stack overflow that occurs when verify_pred! is used with nested function calls.

• Fix bug in summarize_diff where actual and expected strings were considered equal despite only one of the two ending in a newline character.

Full Changelog: v0.12.0...v0.13.0

Breaking changes

Matcher trait definition

The Matcher trait definition has changed:

Pre 0.12.0

pub trait Matcher {
    type ActualT: Debug + ?Sized;
    fn matches(&self, actual: &Self::ActualT) -> MatcherResult;
}

0.12.0

pub trait Matcher<ActualT: Debug + Copy> {
    fn matches(&self, actual: ActualT) -> MatcherResult;
}

This makes the trait implementation more generic in three ways:

• A single struct can implement Matcher for multiple types, since Actual is now a generic type parameter.
• ActualT can be passed as value if it implements Copy, which solved #351.
• When ActualT is a reference, the Matcher implementation can put constraint on its lifetime, which solved #323.

We tried to make sure this change had as limited an impact on users of the library as possible. Often, the library can be updated without changes on the tests. However, there are two areas requiring changes:

Matcher implementation

Obviously, libraries implementing their own matcher will need to update their implementation to match the new trait definition. For instance:

Pre 0.12.0

#[derive(Debug)]
enum MyEnum {
    ...
}

struct MyEnumMatcher { ... }

impl Matcher for MyEnumMatcher {
    type ActualT = MyEnumMatcher;

    fn matches(&self, actual: &Self::ActualT) -> MatcherResult {
        match actual {
            ...
        }
    }
}

will become:

#[derive(Debug)]
enum MyEnum {
    ...
}

#[derive(MatcherBase)]
struct MyEnumMatcher { ... }

impl Matcher<&MyEnum> for MyEnumMatcher {

    fn matches(&self, actual: &MyEnum) -> MatcherResult {
        match actual {
            ...
        }
    }
}

If MyEnum implements Copy, it is appropriate to also implement Matcher<MyEnum>.

MatcherBase is a super trait to Matcher which allow the usage of .and(...) and .or(...).

eq(...) often becomes eq(&...)

The eq(...) matcher now expects a type matching the actual reference-ness. In other words, you may get error:

no implementation for `&MyStruct == MyStruct`

for instance from a test like:

#[derive(Debug, PartialEq)]
struct MyStruct {...}
let actual = MyStruct {...};
let expected = MyStruct {...};
verify_that!(actual, eq(expected))

The issue is that actual is auto-ref to match the Copy bound from the matcher. However, verify_that! is not able to auto-ref expected which stays a MyStruct. The simple solution is to add a & before expected.

verify_that!(actual, eq(&expected))

Even if the snippet above compiles, it will look strange to the reader, as it seems to compare a MyStruct to a &MyStruct.

There are two solutions here:

• Add & to actual as well, since the auto-ref will detect that another & is not necessary. verify_that!(&actual, eq(&expected))
• Use verify_eq!() which supports auto-ref on both actual and expected. verify_eq!(actual, expected).

Changes to property! and matches_pattern!

Receiver reference-ness

property! and matches_pattern! now requires that the receiver must also be referenced in the declaration to match the method definition. In other words, fn method1(&self) -> ... requires matches_pattern!(&MyStruct { method1(): ....}) and property!(&MyStruct.method1(), ...).

Dereference not necessary

Previously, property! and matches_pattern! required to add a * to "dereference" the method returned value.

Pre 0.12.0

#[derive(Debug)]
struct MyStruct{
    field: Field
};

impl MyStruct{
    fn field(&self) -> &Field {&self.field}
}

verify_that!(MyStruct{...}, matches_pattern!(MyStruct{*field(): field_matcher()}))

In 0.12.0, this is not necessary nor supported

verify_that!(MyStruct{...}, matches_pattern!(&MyStruct{field(): field_matcher()}))

New features

expect_eq!(..., ...) and friends

GoogleTest now provides macros similar to assert_eq!() and friends with verify_ and expect_ behavior.

auto_eq

Most macro matchers now automatically inject eq() matchers if the parameters they are expecting does not implement Matcher.

For instance:

#[derive(Debug)]
struct MyStruct {
    field1: String,
    field2: String,
}

verify_that!(actual, matches_pattern!(MyStruct{field1: "field1", field2: "my field2"}))

Generalized .into_test_result()?

.into_test_result() now extends all std::result::Result and Option which simplifies error handling in test arrangements.

matches_pattern!(...) binding modes

matches_pattern!(...) now supports both move and reference binding modes, to be more consistent with Rust pattern matching.

For instance,

struct MyStruct {
    field1: String,
    field2: String
}
verify_that!(actual, matches_pattern!(MyStruct{field1: "something", field2: "else"}))
verify_that!(actual, matches_pattern!(&MyStruct{field1: ref "something", field2: ref "else"}))

This is useful, if you prefer to capture some fields by reference, with the ref keyword, and some by value (they would need to implement Copy).

Full Changelog: v0.11.0...v0.12.0

API Changes

• The Minimum Rust Supported Version was updated from 1.59 to 1.66

• The property! and matches_pattern! matchers use * instead of ref to handle properties returned by reference.
  For instance, to match the following structure:

  struct Strukt { a_field: i32 }
  impl Strukt {
    fn get_a_field(&self) -> &i32 {&self.a_field}
  }
  

  OLD:

  verify_that(Strukt{a_field: 123}, property!(ref Strukt.get_a_field(), eq(123))
  

  NEW:

  verify_that(Strukt{a_field: 123}, property!(*Strukt.get_a_field(), eq(123))
  

• Macro matchers are not exported on the top level anymore but exported in the googletest::matchers module as well as the googletest::prelude module.
  OLD:

  use googletest::elements_are;
  verify_that(vec![1,2,3], elements_are![1,2,3])
  

  NEW:

  use googletest::matchers::elements_are;
  verify_that(vec![1,2,3], elements_are![1,2,3])
  

• Matcher::explain_match and Matcher::describe now returns a Description instead of a String. Handling of wrapping matcher motivated this change and will make them simpler to write. For simple matchers, this change should be straightforward.
  OLD:

  impl Matcher for MyMatcher {
    ...
    fn explain_match(&self, actual: &Self::Actual) -> String {
      "explanation".to_string()
    }
    fn describe(&self) -> String {
      "description".to_string()
    }
  }
  

  NEW:

  impl Matcher for MyMatcher {
    ...
    fn explain_match(&self, actual: &Self::Actual) -> Description {
      "explanation".into()
    }
    fn describe(&self) -> Description {
      "description".into()
    }
  }
  

Other new features and improvements

• is_utf8_string(...) is a new matcher which matches a byte array with proper ut8 encoding.
• assert_that! and expect_that! accepts an error message as third argument, like assert_eq!(...).
• Trailing commas support in assert_that!, expect_that!, elements_are!, and unordered_elements_are!
• Diff summary will highlight the mismatching line with colors.
• #[should_panic] can be used with the #[googletest::test] macro.

Other minor changes

• When using eq(...) with different types (e.g. String and &str), the PartialEq relationship has been switched. See #334 for more details.
• Documentation fix in #299 and #332
• Add an extra whitespace between subsequent non-fatal failure messages.

Full Changelog: v0.10.0...v0.11.0

API Changes

None

Bug fixes

None

Other new features and improvements

• #290 Support test functions returning () with #[googletest::test]. This allows tests which only use expect_* macros to define an always Ok(()) return type.
• #270 Introduce a function verify_current_test_outcome.
• #279 Introduce a macro any! as a complement to the macro all!.

Other minor changes

• #275 Add support for using is_terminal and environment variables to determine whether to output ANSI colour sequences.
• #267 Do not rely on a color term crate to generate ANSI character.
• #271 Clarify the behaviour of fatal and non-fatal assertions in the documentation.
• #283 Reduce the visibility of most submodules of matchers.
• #295 Add docstrings for some elements which were missing it.

API Changes

• We eliminated the macro tuple! and implemented the Matcher trait directly for tuples of matchers. #260

  Previously, if one wanted to match against a tuple of matchers, one would use the tuple! macro. Now, one can construct a matcher just by taking a tuple of matchers. To port code, just remove the call to tuple!:

  OLD:

  verify_that!((1, 2), tuple!(eq(1), eq(2)))
  

  NEW:

  verify_that!((1, 2), (eq(1), eq(2)))
  

  If the tuple is a singleton, one must ensure that a trailing comma is present so that the Rust compiler recognises it as a tuple:

  OLD:

  verify_that!((1,), tuple!(eq(1)))
  

  NEW:

  verify_that!((1), (eq(1),))
  

• We renamed the variants of MatcherResult. #258

  We renamed the variants of the enum MatcherResult from Matches and DoesNotMatch to Match respectively NoMatch. The new names are more concise and work better linguistically.

  To port code, just use the new variants:

  OLD:

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

  NEW:

  fn matches(&self, actual: &Self::ActualT) -> MatcherResult {
      if condition {
          MatcherResult::Match
      } else {
          MatcherResult::NoMatch
      }
  }
  

  This should only affect developers who write their own matchers, not those using existing matchers.

• We renamed MatcherResult::into_bool to MatcherResult::is_match. This name is clearer and more in line with Rust idioms such as Result::is_ok and Result::is_err. #259

  let result = matcher.matches(&value);
  if result.into_bool() { ... }
  

  NEW:

  let result = matcher.matches(&value);
  if result.is_match() { ... }
  

  We have also added a corresponding method MatcherResult::is_no_match() which we recommend instead of negating the output of MatcherResult::is_match().

  This should only affect developers who write their own matchers, not those using existing matchers.

Bugfixes

• All test assertion failures -- fatal and nonfatal -- will now be output when using a mix of assertion types with the #[googletest::test] macro. Previously, when a fatal failure occurred after a non-fatal failure, only the non-fatal failure would be output to the console. #254

Other new features and improvements

• The diff of actual and expected values is now coloured, with extra lines from the actual value appearing in red and lines missing from the expected value appearing in green. The + and - characters are still present for the case that colours are not available or the reader of the output has colourblindness. There is also now an explanation of the output at the top of the diff. #232 #251

• The assertion failure message for matches_pattern! has been improved when matching enums with fields. It now indicates directly that the wrong enum variant was used rather than showing a confusing message about the field not being present. #245

  For example:

  enum AnEnum {
      A(u32), B(u32)
  }
  let actual = A(123);
  verify_that!(actual, matches_pattern!(AnEnum::B(eq(123))))
  

  Previous output:

  Value of: actual
  Expected: is AnEnum :: B which has field `0`, which is equal to 123
  Actual: A(123),
    which has no field `0`
  

  New output:

  Value of: actual
  Expected: is AnEnum :: B which has field `0`, which is equal to 123
  Actual: A(123),
    which has the wrong enum variant `A`
  

• There is new optional support to ease integration with the proptest crate for property-based testing. See the crate-level documentation for more information. #246

• The new matcher char_count matches string slices and owned strings with a given number of Unicode scalar values. It is analogous to len for containers. #247

  verify_that!("This string", char_count(gt(5)))
  

Other minor changes

• The description and match explanation of the len matcher now uses the word "length" rather than (the potentially misleading) "size".
• The output for test failures when using the #[googletest::test] attribute macro has been improved somewhat. Instead of outputting Error: (), the test harness will now output Error: See failure output above. #255

This release only ensures that the published crates googletest and googletest_macro each include a copy of the LICENSE file. It includes no other changes compared to version 0.8.0.

This change is needed to import the crates googletest and googletest_macro into the Android Open Source Project.