organicmaps/googletest
13
Fork 0
mirror of https://github.com/google/googletest.git synced 2025-04-07 06:25:01 +00:00
Code Issues 1 Projects Releases Wiki Activity Actions

Adds a section on using Boolean assertions with AssestionResult.

Browse source
This commit is contained in:
vladlosev 2009-11-12 08:18:10 +00:00
parent 2ec928098c
commit 4084a92d74
1 changed files with 139 additions and 43 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

182
wiki/GoogleTestAdvancedGuide.wiki
View file

@ -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
<pre>
!MutuallyPrime(b, c) is false, where
b is 4
c is 10
</pre>
*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:
<pre>
Value of: !IsEven(Fib(4))
Actual: false (*3 is odd*)
Expected: true
</pre>
instead of a more opaque
<pre>
Value of: !IsEven(Fib(4))
Actual: false
Expected: true
</pre>
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
<pre>
Value of: !IsEven(Fib(6))
Actual: true (8 is even)
Expected: false
</pre>
_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
<pre>
b and c (4 and 10) are not mutually prime, as they have a common divisor 2.
</pre>
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.