Skip to content

GitLab

Commit d6ce39ed authored by Abseil Team's avatar Abseil Team Committed by Andy Getz
Browse files

Googletest export 

Create implementation macroses for matchers to move variadic parameters to the
end of parameters list.

To save backward compatibility, old macroses will be still taking `description`
parameter as the last one. But they will use INTERNAL macro that takes
`description` as the second parameter.

PiperOrigin-RevId: 291724469
parent 7413280c
Hide whitespace changes
Inline Side-by-side
Showing with 257 additions and 441 deletions
googlemock/include/gmock/gmock-generated-matchers.h
View file @ d6ce39ed
...@@ -47,220 +47,7 @@ ...@@ -47,220 +47,7 @@
#include <vector> #include <vector>
#include "gmock/gmock-matchers.h" #include "gmock/gmock-matchers.h"
// The MATCHER* family of macros can be used in a namespace scope to #define GMOCK_INTERNAL_MATCHER(name, description)\
// define custom matchers easily.
//
// Basic Usage
// ===========
//
// The syntax
//
// MATCHER(name, description_string) { statements; }
//
// defines a matcher with the given name that executes the statements,
// which must return a bool to indicate if the match succeeds. Inside
// the statements, you can refer to the value being matched by 'arg',
// and refer to its type by 'arg_type'.
//
// The description string documents what the matcher does, and is used
// to generate the failure message when the match fails. Since a
// MATCHER() is usually defined in a header file shared by multiple
// C++ source files, we require the description to be a C-string
// literal to avoid possible side effects. It can be empty, in which
// case we'll use the sequence of words in the matcher name as the
// description.
//
// For example:
//
// MATCHER(IsEven, "") { return (arg % 2) == 0; }
//
// allows you to write
//
// // Expects mock_foo.Bar(n) to be called where n is even.
// EXPECT_CALL(mock_foo, Bar(IsEven()));
//
// or,
//
// // Verifies that the value of some_expression is even.
// EXPECT_THAT(some_expression, IsEven());
//
// If the above assertion fails, it will print something like:
//
// Value of: some_expression
// Expected: is even
// Actual: 7
//
// where the description "is even" is automatically calculated from the
// matcher name IsEven.
//
// Argument Type
// =============
//
// Note that the type of the value being matched (arg_type) is
// determined by the context in which you use the matcher and is
// supplied to you by the compiler, so you don't need to worry about
// declaring it (nor can you). This allows the matcher to be
// polymorphic. For example, IsEven() can be used to match any type
// where the value of "(arg % 2) == 0" can be implicitly converted to
// a bool. In the "Bar(IsEven())" example above, if method Bar()
// takes an int, 'arg_type' will be int; if it takes an unsigned long,
// 'arg_type' will be unsigned long; and so on.
//
// Parameterizing Matchers
// =======================
//
// Sometimes you'll want to parameterize the matcher. For that you
// can use another macro:
//
// MATCHER_P(name, param_name, description_string) { statements; }
//
// For example:
//
// MATCHER_P(HasAbsoluteValue, value, "") { return abs(arg) == value; }
//
// will allow you to write:
//
// EXPECT_THAT(Blah("a"), HasAbsoluteValue(n));
//
// which may lead to this message (assuming n is 10):
//
// Value of: Blah("a")
// Expected: has absolute value 10
// Actual: -9
//
// Note that both the matcher description and its parameter are
// printed, making the message human-friendly.
//
// In the matcher definition body, you can write 'foo_type' to
// reference the type of a parameter named 'foo'. For example, in the
// body of MATCHER_P(HasAbsoluteValue, value) above, you can write
// 'value_type' to refer to the type of 'value'.
//
// We also provide MATCHER_P2, MATCHER_P3, ..., up to MATCHER_P10 to
// support multi-parameter matchers.
//
// Describing Parameterized Matchers
// =================================
//
// The last argument to MATCHER*() is a string-typed expression. The
// expression can reference all of the matcher's parameters and a
// special bool-typed variable named 'negation'. When 'negation' is
// false, the expression should evaluate to the matcher's description;
// otherwise it should evaluate to the description of the negation of
// the matcher. For example,
//
// using testing::PrintToString;
//
// MATCHER_P2(InClosedRange, low, hi,
// std::string(negation ? "is not" : "is") + " in range [" +
// PrintToString(low) + ", " + PrintToString(hi) + "]") {
// return low <= arg && arg <= hi;
// }
// ...
// EXPECT_THAT(3, InClosedRange(4, 6));
// EXPECT_THAT(3, Not(InClosedRange(2, 4)));
//
// would generate two failures that contain the text:
//
// Expected: is in range [4, 6]
// ...
// Expected: is not in range [2, 4]
//
// If you specify "" as the description, the failure message will
// contain the sequence of words in the matcher name followed by the
// parameter values printed as a tuple. For example,
//
// MATCHER_P2(InClosedRange, low, hi, "") { ... }
// ...
// EXPECT_THAT(3, InClosedRange(4, 6));
// EXPECT_THAT(3, Not(InClosedRange(2, 4)));
//
// would generate two failures that contain the text:
//
// Expected: in closed range (4, 6)
// ...
// Expected: not (in closed range (2, 4))
//
// Types of Matcher Parameters
// ===========================
//
// For the purpose of typing, you can view
//
// MATCHER_Pk(Foo, p1, ..., pk, description_string) { ... }
//
// as shorthand for
//
// template <typename p1_type, ..., typename pk_type>
// FooMatcherPk<p1_type, ..., pk_type>
// Foo(p1_type p1, ..., pk_type pk) { ... }
//
// When you write Foo(v1, ..., vk), the compiler infers the types of
// the parameters v1, ..., and vk for you. If you are not happy with
// the result of the type inference, you can specify the types by
// explicitly instantiating the template, as in Foo<long, bool>(5,
// false). As said earlier, you don't get to (or need to) specify
// 'arg_type' as that's determined by the context in which the matcher
// is used. You can assign the result of expression Foo(p1, ..., pk)
// to a variable of type FooMatcherPk<p1_type, ..., pk_type>. This
// can be useful when composing matchers.
//
// While you can instantiate a matcher template with reference types,
// passing the parameters by pointer usually makes your code more
// readable. If, however, you still want to pass a parameter by
// reference, be aware that in the failure message generated by the
// matcher you will see the value of the referenced object but not its
// address.
//
// Explaining Match Results
// ========================
//
// Sometimes the matcher description alone isn't enough to explain why
// the match has failed or succeeded. For example, when expecting a
// long string, it can be very helpful to also print the diff between
// the expected string and the actual one. To achieve that, you can
// optionally stream additional information to a special variable
// named result_listener, whose type is a pointer to class
// MatchResultListener:
//
// MATCHER_P(EqualsLongString, str, "") {
// if (arg == str) return true;
//
// *result_listener << "the difference: "
/// << DiffStrings(str, arg);
// return false;
// }
//
// Overloading Matchers
// ====================
//
// You can overload matchers with different numbers of parameters:
//
// MATCHER_P(Blah, a, description_string1) { ... }
// MATCHER_P2(Blah, a, b, description_string2) { ... }
//
// Caveats
// =======
//
// When defining a new matcher, you should also consider implementing
// MatcherInterface or using MakePolymorphicMatcher(). These
// approaches require more work than the MATCHER* macros, but also
// give you more control on the types of the value being matched and
// the matcher parameters, which may leads to better compiler error
// messages when the matcher is used wrong. They also allow
// overloading matchers based on parameter types (as opposed to just
// based on the number of parameters).
//
// MATCHER*() can only be used in a namespace scope as templates cannot be
// declared inside of a local class.
//
// More Information
// ================
//
// To learn more about using these macros, please search for 'MATCHER'
// on
// https://github.com/google/googletest/blob/master/googlemock/docs/cook_book.md
#define MATCHER(name, description)\
class name##Matcher : public \ class name##Matcher : public \
::testing::internal::MatcherBaseImpl<name##Matcher> {\ ::testing::internal::MatcherBaseImpl<name##Matcher> {\
using __internal_base_type = \ using __internal_base_type = \
...@@ -304,7 +91,7 @@ ...@@ -304,7 +91,7 @@
::testing::MatchResultListener* result_listener GTEST_ATTRIBUTE_UNUSED_)\ ::testing::MatchResultListener* result_listener GTEST_ATTRIBUTE_UNUSED_)\
const const
#define MATCHER_P(name, p0, description)\ #define GMOCK_INTERNAL_MATCHER_P(name, description, p0)\
template <typename p0##_type>\ template <typename p0##_type>\
class name##MatcherP : public \ class name##MatcherP : public \
::testing::internal::MatcherBaseImpl<name##MatcherP<p0##_type>> {\ ::testing::internal::MatcherBaseImpl<name##MatcherP<p0##_type>> {\
...@@ -352,7 +139,7 @@ ...@@ -352,7 +139,7 @@
::testing::MatchResultListener* result_listener GTEST_ATTRIBUTE_UNUSED_)\ ::testing::MatchResultListener* result_listener GTEST_ATTRIBUTE_UNUSED_)\
const const
#define MATCHER_P2(name, p0, p1, description)\ #define GMOCK_INTERNAL_MATCHER_P2(name, description, p0, p1)\
template <typename p0##_type, typename p1##_type>\ template <typename p0##_type, typename p1##_type>\
class name##MatcherP2 : public \ class name##MatcherP2 : public \
::testing::internal::MatcherBaseImpl<name##MatcherP2<p0##_type, \ ::testing::internal::MatcherBaseImpl<name##MatcherP2<p0##_type, \
...@@ -404,7 +191,7 @@ ...@@ -404,7 +191,7 @@
::testing::MatchResultListener* result_listener GTEST_ATTRIBUTE_UNUSED_)\ ::testing::MatchResultListener* result_listener GTEST_ATTRIBUTE_UNUSED_)\
const const
#define MATCHER_P3(name, p0, p1, p2, description)\ #define GMOCK_INTERNAL_MATCHER_P3(name, description, p0, p1, p2)\
template <typename p0##_type, typename p1##_type, typename p2##_type>\ template <typename p0##_type, typename p1##_type, typename p2##_type>\
class name##MatcherP3 : public \ class name##MatcherP3 : public \
::testing::internal::MatcherBaseImpl<name##MatcherP3<p0##_type, \ ::testing::internal::MatcherBaseImpl<name##MatcherP3<p0##_type, \
...@@ -458,7 +245,7 @@ ...@@ -458,7 +245,7 @@
::testing::MatchResultListener* result_listener GTEST_ATTRIBUTE_UNUSED_)\ ::testing::MatchResultListener* result_listener GTEST_ATTRIBUTE_UNUSED_)\
const const
#define MATCHER_P4(name, p0, p1, p2, p3, description)\ #define GMOCK_INTERNAL_MATCHER_P4(name, description, p0, p1, p2, p3)\
template <typename p0##_type, typename p1##_type, typename p2##_type, \ template <typename p0##_type, typename p1##_type, typename p2##_type, \
typename p3##_type>\ typename p3##_type>\
class name##MatcherP4 : public \ class name##MatcherP4 : public \
...@@ -520,7 +307,7 @@ ...@@ -520,7 +307,7 @@
::testing::MatchResultListener* result_listener GTEST_ATTRIBUTE_UNUSED_)\ ::testing::MatchResultListener* result_listener GTEST_ATTRIBUTE_UNUSED_)\
const const
#define MATCHER_P5(name, p0, p1, p2, p3, p4, description)\ #define GMOCK_INTERNAL_MATCHER_P5(name, description, p0, p1, p2, p3, p4)\
template <typename p0##_type, typename p1##_type, typename p2##_type, \ template <typename p0##_type, typename p1##_type, typename p2##_type, \
typename p3##_type, typename p4##_type>\ typename p3##_type, typename p4##_type>\
class name##MatcherP5 : public \ class name##MatcherP5 : public \
...@@ -584,7 +371,7 @@ ...@@ -584,7 +371,7 @@
::testing::MatchResultListener* result_listener GTEST_ATTRIBUTE_UNUSED_)\ ::testing::MatchResultListener* result_listener GTEST_ATTRIBUTE_UNUSED_)\
const const
#define MATCHER_P6(name, p0, p1, p2, p3, p4, p5, description)\ #define GMOCK_INTERNAL_MATCHER_P6(name, description, p0, p1, p2, p3, p4, p5)\
template <typename p0##_type, typename p1##_type, typename p2##_type, \ template <typename p0##_type, typename p1##_type, typename p2##_type, \
typename p3##_type, typename p4##_type, typename p5##_type>\ typename p3##_type, typename p4##_type, typename p5##_type>\
class name##MatcherP6 : public \ class name##MatcherP6 : public \
...@@ -649,7 +436,8 @@ ...@@ -649,7 +436,8 @@
::testing::MatchResultListener* result_listener GTEST_ATTRIBUTE_UNUSED_)\ ::testing::MatchResultListener* result_listener GTEST_ATTRIBUTE_UNUSED_)\
const const
#define MATCHER_P7(name, p0, p1, p2, p3, p4, p5, p6, description)\ #define GMOCK_INTERNAL_MATCHER_P7(name, description, p0, p1, p2, p3, p4, p5, \
p6)\
template <typename p0##_type, typename p1##_type, typename p2##_type, \ template <typename p0##_type, typename p1##_type, typename p2##_type, \
typename p3##_type, typename p4##_type, typename p5##_type, \ typename p3##_type, typename p4##_type, typename p5##_type, \
typename p6##_type>\ typename p6##_type>\
...@@ -722,7 +510,8 @@ ...@@ -722,7 +510,8 @@
::testing::MatchResultListener* result_listener GTEST_ATTRIBUTE_UNUSED_)\ ::testing::MatchResultListener* result_listener GTEST_ATTRIBUTE_UNUSED_)\
const const
#define MATCHER_P8(name, p0, p1, p2, p3, p4, p5, p6, p7, description)\ #define GMOCK_INTERNAL_MATCHER_P8(name, description, p0, p1, p2, p3, p4, p5, \
p6, p7)\
template <typename p0##_type, typename p1##_type, typename p2##_type, \ template <typename p0##_type, typename p1##_type, typename p2##_type, \
typename p3##_type, typename p4##_type, typename p5##_type, \ typename p3##_type, typename p4##_type, typename p5##_type, \
typename p6##_type, typename p7##_type>\ typename p6##_type, typename p7##_type>\
...@@ -799,7 +588,8 @@ ...@@ -799,7 +588,8 @@
::testing::MatchResultListener* result_listener GTEST_ATTRIBUTE_UNUSED_)\ ::testing::MatchResultListener* result_listener GTEST_ATTRIBUTE_UNUSED_)\
const const
#define MATCHER_P9(name, p0, p1, p2, p3, p4, p5, p6, p7, p8, description)\ #define GMOCK_INTERNAL_MATCHER_P9(name, description, p0, p1, p2, p3, p4, p5, \
p6, p7, p8)\
template <typename p0##_type, typename p1##_type, typename p2##_type, \ template <typename p0##_type, typename p1##_type, typename p2##_type, \
typename p3##_type, typename p4##_type, typename p5##_type, \ typename p3##_type, typename p4##_type, typename p5##_type, \
typename p6##_type, typename p7##_type, typename p8##_type>\ typename p6##_type, typename p7##_type, typename p8##_type>\
...@@ -879,7 +669,8 @@ ...@@ -879,7 +669,8 @@
::testing::MatchResultListener* result_listener GTEST_ATTRIBUTE_UNUSED_)\ ::testing::MatchResultListener* result_listener GTEST_ATTRIBUTE_UNUSED_)\
const const
#define MATCHER_P10(name, p0, p1, p2, p3, p4, p5, p6, p7, p8, p9, description)\ #define GMOCK_INTERNAL_MATCHER_P10(name, description, p0, p1, p2, p3, p4, p5, \
p6, p7, p8, p9)\
template <typename p0##_type, typename p1##_type, typename p2##_type, \ template <typename p0##_type, typename p1##_type, typename p2##_type, \
typename p3##_type, typename p4##_type, typename p5##_type, \ typename p3##_type, typename p4##_type, typename p5##_type, \
typename p6##_type, typename p7##_type, typename p8##_type, \ typename p6##_type, typename p7##_type, typename p8##_type, \
......
googlemock/include/gmock/gmock-generated-matchers.h.pump
View file @ d6ce39ed
...@@ -49,225 +49,12 @@ $$ }} This line fixes auto-indentation of the following code in Emacs. ...@@ -49,225 +49,12 @@ $$ }} This line fixes auto-indentation of the following code in Emacs.
#include <vector> #include <vector>
#include "gmock/gmock-matchers.h" #include "gmock/gmock-matchers.h"
// The MATCHER* family of macros can be used in a namespace scope to
// define custom matchers easily.
//
// Basic Usage
// ===========
//
// The syntax
//
// MATCHER(name, description_string) { statements; }
//
// defines a matcher with the given name that executes the statements,
// which must return a bool to indicate if the match succeeds. Inside
// the statements, you can refer to the value being matched by 'arg',
// and refer to its type by 'arg_type'.
//
// The description string documents what the matcher does, and is used
// to generate the failure message when the match fails. Since a
// MATCHER() is usually defined in a header file shared by multiple
// C++ source files, we require the description to be a C-string
// literal to avoid possible side effects. It can be empty, in which
// case we'll use the sequence of words in the matcher name as the
// description.
//
// For example:
//
// MATCHER(IsEven, "") { return (arg % 2) == 0; }
//
// allows you to write
//
// // Expects mock_foo.Bar(n) to be called where n is even.
// EXPECT_CALL(mock_foo, Bar(IsEven()));
//
// or,
//
// // Verifies that the value of some_expression is even.
// EXPECT_THAT(some_expression, IsEven());
//
// If the above assertion fails, it will print something like:
//
// Value of: some_expression
// Expected: is even
// Actual: 7
//
// where the description "is even" is automatically calculated from the
// matcher name IsEven.
//
// Argument Type
// =============
//
// Note that the type of the value being matched (arg_type) is
// determined by the context in which you use the matcher and is
// supplied to you by the compiler, so you don't need to worry about
// declaring it (nor can you). This allows the matcher to be
// polymorphic. For example, IsEven() can be used to match any type
// where the value of "(arg % 2) == 0" can be implicitly converted to
// a bool. In the "Bar(IsEven())" example above, if method Bar()
// takes an int, 'arg_type' will be int; if it takes an unsigned long,
// 'arg_type' will be unsigned long; and so on.
//
// Parameterizing Matchers
// =======================
//
// Sometimes you'll want to parameterize the matcher. For that you
// can use another macro:
//
// MATCHER_P(name, param_name, description_string) { statements; }
//
// For example:
//
// MATCHER_P(HasAbsoluteValue, value, "") { return abs(arg) == value; }
//
// will allow you to write:
//
// EXPECT_THAT(Blah("a"), HasAbsoluteValue(n));
//
// which may lead to this message (assuming n is 10):
//
// Value of: Blah("a")
// Expected: has absolute value 10
// Actual: -9
//
// Note that both the matcher description and its parameter are
// printed, making the message human-friendly.
//
// In the matcher definition body, you can write 'foo_type' to
// reference the type of a parameter named 'foo'. For example, in the
// body of MATCHER_P(HasAbsoluteValue, value) above, you can write
// 'value_type' to refer to the type of 'value'.
//
// We also provide MATCHER_P2, MATCHER_P3, ..., up to MATCHER_P$n to
// support multi-parameter matchers.
//
// Describing Parameterized Matchers
// =================================
//
// The last argument to MATCHER*() is a string-typed expression. The
// expression can reference all of the matcher's parameters and a
// special bool-typed variable named 'negation'. When 'negation' is
// false, the expression should evaluate to the matcher's description;
// otherwise it should evaluate to the description of the negation of
// the matcher. For example,
//
// using testing::PrintToString;
//
// MATCHER_P2(InClosedRange, low, hi,
// std::string(negation ? "is not" : "is") + " in range [" +
// PrintToString(low) + ", " + PrintToString(hi) + "]") {
// return low <= arg && arg <= hi;
// }
// ...
// EXPECT_THAT(3, InClosedRange(4, 6));
// EXPECT_THAT(3, Not(InClosedRange(2, 4)));
//
// would generate two failures that contain the text:
//
// Expected: is in range [4, 6]
// ...
// Expected: is not in range [2, 4]
//
// If you specify "" as the description, the failure message will
// contain the sequence of words in the matcher name followed by the
// parameter values printed as a tuple. For example,
//
// MATCHER_P2(InClosedRange, low, hi, "") { ... }
// ...
// EXPECT_THAT(3, InClosedRange(4, 6));
// EXPECT_THAT(3, Not(InClosedRange(2, 4)));
//
// would generate two failures that contain the text:
//
// Expected: in closed range (4, 6)
// ...
// Expected: not (in closed range (2, 4))
//
// Types of Matcher Parameters
// ===========================
//
// For the purpose of typing, you can view
//
// MATCHER_Pk(Foo, p1, ..., pk, description_string) { ... }
//
// as shorthand for
//
// template <typename p1_type, ..., typename pk_type>
// FooMatcherPk<p1_type, ..., pk_type>
// Foo(p1_type p1, ..., pk_type pk) { ... }
//
// When you write Foo(v1, ..., vk), the compiler infers the types of
// the parameters v1, ..., and vk for you. If you are not happy with
// the result of the type inference, you can specify the types by
// explicitly instantiating the template, as in Foo<long, bool>(5,
// false). As said earlier, you don't get to (or need to) specify
// 'arg_type' as that's determined by the context in which the matcher
// is used. You can assign the result of expression Foo(p1, ..., pk)
// to a variable of type FooMatcherPk<p1_type, ..., pk_type>. This
// can be useful when composing matchers.
//
// While you can instantiate a matcher template with reference types,
// passing the parameters by pointer usually makes your code more
// readable. If, however, you still want to pass a parameter by
// reference, be aware that in the failure message generated by the
// matcher you will see the value of the referenced object but not its
// address.
//
// Explaining Match Results
// ========================
//
// Sometimes the matcher description alone isn't enough to explain why
// the match has failed or succeeded. For example, when expecting a
// long string, it can be very helpful to also print the diff between
// the expected string and the actual one. To achieve that, you can
// optionally stream additional information to a special variable
// named result_listener, whose type is a pointer to class
// MatchResultListener:
//
// MATCHER_P(EqualsLongString, str, "") {
// if (arg == str) return true;
//
// *result_listener << "the difference: "
/// << DiffStrings(str, arg);
// return false;
// }
//
// Overloading Matchers
// ====================
//
// You can overload matchers with different numbers of parameters:
//
// MATCHER_P(Blah, a, description_string1) { ... }
// MATCHER_P2(Blah, a, b, description_string2) { ... }
//
// Caveats
// =======
//
// When defining a new matcher, you should also consider implementing
// MatcherInterface or using MakePolymorphicMatcher(). These
// approaches require more work than the MATCHER* macros, but also
// give you more control on the types of the value being matched and
// the matcher parameters, which may leads to better compiler error
// messages when the matcher is used wrong. They also allow
// overloading matchers based on parameter types (as opposed to just
// based on the number of parameters).
//
// MATCHER*() can only be used in a namespace scope as templates cannot be
// declared inside of a local class.
//
// More Information
// ================
//
// To learn more about using these macros, please search for 'MATCHER'
// on
// https://github.com/google/googletest/blob/master/googlemock/docs/cook_book.md
$range i 0..n $range i 0..n
$for i $for i
[[ [[
$var macro_name = [[$if i==0 [[MATCHER]] $elif i==1 [[MATCHER_P]] $var macro_name = [[$if i==0 [[GMOCK_INTERNAL_MATCHER]] $elif i==1 [[GMOCK_INTERNAL_MATCHER_P]]
$else [[MATCHER_P$i]]]] $else [[GMOCK_INTERNAL_MATCHER_P$i]]]]
$var class_name = [[name##Matcher[[$if i==0 [[]] $elif i==1 [[P]] $var class_name = [[name##Matcher[[$if i==0 [[]] $elif i==1 [[P]]
$else [[P$i]]]]]] $else [[P$i]]]]]]
$range j 0..i-1 $range j 0..i-1
...@@ -291,7 +78,7 @@ $var param_field_decls2 = [[$for j ...@@ -291,7 +78,7 @@ $var param_field_decls2 = [[$for j
p$j##_type const p$j;\ p$j##_type const p$j;\
]]]] ]]]]
#define $macro_name(name$for j [[, p$j]], description)\$template #define $macro_name(name, description$for j [[, p$j]])\$template
class $class_name : public ::testing::internal::MatcherBaseImpl<$class_name$param_types> {\ class $class_name : public ::testing::internal::MatcherBaseImpl<$class_name$param_types> {\
using __internal_base_type = ::testing::internal::MatcherBaseImpl<$class_name>;\ using __internal_base_type = ::testing::internal::MatcherBaseImpl<$class_name>;\
public:\ public:\
......
googlemock/include/gmock/gmock-matchers.h
View file @ d6ce39ed
...@@ -30,7 +30,220 @@ ...@@ -30,7 +30,220 @@
// Google Mock - a framework for writing C++ mock classes. // Google Mock - a framework for writing C++ mock classes.
// //
// This file implements some commonly used argument matchers. More // The MATCHER* family of macros can be used in a namespace scope to
// define custom matchers easily.
//
// Basic Usage
// ===========
//
// The syntax
//
// MATCHER(name, description_string) { statements; }
//
// defines a matcher with the given name that executes the statements,
// which must return a bool to indicate if the match succeeds. Inside
// the statements, you can refer to the value being matched by 'arg',
// and refer to its type by 'arg_type'.
//
// The description string documents what the matcher does, and is used
// to generate the failure message when the match fails. Since a
// MATCHER() is usually defined in a header file shared by multiple
// C++ source files, we require the description to be a C-string
// literal to avoid possible side effects. It can be empty, in which
// case we'll use the sequence of words in the matcher name as the
// description.
//
// For example:
//
// MATCHER(IsEven, "") { return (arg % 2) == 0; }
//
// allows you to write
//
// // Expects mock_foo.Bar(n) to be called where n is even.
// EXPECT_CALL(mock_foo, Bar(IsEven()));
//
// or,
//
// // Verifies that the value of some_expression is even.
// EXPECT_THAT(some_expression, IsEven());
//
// If the above assertion fails, it will print something like:
//
// Value of: some_expression
// Expected: is even
// Actual: 7
//
// where the description "is even" is automatically calculated from the
// matcher name IsEven.
//
// Argument Type
// =============
//
// Note that the type of the value being matched (arg_type) is
// determined by the context in which you use the matcher and is
// supplied to you by the compiler, so you don't need to worry about
// declaring it (nor can you). This allows the matcher to be
// polymorphic. For example, IsEven() can be used to match any type
// where the value of "(arg % 2) == 0" can be implicitly converted to
// a bool. In the "Bar(IsEven())" example above, if method Bar()
// takes an int, 'arg_type' will be int; if it takes an unsigned long,
// 'arg_type' will be unsigned long; and so on.
//
// Parameterizing Matchers
// =======================
//
// Sometimes you'll want to parameterize the matcher. For that you
// can use another macro:
//
// MATCHER_P(name, param_name, description_string) { statements; }
//
// For example:
//
// MATCHER_P(HasAbsoluteValue, value, "") { return abs(arg) == value; }
//
// will allow you to write:
//
// EXPECT_THAT(Blah("a"), HasAbsoluteValue(n));
//
// which may lead to this message (assuming n is 10):
//
// Value of: Blah("a")
// Expected: has absolute value 10
// Actual: -9
//
// Note that both the matcher description and its parameter are
// printed, making the message human-friendly.
//
// In the matcher definition body, you can write 'foo_type' to
// reference the type of a parameter named 'foo'. For example, in the
// body of MATCHER_P(HasAbsoluteValue, value) above, you can write
// 'value_type' to refer to the type of 'value'.
//
// We also provide MATCHER_P2, MATCHER_P3, ..., up to MATCHER_P$n to
// support multi-parameter matchers.
//
// Describing Parameterized Matchers
// =================================
//
// The last argument to MATCHER*() is a string-typed expression. The
// expression can reference all of the matcher's parameters and a
// special bool-typed variable named 'negation'. When 'negation' is
// false, the expression should evaluate to the matcher's description;
// otherwise it should evaluate to the description of the negation of
// the matcher. For example,
//
// using testing::PrintToString;
//
// MATCHER_P2(InClosedRange, low, hi,
// std::string(negation ? "is not" : "is") + " in range [" +
// PrintToString(low) + ", " + PrintToString(hi) + "]") {
// return low <= arg && arg <= hi;
// }
// ...
// EXPECT_THAT(3, InClosedRange(4, 6));
// EXPECT_THAT(3, Not(InClosedRange(2, 4)));
//
// would generate two failures that contain the text:
//
// Expected: is in range [4, 6]
// ...
// Expected: is not in range [2, 4]
//
// If you specify "" as the description, the failure message will
// contain the sequence of words in the matcher name followed by the
// parameter values printed as a tuple. For example,
//
// MATCHER_P2(InClosedRange, low, hi, "") { ... }
// ...
// EXPECT_THAT(3, InClosedRange(4, 6));
// EXPECT_THAT(3, Not(InClosedRange(2, 4)));
//
// would generate two failures that contain the text:
//
// Expected: in closed range (4, 6)
// ...
// Expected: not (in closed range (2, 4))
//
// Types of Matcher Parameters
// ===========================
//
// For the purpose of typing, you can view
//
// MATCHER_Pk(Foo, p1, ..., pk, description_string) { ... }
//
// as shorthand for
//
// template <typename p1_type, ..., typename pk_type>
// FooMatcherPk<p1_type, ..., pk_type>
// Foo(p1_type p1, ..., pk_type pk) { ... }
//
// When you write Foo(v1, ..., vk), the compiler infers the types of
// the parameters v1, ..., and vk for you. If you are not happy with
// the result of the type inference, you can specify the types by
// explicitly instantiating the template, as in Foo<long, bool>(5,
// false). As said earlier, you don't get to (or need to) specify
// 'arg_type' as that's determined by the context in which the matcher
// is used. You can assign the result of expression Foo(p1, ..., pk)
// to a variable of type FooMatcherPk<p1_type, ..., pk_type>. This
// can be useful when composing matchers.
//
// While you can instantiate a matcher template with reference types,
// passing the parameters by pointer usually makes your code more
// readable. If, however, you still want to pass a parameter by
// reference, be aware that in the failure message generated by the
// matcher you will see the value of the referenced object but not its
// address.
//
// Explaining Match Results
// ========================
//
// Sometimes the matcher description alone isn't enough to explain why
// the match has failed or succeeded. For example, when expecting a
// long string, it can be very helpful to also print the diff between
// the expected string and the actual one. To achieve that, you can
// optionally stream additional information to a special variable
// named result_listener, whose type is a pointer to class
// MatchResultListener:
//
// MATCHER_P(EqualsLongString, str, "") {
// if (arg == str) return true;
//
// *result_listener << "the difference: "
/// << DiffStrings(str, arg);
// return false;
// }
//
// Overloading Matchers
// ====================
//
// You can overload matchers with different numbers of parameters:
//
// MATCHER_P(Blah, a, description_string1) { ... }
// MATCHER_P2(Blah, a, b, description_string2) { ... }
//
// Caveats
// =======
//
// When defining a new matcher, you should also consider implementing
// MatcherInterface or using MakePolymorphicMatcher(). These
// approaches require more work than the MATCHER* macros, but also
// give you more control on the types of the value being matched and
// the matcher parameters, which may leads to better compiler error
// messages when the matcher is used wrong. They also allow
// overloading matchers based on parameter types (as opposed to just
// based on the number of parameters).
//
// MATCHER*() can only be used in a namespace scope as templates cannot be
// declared inside of a local class.
//
// More Information
// ================
//
// To learn more about using these macros, please search for 'MATCHER'
// on
// https://github.com/google/googletest/blob/master/googlemock/docs/cook_book.md
//
// This file also implements some commonly used argument matchers. More
// matchers can be defined by the user implementing the // matchers can be defined by the user implementing the
// MatcherInterface<T> interface if necessary. // MatcherInterface<T> interface if necessary.
// //
...@@ -4607,6 +4820,31 @@ PolymorphicMatcher<internal::variant_matcher::VariantMatcher<T> > VariantWith( ...@@ -4607,6 +4820,31 @@ PolymorphicMatcher<internal::variant_matcher::VariantMatcher<T> > VariantWith(
#define EXPECT_THAT(value, matcher) EXPECT_PRED_FORMAT1(\ #define EXPECT_THAT(value, matcher) EXPECT_PRED_FORMAT1(\
::testing::internal::MakePredicateFormatterFromMatcher(matcher), value) ::testing::internal::MakePredicateFormatterFromMatcher(matcher), value)
// MATCHER* macroses itself are listed below.
#define MATCHER(name, description) GMOCK_INTERNAL_MATCHER(name, description)
#define MATCHER_P(name, p0, description) \
GMOCK_INTERNAL_MATCHER_P(name, description, p0)
#define MATCHER_P2(name, p0, p1, description) \
GMOCK_INTERNAL_MATCHER_P2(name, description, p0, p1)
#define MATCHER_P3(name, p0, p1, p2, description) \
GMOCK_INTERNAL_MATCHER_P3(name, description, p0, p1, p2)
#define MATCHER_P4(name, p0, p1, p2, p3, description) \
GMOCK_INTERNAL_MATCHER_P4(name, description, p0, p1, p2, p3)
#define MATCHER_P5(name, p0, p1, p2, p3, p4, description) \
GMOCK_INTERNAL_MATCHER_P5(name, description, p0, p1, p2, p3, p4)
#define MATCHER_P6(name, p0, p1, p2, p3, p4, p5, description) \
GMOCK_INTERNAL_MATCHER_P6(name, description, p0, p1, p2, p3, p4, p5)
#define MATCHER_P7(name, p0, p1, p2, p3, p4, p5, p6, description) \
GMOCK_INTERNAL_MATCHER_P7(name, description, p0, p1, p2, p3, p4, p5, p6)
#define MATCHER_P8(name, p0, p1, p2, p3, p4, p5, p6, p7, description) \
GMOCK_INTERNAL_MATCHER_P8(name, description, p0, p1, p2, p3, p4, p5, p6, p7)
#define MATCHER_P9(name, p0, p1, p2, p3, p4, p5, p6, p7, p8, description) \
GMOCK_INTERNAL_MATCHER_P9(name, description, p0, p1, p2, p3, p4, p5, p6, p7, \
p8)
#define MATCHER_P10(name, p0, p1, p2, p3, p4, p5, p6, p7, p8, p9, description) \
GMOCK_INTERNAL_MATCHER_P10(name, description, p0, p1, p2, p3, p4, p5, p6, \
p7, p8, p9)
} // namespace testing } // namespace testing
GTEST_DISABLE_MSC_WARNINGS_POP_() // 4251 5046 GTEST_DISABLE_MSC_WARNINGS_POP_() // 4251 5046
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment