diff --git a/wiki/GoogleTestAdvancedGuide.wiki b/wiki/GoogleTestAdvancedGuide.wiki
index 7ba1f488..70743d90 100644
--- a/wiki/GoogleTestAdvancedGuide.wiki
+++ b/wiki/GoogleTestAdvancedGuide.wiki
@@ -70,7 +70,7 @@ EXPECT_NO_THROW({
_Availability_: Linux, Windows, Mac; since version 1.1.0.
-== Predicate Assertions ==
+== Predicate Assertions for Better Error Messages ==
Even though Google Test has a rich set of assertions, they can never be
complete, as it's impossible (nor a good idea) to anticipate all the scenarios
@@ -82,7 +82,14 @@ failure message by themselves, streaming it into `EXPECT_TRUE()`. However, this
is awkward especially when the expression has side-effects or is expensive to
evaluate.
-To solve this problem, we provide a family of generic _predicate assertions_:
+Google Test gives you three different options to solve this problem:
+
+=== Using an Existing Boolean Function ===
+
+If you already have a function or a functor that returns `bool` (or a type
+that can be implicitly converted to `bool`), you can use it in a _predicate
+assertion_ to get the function arguments printed for free:
+
|| *Fatal assertion* || *Nonfatal assertion* || *Verifies* ||
|| `ASSERT_PRED1(`_pred1, val1_`);` || `EXPECT_PRED1(`_pred1, val1_`);` || _pred1(val1)_ returns true ||
|| `ASSERT_PRED2(`_pred2, val1, val2_`);` || `EXPECT_PRED2(`_pred2, val1, val2_`);` || _pred2(val1, val2)_ returns true ||
@@ -90,13 +97,10 @@ To solve this problem, we provide a family of generic _predicate assertions_:
In the above, _predn_ is an _n_-ary predicate function or functor, where
_val1_, _val2_, ..., and _valn_ are its arguments. The assertion succeeds
-if the predicate returns true when applied on the given arguments, and fails
-otherwise. When the assertion fails, it prints the value of each arguments. In
+if the predicate returns `true` when applied to the given arguments, and fails
+otherwise. When the assertion fails, it prints the value of each argument. In
either case, the arguments are evaluated exactly once.
-Currently we only provide predicate assertions of arity <= 5. If you need a
-higher-arity assertion, let us know.
-
Here's an example. Given
{{{
@@ -110,26 +114,125 @@ const int c = 10;
the assertion `EXPECT_PRED2(MutuallyPrime, a, b);` will succeed, while the
assertion `EXPECT_PRED2(MutuallyPrime, b, c);` will fail with the message
+
+!MutuallyPrime(b, c) is false, where
+b is 4
+c is 10
+
+
+*Notes:*
+
+ # If you see a compiler error "no matching function to call" when using `ASSERT_PRED*` or `EXPECT_PRED*`, please see [GoogleTestFAQ#The_compiler_complains_%22no_matching_function_to_call%22 this] for how to resolve it.
+ # Currently we only provide predicate assertions of arity <= 5. If you need a higher-arity assertion, let us know.
+
+_Availability_: Linux, Windows, Mac
+
+=== Using a Funciton That Returns an !AssertionResult ===
+
+While `EXPECT_PRED*()` and friends are handy for a quick job, the
+syntax is not satisfactory: you have to use different macros for
+different arities, and it feels more like Lisp than C++. The
+`::testing::AssertionResult` class solves this problem.
+
+An `AssertionResult` object represents the result of an assertion
+(whether it's a success or a failure, and an associated message). You
+can create an `AssertionResult` using one of these factory
+functions:
+
{{{
-MutuallyPrime(b, c) is false,
-where
- b is 4
- c is 10
+namespace testing {
+
+// Returns an AssertionResult object to indicate that an assertion has
+// succeeded.
+AssertionResult AssertionSuccess();
+
+// Returns an AssertionResult object to indicate that an assertion has
+// failed.
+AssertionResult AssertionFailure();
+
+}
}}}
-If you find the default message generated by `(ASSERT|EXPECT)_PRED*` not
-satisfactory, or some arguments to your predicate do not support streaming to
-`ostream`, you can instead use the following assertions to customize how the
+You can then use the `<<` operator to stream messages to the
+`AssertionResult` object.
+
+To provide more readable messages in Boolean assertions
+(e.g. `EXPECT_TRUE()`), write a predicate function that returns
+`AssertionResult` instead of `bool`. For example, if you define
+`IsEven()` as:
+
+{{{
+::testing::AssertionResult IsEven(int n) {
+ if ((n % 2) == 0)
+ return ::testing::AssertionSuccess();
+ else
+ return ::testing::AssertionFailure() << n << " is odd";
+}
+}}}
+
+instead of:
+
+{{{
+bool IsEven(int n) {
+ return (n % 2) == 0;
+}
+}}}
+
+the failed assertion `EXPECT_TRUE(IsEven(Fib(4)))` will print:
+
+
+ Value of: !IsEven(Fib(4))
+ Actual: false (*3 is odd*)
+ Expected: true
+
+
+instead of a more opaque
+
+
+ Value of: !IsEven(Fib(4))
+ Actual: false
+ Expected: true
+
+
+If you want informative messages in `EXPECT_FALSE` and `ASSERT_FALSE`
+as well, and are fine with making the predicate slower in the success
+case, you can supply a success message:
+
+{{{
+::testing::AssertionResult IsEven(int n) {
+ if ((n % 2) == 0)
+ return ::testing::AssertionSuccess() << n << " is even";
+ else
+ return ::testing::AssertionFailure() << n << " is odd";
+}
+}}}
+
+Then the statement `EXPECT_FALSE(IsEven(Fib(6)))` will print
+
+
+ Value of: !IsEven(Fib(6))
+ Actual: true (8 is even)
+ Expected: false
+
+
+_Availability_: Linux, Windows, Mac; since version 1.4.1.
+
+=== Using a Predicate-Formatter ===
+
+If you find the default message generated by `(ASSERT|EXPECT)_PRED*` and
+`(ASSERT|EXPECT)_(TRUE|FALSE)` unsatisfactory, or some arguments to your
+predicate do not support streaming to `ostream`, you can instead use the
+following _predicate-formatter assertions_ to _fully_ customize how the
message is formatted:
|| *Fatal assertion* || *Nonfatal assertion* || *Verifies* ||
-|| `ASSERT_PRED_FORMAT1(`_pred_format1, val1_);` || `EXPECT_PRED_FORMAT1(`_pred_format1, val1_); || _pred_format1(val1)_ is successful ||
-|| `ASSERT_PRED_FORMAT2(`_pred_format2, val1, val2_`);` || `EXPECT_PRED_FORMAT2(`_pred_format2, val1, val2_); || _pred_format2(val1, val2)_ is successful ||
-|| ... || ... ||
+|| `ASSERT_PRED_FORMAT1(`_pred_format1, val1_`);` || `EXPECT_PRED_FORMAT1(`_pred_format1, val1_`); || _pred_format1(val1)_ is successful ||
+|| `ASSERT_PRED_FORMAT2(`_pred_format2, val1, val2_`);` || `EXPECT_PRED_FORMAT2(`_pred_format2, val1, val2_`);` || _pred_format2(val1, val2)_ is successful ||
+|| `...` || `...` || `...` ||
-The difference between this and the previous group of macros is that instead of
+The difference between this and the previous two groups of macros is that instead of
a predicate, `(ASSERT|EXPECT)_PRED_FORMAT*` take a _predicate-formatter_
-(_pred_formatn_), which is a function or functor that has the signature:
+(_pred_formatn_), which is a function or functor with the signature:
`::testing::AssertionResult PredicateFormattern(const char* `_expr1_`, const char* `_expr2_`, ... const char* `_exprn_`, T1 `_val1_`, T2 `_val2_`, ... Tn `_valn_`);`
@@ -144,20 +247,6 @@ A predicate-formatter returns a `::testing::AssertionResult` object to indicate
whether the assertion has succeeded or not. The only way to create such an
object is to call one of these factory functions:
-{{{
-namespace testing {
-
-// Returns an AssertionResult object to indicate that an assertion has
-// succeeded.
-AssertionResult AssertionSuccess();
-
-// Returns an AssertionResult object to indicate that an assertion has
-// failed with the given failure message.
-AssertionResult AssertionFailure(const Message& msg);
-
-} // namespace testing
-}}}
-
As an example, let's improve the failure message in the previous example, which uses `EXPECT_PRED2()`:
{{{
@@ -166,29 +255,36 @@ As an example, let's improve the failure message in the previous example, which
int SmallestPrimeCommonDivisor(int m, int n) { ... }
// A predicate-formatter for asserting that two integers are mutually prime.
-::testing::AssertionResult AssertMutuallyPrime(const char* m_expr, const char* n_expr, int m, int n) {
+::testing::AssertionResult AssertMutuallyPrime(const char* m_expr,
+ const char* n_expr,
+ int m,
+ int n) {
if (MutuallyPrime(m, n))
return ::testing::AssertionSuccess();
- ::testing::Message msg;
- msg << m_expr << " and " << n_expr << " (" << m << " and " << n
+
+ return ::testing::AssertionFailure()
+ << m_expr << " and " << n_expr << " (" << m << " and " << n
<< ") are not mutually prime, " << "as they have a common divisor "
<< SmallestPrimeCommonDivisor(m, n);
- return ::testing::AssertionFailure(msg);
}
}}}
With this predicate-formatter, we can use
-`EXPECT_PRED_FORMAT2(AssertMutuallyPrime, b, c);` to generate the message
-`b and c (4 and 10) are not mutually prime, as they have a common divisor 2.`
+
+{{{
+EXPECT_PRED_FORMAT2(AssertMutuallyPrime, b, c);
+}}}
+
+to generate the message
+
+
+b and c (4 and 10) are not mutually prime, as they have a common divisor 2.
+
As you may have realized, many of the assertions we introduced earlier are
special cases of `(EXPECT|ASSERT)_PRED_FORMAT*`. In fact, most of them are
indeed defined using `(EXPECT|ASSERT)_PRED_FORMAT*`.
-_Note:_ If you see a compiler error "no matching function to call" when using
-`ASSERT_PRED*` or `EXPECT_PRED*`, please see the GoogleTestFAQ for how to
-resolve it.
-
_Availability_: Linux, Windows, Mac.