.. _cheatsheet:

========
チートシート
========
.. Google C++ Mocking Framework Cheat Sheet
*Google C++ Mocking Framework チートシート*

* :ref:`cheatsheet_defining_mock_class`

  * :ref:`cheatsheet_mocking_normal_class`
  * :ref:`cheatsheet_mocking_class_template`
  * :ref:`cheatsheet_specifying_calling_conventions_4mockfunctions`

* :ref:`cheatsheet_using_mocks_in_tests`
* :ref:`cheatsheet_setting_default_actions`
* :ref:`cheatsheet_setting_expectations`
* :ref:`cheatsheet_matchers`

  * :ref:`cheatsheet_wildcard`
  * :ref:`cheatsheet_generic_comparison`
  * :ref:`cheatsheet_floating-point_matchers`
  * :ref:`cheatsheet_string_matchers`
  * :ref:`cheatsheet_container_matchers`
  * :ref:`cheatsheet_member_matchers`
  * :ref:`cheatsheet_matching_the_result`
  * :ref:`cheatsheet_pointer_matchers`
  * :ref:`cheatsheet_multiargument_matchers`
  * :ref:`cheatsheet_composite_matchers`
  * :ref:`cheatsheet_adapters_for_matchers`
  * :ref:`cheatsheet_matchers_as_predicates`
  * :ref:`cheatsheet_defining_machers`
  * :ref:`cheatsheet_matchers_as_test_assertions`

* :ref:`cheatsheet_actions`

  * :ref:`cheatsheet_returning_value`
  * :ref:`cheatsheet_side_effects`
  * :ref:`cheatsheet_using_afunction_or_functor`
  * :ref:`cheatsheet_default_action`
  * :ref:`cheatsheet_compsite_actions`
  * :ref:`cheatsheet_defining_actions`

* :ref:`cheatsheet_cardinalities`
* :ref:`cheatsheet_expectation_order`

  * :ref:`cheatsheet_the_after_clause`
  * :ref:`cheatsheet_sequences`

* :ref:`cheatsheet_verifying_and_resetting_a_mock`
* :ref:`cheatsheet_mock_classes`
* :ref:`cheatsheet_flags`

.. Defining a Mock Class
.. _cheatsheet_defining_mock_class:

モッククラスを定義する
=================

.. Mocking a Normal Class
.. _cheatsheet_mocking_normal_class:

通常のクラスをモック化する
------------------------------

.. Given
以下のようなクラスが与えられた場合を考えます．

.. code-block:: c

  class Foo {
    ...
    virtual ~Foo();
    virtual int GetSize() const = 0;
    virtual string Describe(const char* name) = 0;
    virtual string Describe(int type) = 0;
    virtual bool Process(Bar elem, int count) = 0;
  };

.. (note that ~Foo() must be virtual) we can define its mock as
（~Foo() は必ず virtual であることに注意してください）これのモックは，次のように定義できます．

.. code-block:: c

  #include "gmock/gmock.h"
  
  class MockFoo : public Foo {
    MOCK_CONST_METHOD0(GetSize, int());
    MOCK_METHOD1(Describe, string(const char* name));
    MOCK_METHOD1(Describe, string(int type));
    MOCK_METHOD2(Process, bool(Bar elem, int count));
  };

.. To create a "nice" mock object which ignores all uninteresting calls, or a "strict" mock object, which treats them as failures:
不要な呼び出しを無視する「nice」モックオブジェクト，または，それらを失敗として扱う「strict」モックオブジェクト，を作るには次のようにします：

.. code-block:: c

  NiceMock<MockFoo> nice_foo;     // MockFoo の派生クラス型
  StrictMock<MockFoo> strict_foo;  // MockFoo の派生クラス型

.. Mocking a Class Template
.. _cheatsheet_mocking_class_template:

クラステンプレートをモック化する
---------------------------------------

.. To mock
次のクラステンプレートをモック化するには

.. code-block:: c

  template <typename Elem>
  class StackInterface {
   public:
    ...
    virtual ~StackInterface();
    virtual int GetSize() const = 0;
    virtual void Push(const Elem& x) = 0;
  };

.. (note that ~StackInterface() must be virtual) just append _T to the MOCK_* macros:
（~StackInterface() は必ず virtual であることに注意してください）MOCK_* マクロに _T を追加するだけです：

.. code-block:: c

  template <typename Elem>
  class MockStack : public StackInterface<Elem> {
   public:
    ...
    MOCK_CONST_METHOD0_T(GetSize, int());
    MOCK_METHOD1_T(Push, void(const Elem& x));
  };

.. Specifying Calling Conventions for Mock Functions
.. _cheatsheet_specifying_calling_conventions_4mockfunctions:

モック関数の呼び出し規約を指定する
-------------------------------------------

.. If your mock function doesn't use the default calling convention, you can specify it by appending _WITH_CALLTYPE to any of the macros described in the previous two sections and supplying the calling convention as the first argument to the macro. For example,
あなたのモック関数がデフォルトの呼び出し規約を利用しない場合，それを指定することができます．それには，前述の2つのセクションで説明したマクロすべてに _WITH_CALLTYPE を追加して，マクロの1番目の引数として呼び出し規約を与えます．次に例を示します．

.. code-block:: c

  MOCK_METHOD_1_WITH_CALLTYPE(STDMETHODCALLTYPE, Foo, bool(int n));
  MOCK_CONST_METHOD2_WITH_CALLTYPE(STDMETHODCALLTYPE, Bar, int(double x, double y));

.. where STDMETHODCALLTYPE is defined by <objbase.h> on Windows.
ここで STDMETHODCALLTYPE は，Windows の <objbase.h> で定義されています．

.. Using Mocks in Tests
.. _cheatsheet_using_mocks_in_tests:

モックをテストで利用する
==================

.. The typical flow is:
典型的な利用の流れは次のようになります：

.. Import the Google Mock names you need to use. All Google Mock names are in the testing namespace unless they are macros or otherwise noted.
.. Create the mock objects.
.. Optionally, set the default actions of the mock objects.
.. Set your expectations on the mock objects (How will they be called? What wil they do?).
.. Exercise code that uses the mock objects; if necessary, check the result using Google Test assertions.
.. When a mock objects is destructed, Google Mock automatically verifies that all expectations on it have been satisfied.
#. 利用する Google Mock の名前をインポートします．Google Mock 全ての名前は，マクロなどの例外を除いて testing 名前空間に存在します．
#. モックオブジェクトを作成します．
#. モックオブジェクトのデフォルト Action を設定します．これはオプションです．
#. モックオブジェクトに Expectation を設定します（どのように呼び出されるか？何をするのか？）
#. モックオブジェクトを利用するコードを実行します．必要ならば，Google Test アサーションを用いて結果をチェックしてください．
#. モックオブジェクトがデストラクトされると，その全ての Expectation が満足されたかどうかを Google Mock が自動的に検証します．

.. Here is an example:
以下に例を示します：

.. code-block:: c

  using ::testing::Return;                           // #1
  
  TEST(BarTest, DoesThis) {
    MockFoo foo;                                    // #2
  
    ON_CALL(foo, GetSize())                         // #3
        .WillByDefault(Return(1));
    // ... その他のデフォルト Action ...
  
    EXPECT_CALL(foo, Describe(5))                   // #4
        .Times(3)
        .WillRepeatedly(Return("Category 5"));
    // ... その他の Expectation ...
  
    EXPECT_EQ("good", MyProductionFunction(&foo));  // #5
  }                                                 // #6

.. Setting Default Actions
.. _cheatsheet_setting_default_actions:

デフォルトの Action を定義する
=========================

.. Google Mock has a built-in default action for any function that returns void, bool, a numeric value, or a pointer.
void，bool，数値，ポインタを返す関数に対しては，Google Mock 組み込みのデフォルト Action があります．

.. To customize the default action for functions with return type T globally:
戻り値型 T の関数のデフォルト Action を全体的にカスタマイズするには，次のようにします：

.. code-block:: c

  using ::testing::DefaultValue;
  
  DefaultValue<T>::Set(value);  // 返されるデフォルト値を設定します．
  // ... モックを利用します ...
  DefaultValue<T>::Clear();     // デフォルト値をリセットします．

.. To customize the default action for a particular method, use ON_CALL():
特定のメソッドのデフォルト Action をカスタマイズするには，ON_CALL() を利用します：

.. code-block:: c
  
  ON_CALL(mock_object, method(matchers))
      .With(multi_argument_matcher)  ?
      .WillByDefault(action);

.. Setting Expectations
.. _cheatsheet_setting_expectations:

Expectation を設定する
=================

.. EXPECT_CALL() sets expectations on a mock method (How will it be called? What will it do?):
EXPECT_CALL()  は，モックメソッドに Expectation を設定します（どのように呼び出されるか？何をするのか？）

.. code-block:: c

  EXPECT_CALL(mock_object, method(matchers))
      .With(multi_argument_matcher)  ?
      .Times(cardinality)            ?
      .InSequence(sequences)         *
      .After(expectations)           *
      .WillOnce(action)              *
      .WillRepeatedly(action)        ?
      .RetiresOnSaturation();        ?

.. If Times() is omitted, the cardinality is assumed to be:
Times() が省略された場合，cardinality は次のように仮定されます：

.. Times(1) when there is neither WillOnce() nor WillRepeatedly();
.. Times(n) when there are n WillOnce()s but no WillRepeatedly(), where n >= 1; or
.. Times(AtLeast(n)) when there are n WillOnce()s and a WillRepeatedly(), where n >= 0.
* WillOnce() も WillRepeatedly() もない場合，Times(1)．
* WillOnce() が n 個あり，WillRepeatedly() がない場合，Times(n)．ただし， n >= 1．
* WillOnce() が n 個あり，WillRepeatedly() が 1 個ある場合，Times(AtLeast(n))．ただし， n >= 0．

.. A method with no EXPECT_CALL() is free to be invoked any number of times, and the default action will be taken each time.
EXPECT_CALL() がないメソッドは，何度でも自由に呼び出され，そのたびにデフォルトアクションが実行されます．

.. Matchers
.. _cheatsheet_matchers:

Matchers
=========

.. A matcher matches a single argument. You can use it inside ON_CALL() or EXPECT_CALL(), or use it to validate a value directly:
matcher は，単一の引数にマッチします．これは，ON_CALL() または EXPECT_CALL() 内で利用したり，また値を直接検証するために利用することができます．．

.. csv-table::
  :header:
  :widths: 10,30

  "EXPECT_THAT(value, matcher)", "value が matcher にマッチすることをアサートします．"
  "ASSERT_THAT(value, matcher)", "致命的な失敗を生成することを除いて，EXPECT_THAT(value, matcher) と同じです．"

.. Built-in matchers (where argument is the function argument) are divided into several categories:
組み込みの matcher （argument は関数の引数）は，いくつかのカテゴリに分類されます．

.. Wildcard
.. _cheatsheet_wildcard:

ワイルドカード
-----------------------

.. csv-table::
  :header:
  :widths: 10,30

  "_", "argument は，正しい型の任意の値をとれます．"
  "A<type>() or An<type>()", "argument は，type 型の任意の値をとれます．"

.. Generic Comparison
.. _cheatsheet_generic_comparison:

一般的な比較
-----------------------

.. csv-table::
  :header:
  :widths: 9,55

  "Eq(value) または value", "argument == value"
  "Ge(value)", "argument >= value"
  "Gt(value)", "argument > value"
  "Le(value)", "argument <= value"
  "Lt(value)", "argument < value"
  "Ne(value)", "argument != value"
  "IsNull()", "argument は NULL ポインタ（生ポインタ，またはスマートポインタ）．"
  "NotNull()", "argument は NULL ポインタではない（生ポインタ，またはスマートポインタ）．"
  "Ref(variable)", "argument は variable の参照．"
  "TypedEq<type>(value)", "argument の type 型で，value に等しい．モック関数がオーバーロードされた場合，Eq(value) の代わりにこれを使う必要があるかもしれません．"

.. Except Ref(), these matchers make a copy of value in case it's modified or destructed later. If the compiler complains that value doesn't have a public copy constructor, try wrap it in ByRef(), e.g. Eq(ByRef(non_copyable_value)). If you do that, make sure non_copyable_value is not changed afterwards, or the meaning of your matcher will be changed.
Ref() を除いて，これらの matcher は，後から変更したり破棄したりするのに備えて value のコピーを作ります．コンパイラが value が public なコピーコンストラクタを持っていないというエラーを出した場合，例えば，Eq(ByRef(non_copyable_value)) というように ByRef() でラップしてみてくださいこれを使う場合，non_copyable_value を後から変更したり，あなたの定義した matcher の意味を変更したり，決してしないようにしてください．

.. Floating-Point Matchers
.. _cheatsheet_floating-point_matchers:

浮動小数点 Matcher
--------------------------

.. csv-table::
  :header:
  :widths: 10,30

  "DoubleEq(a_double)", "argument は，a_double とおよそ等しい double 型の値．2つの NaN は等しくないとされます．"
  "FloatEq(a_float)", "argument は，a_float とおよそ等しい float 型の値．2つの NaN は等しくないとされます．"
  "NanSensitiveDoubleEq(a_double)", "argument は，a_double とおよそ等しい double 型の値．2つの NaN は等しいとされます．"
  "NanSensitiveFloatEq(a_float)", "argument は，a_float とおよそ等しい float 型の値．2つの NaN は等しいとされます．"

.. These matchers use ULP-based comparison (the same as used in Google Test). They automatically pick a reasonable error bound based on the absolute value of the expected value. DoubleEq() and FloatEq() conform to the IEEE standard, which requires comparing two NaNs for equality to return false. The NanSensitive* version instead treats two NaNs as equal, which is often what a user wants.
これらの matcher は，（Google Test で利用されているものと同様に）ULP に基づいた比較を行います．ここでは，期待する値の絶対値に基づいた適切な誤差範囲が自動的に利用されます．DoubleEq() と FloatEq() は IEEE 標準に従い，NaN 同士の等価性を評価した場合に false を返します．NanSensitive* バージョンは，2つの NaN を等しい値として扱います．この動作を望むユーザも多いでしょう．

.. String Matchers
.. _cheatsheet_string_matchers:

文字列 Matcher
--------------------

.. The argument can be either a C string or a C++ string object:
argument は C 文字列，または C++ string オブジェクトのどちらでも利用できます．

.. csv-table::
  :header:
  :widths: 10, 33

  "ContainsRegex(string)", "argument は，与えられた正規表現にマッチします．"
  "EndsWith(suffix)", "argument の末尾が，文字列 suffix です．"
  "HasSubstr(string)", "argument が，その部分文字列として string を含みます．"
  "MatchesRegex(string)", "argument の先頭から末尾までが，与えられた正規表現にマッチします．"
  "StartsWith(prefix)", "argument の先頭が，文字列 prefix です．"
  "StrCaseEq(string)", "argument は，string に等しい．大文字小文字は無視されます．"
  "StrCaseNe(string)", "argument は，string に等しくない．大文字小文字は無視されます．"
  "StrEq(string)", "argument は，string と等しい．"
  "StrNe(string)", "argument は，string と等しくない．"

.. StrCaseEq(), StrCaseNe(), StrEq(), and StrNe() work for wide strings as well.
StrCaseEq() ，StrCaseNe() ，StrEq() ，StrNe() は，ワイド文字列に対しても動作します．

.. Container Matchers
.. _cheatsheet_container_matchers:

コンテナ Matcher
------------------------

.. Most STL-style containers support ==, so you can use Eq(expected_container) or simply expected_container to match a container exactly. If you want to write the elements in-line, match them more flexibly, or get more informative messages, you can use:
STL スタイルのコンテナの多くは == をサポートしています．よって，Eq(expected_container) または単に expected_container を使えば，正確にコンテナにマッチすることができます．しかし，要素をインラインで書きたい，より柔軟にマッチさせたい，メッセージを充実させたい，など場合は，以下を利用できます：

.. csv-table::
  :header:
  :widths: 10, 50

  "Contains(e)", "argument は，e （値または matcher）にマッチする要素を含みます．"
  "Each(e)", "argument は，すべての要素が e （値または matcher）にマッチするコンテナです．"
  "ElementsAre(e0, e1, ..., en)", "argument は，n + 1 個の要素を持ち，i-番目の要素は ei （値または matcher）にマッチします．0 から 10 までの引数をとれます．"
  "ElementsAreArray(array) または ElementsAreArray(array, count)", "期待する要素の値/matcher がC形式の配列で表現されることを除いて，ElementsAre() と同じです．"
  "ContainerEq(container)", "失敗メッセージにも片方のコンテナだけに存在する要素が表示される点を除いて，Eq(container) と同じです．"
  "Pointwise(m, container)", "argument は，container と同数の要素を持ち，全ての i に対して（argument の i-番目の要素，container の i-番目の要素が）m にマッチします．ここで ｍ は，2要素タプル形式の matcher です．例えば Pointwise(Le(), upper_bounds) は，argument の各要素が，対応する upper_bounds の要素を超えないかどうかを検証します．"

.. These matchers can also match:
これらの matcher は，次のようなものにもマッチします：

.. a native array passed by reference (e.g. in Foo(const int (&a)[5])), and
.. an array passed as a pointer and a count (e.g. in Bar(const T* buffer, int len) -- see Multi-argument Matchers).
#. 参照渡しされたネイティブな配列（例えば， Foo(const int (&a)[5]) ）
#. ポインタと長さで渡された配列（例えば， Bar(const T* buffer, int len) -- :ref:`cheatsheet_multiargument_matchers` を参照してください．

.. where the array may be multi-dimensional (i.e. its elements can be arrays).
ここで，配列は多次元配列（例えば，要素が配列）でも構いません．



.. Member Matchers
.. _cheatsheet_member_matchers:

メンバ Matcher
-----------------------

.. csv-table::
  :header:
  :widths: 9, 45

  "Field(&class::field, m)", "argument.field（argument がただのポインタの場合は argument->field ）は，matcher m にマッチします．ここで，argument は class 型のオブジェクトです．"
  "Key(e)", "argument.first は，e （値または matcher）にマッチします．例えば，Contains(Key(Le(5))) は，マップに key <=5 が含まれていることを検証します．"
  "Pair(m1, m2)", "argument は，1番目のフィールドが m1 に， 2番目のフィールドが m2 にマッチする std::pair です．"
  "Property(&class::property, m)", "argument.property() （argument がただのポインタの場合は argument->property() ）は，matcer m にマッチします．ここで，argument は class 型のオブジェクトです．"

.. Matching the Result of a Function or Functor
.. _cheatsheet_matching_the_result:

関数またはファンクタの結果のマッチング
----------------------------------------------

.. csv-table::
  :header:
  :widths: 5, 30

  "ResultOf(f, m)", "f(argument) は，matcher にマッチします．ここで f は関数またはファンクタです．"

.. Pointer Matchers
.. _cheatsheet_pointer_matchers:

ポインタ Matcher
-----------------------

.. csv-table::
  :header:
  :widths: 5, 40

  "Pointee(m)", "argument （スマートポンタ，または生ポインタ）が指し示す値は，matcher m にマッチします．"

.. Multiargument Matchers
.. _cheatsheet_multiargument_matchers:

複数の引数をとる Matcher
----------------------------------

.. Technically, all matchers match a single value. A "multi-argument" matcher is just one that matches a tuple. The following matchers can be used to match a tuple (x, y):
理論的には，すべての matcher は単一の値にマッチします．「複数の引数をとる」 matcher は，単にタプルにマッチする matcher です．以下の matcher は，タプル (x, y) にマッチさせるために利用できます：

.. csv-table::
  :header:
  :widths: 10, 15

  "Eq()", "x == y"
  "Ge()", "x >= y"
  "Gt()", "x > y"
  "Le()", "x <= y"
  "Lt()", "x < y"
  "Ne()", "x != y"

.. You can use the following selectors to pick a subset of the arguments (or reorder them) to participate in the matching:
以下のセレクタを利用すると，引数の一部を抜き出し（または，順番を入れ替え）て，マッチングさせることができます

.. csv-table::
  :header:
  :widths: 10, 30

  "AllArgs(m)", "m と等価です．.With(AllArgs(m)) のシンタックスシュガーとして役立ちます．"
  "Args<N1, N2, ..., Nk>(m)", "（0基準のインデックスによって） k 要素のタプルが引数から選択され，それが m にマッチします．例えば， Args<1, 2>(Eq())．"

.. Composite Matchers
.. _cheatsheet_composite_matchers:

複合 Matcher
--------------------

.. You can make a matcher from one or more other matchers:
1つまたは複数の matcher から， 新たに別の matcher を作ることができます．

.. csv-table::
  :header:
  :widths: 10, 20

  "AllOf(m1, m2, ..., mn)", "argument は，m1 から mn までの全ての matcher にマッチします．"
  "AnyOf(m1, m2, ..., mn)", "argument は，m1 から mn までの matcher のうち，少なくとも1つにマッチします．"
  "Not(m)", "argument は，matcher m にマッチしません．"

.. Adapters for Matchers
.. _cheatsheet_adapters_for_matchers:

Matcher のアダプタ
--------------------------

.. csv-table::
  :header:
  :widths: 10, 30

  "MatcherCast<T>(m)", "matcher m を，型 Matcher<T> にキャストします．"
  "SafeMatcherCast<T>(m)", "matcher m を，型 Matcher<T> に安全にキャストします．"
  "Truly(predicate)", "predicate(argument) は，C++ で true と判断されるなにかを返します．predicate は，関数またはファンクタです．"

.. Matchers as Predicates
.. _cheatsheet_matchers_as_predicates:

述語関数としての Matcher
-------------------------------

.. csv-table::
  :header:
  :widths: 15, 30

  "Matches(m)", "argument が m にマッチする場合に true を返す，1変数関数です．"
  "ExplainMatchResult(m, value, result_listener)", "value が m にマッチする場合に true を返し，その結果を result_listener に説明します．"
  "Value(x, m)", "x の値が m にマッチする場合に true を返します．"

.. Defining Matchers
.. _cheatsheet_defining_machers:

Matcher を定義する
---------------------------

.. csv-table::
  :header:
  :widths: 35 20

  "MATCHER(IsEven, """") { return (arg % 2) == 0; }", "偶数にマッチする matcher IsEven() を定義します．"
  "MATCHER_P(IsDivisibleBy, n, """") { *result_listener << ""where the remainder is "" << (arg % n); return (arg % n) == 0; }", "n の倍数にマッチする matcher IsDivisibleBy(n) を定義します．"
  "MATCHER_P2(IsBetween, a, b, std::string(negation ? ""isn't"" : ""is"") + "" between "" + PrintToString(a) + "" and "" + PrintToString(b)) { return a <= arg && arg <= b; }", "[a, b] の範囲内の値にマッチする matcher IsBetween(a, b) を定義します．"

.. Notes:
**注意：**

.. The MATCHER* macros cannot be used inside a function or class.
.. The matcher body must be purely functional (i.e. it cannot have any side effect, and the result must not depend on anything other than the value being matched and the matcher parameters).
.. You can use PrintToString(x) to convert a value x of any type to a string.
#. MATCHER* マクロは，関数やクラスの内部では利用できません．
#. matcher 本体は，純関数的である必要があります（つまり，いかなる副作用もなく，マッチさせる値と matcher のパラメータだけで結果が決まります）．
#. PrintToString(x) を利用して，任意の型の値 x を文字列に変換することができます．

.. Matchers as Test Assertions
.. _cheatsheet_matchers_as_test_assertions:

テストアサーションとしての Matcher
-------------------------------------------------

.. csv-table::
  :header:
  :widths: 10, 25

  "ASSERT_THAT(expression, m)", "expression の値が matcher m にマッチしなかった場合に，致命的な失敗を生成します．"
  "EXPECT_THAT(expression, m)", "expression の値が matcher m にマッチしなかった場合に，致命的ではない失敗を生成します．"

.. Actions
.. _cheatsheet_actions:

Actions
=======

.. Actions specify what a mock function should do when invoked.
Action は，モック関数が呼ばれたときに何をするのかを規定します．

.. Returning a Value
.. _cheatsheet_returning_value:

値を返す
-----------------

.. csv-table::
  :header:
  :widths: 10, 50

  "Return()", "void モック関数から返ります．"
  "Return(value)", "value を返します．value の型がモック関数の戻り値型と異なる場合，value の型が変換されます．これは，Action 実行時ではなく，Expectation が設定されるときに行われます．"
  "ReturnArg<N>()", "N-番目（0基準）の argument を返します．"
  "ReturnNew<T>(a1, ..., ak)", "new T(a1, ..., ak); を返します．毎回異なるオブジェクトが作成されます．"
  "ReturnNull()", "Null ポインタを返します．"
  "ReturnPointee(ptr)", "ptr で指定される値を返します．"
  "ReturnRef(variable)", "variable の参照を返します．"
  "ReturnRefOfCopy(value)", "value のコピーの参照を返します．このコピーは，Action 時にのみ有効です．"

.. Side Effects
.. _cheatsheet_side_effects:

副作用
----------

.. csv-table::
  :header:
  :widths: 10, 50

  "Assign(&variable, value)", "value を variable に代入します．"
  "DeleteArg<N>()", "N-番目（0基準）の argument を削除します．これはポインタである必要があります．"
  "SaveArg<N>(pointer)", "N-番目（0基準）の argument を *pointer に保存します．"
  "SaveArgPointee<N>(pointer)", "N-番目（0基準）の argument によって指される値を *pointer に保存します．"
  "SetArgReferee<N>(value)", "N-番目（0基準）の argument によって参照される変数に，value を代入します．"
  "SetArgPointee<N>(value)", "N-番目（0基準）の argument によって指される変数に，value を代入します．"
  "SetArgumentPointee<N>(value)", "SetArgPointee<N>(value) と同じです．非推奨．v1.7.0 で廃止予定です．"
  "SetArrayArgument<N>(first, last)", "入力範囲 [first, last) の要素を，N-番目（0基準）の argument （これは，ポインタまたはイテレータ）によって指される配列にコピーします．Action は，入力範囲内の要素の所有権を持ちません．"
  "SetErrnoAndReturn(error, value)", "error にエラー番号を設定して，value を返します．"
  "Throw(exception)", "与えられた exception を投げます．これは任意のコピー可能な値です．v1.1.0 以降で利用できます．"

.. Using a Function or a Functor as an Action
.. _cheatsheet_using_afunction_or_functor:

関数またはファンクタを Action として利用する
-------------------------------------------------------

.. csv-table::
  :header:
  :widths: 10, 50

  "Invoke(f)", "モック関数に渡された argument を与えて f を呼び出します．ここで f は，グローバルで static な関数またはファンクタです．"
  "Invoke(object_pointer, &class::method)", "モック関数に渡された argument を与えてオブジェクトの method を呼び出します．"
  "InvokeWithoutArgs(f)", "f を呼び出します．ここで f は，グローバルで static な関数またはファンクタです．また，f は引数をとってはいけません．"
  "InvokeWithoutArgs(object_pointer, &class::method)", "オブジェクトの，引数を取らない method を呼び出します"
  "InvokeArgument<N>(arg1, arg2, ..., argk)", "モック関数のN-番目（0基準）の argument を呼び出します．これは k この引数をとる，関数またはファンクタである必要があります．"

.. The return value of the invoked function is used as the return value of the action.
呼び出された関数の戻り値は，Action の戻り値として利用されます．

.. When defining a function or functor to be used with Invoke*(), you can declare any unused parameters as Unused:
Invoke*() で利用される関数またはファンクタを定義する際，利用しない任意のパラメータを Unused として宣言することができます：

.. code-block:: c

  double Distance(Unused, double x, double y) { return sqrt(x*x + y*y); }
  ...
  EXPECT_CALL(mock, Foo("Hi", _, _)).WillOnce(Invoke(Distance));

.. In InvokeArgument<N>(...), if an argument needs to be passed by reference, wrap it inside ByRef(). For example,
InvokeArgument<N>(...) で，引数を参照渡しする必要があるならば，ByRef() でラップしてください．例えば：

.. code-block:: c

  InvokeArgument<2>(5, string("Hi"), ByRef(foo))

.. calls the mock function's #2 argument, passing to it 5 and string("Hi") by value, and foo by reference.
モック関数の2番目の argument に，5 と string("Hi") が値渡しされ，foo が参照渡しされます．

.. Default Action
.. _cheatsheet_default_action:

デフォルト Action
---------------------------

.. csv-table::
  :header:
  :widths: 5, 35

  "DoDefault()", "（ON_CALL() によって指定される，または組み込みの）デフォルト Action を実行します．"

.. Note: due to technical reasons, DoDefault() cannot be used inside a composite action - trying to do so will result in a run-time error.
**注意：** 技術的な理由により，DoDefault() は複合 Action 内部では利用できません．利用しようとすると，ランタイムエラーが発生します．

.. Composite Actions
.. _cheatsheet_compsite_actions:

複合 Action
----------------

.. csv-table::
  :header:
  :widths: 10, 45

  "DoAll(a1, a2, ..., an)", "a1 から an までの Action が全て実行され，an の結果が毎回返されます．最初の n-1 個の Sub-Action は void を返すものでなければいけません．"
  "IgnoreResult(a)", "Action a を実行し，その結果を無視します．a は，void を返してはいけません．"
  "WithArg<N>(a)", "モック関数の N-番目（0基準）の argument を Action に渡し，それを実行します．"
  "WithArgs<N1, N2, ..., Nk>(a)", "モック関数の引数を（0基準のインデックスで）選択し，Action a に渡して実行します．"
  "WithoutArgs(a)", "引数なしで Action a を実行します"

.. Defining Actions
.. _cheatsheet_defining_actions:

Action を定義する
------------------------

.. csv-table::
  :header:
  :widths: 10, 30

  "ACTION(Sum) { return arg0 + arg1; }", "モック関数の 0番目と 1番目の argument の合計を返す Action Sum() を定義します．"
  "ACTION_P(Plus, n) { return arg0 + n; }", "モック関数の 0番目の argument と n との和を返す Action Plus(n) を定義します．"
  "ACTION_Pk(Foo, p1, ..., pk) { statements; }", "与えられた statements を実行する，パラメータ化された Action Foo(p1, ..., pk) を定義します．"

.. The ACTION* macros cannot be used inside a function or class.
ACTION* マクロは，関数またはマクロの中では利用できません．

.. Cardinalities
.. _cheatsheet_cardinalities:

Cardinalities
============

.. These are used in Times() to specify how many times a mock function will be called:
これらは， Times() 内で，モック関数が呼び出される回数を指定するために利用されます：

.. csv-table::
  :header:
  :widths: 10, 40

  "AnyNumber()", "関数は何度でも呼び出すことができます．"
  "AtLeast(n)", "呼び出し回数は，最低でも n 回であることが期待されます．"
  "AtMost(n)", "呼び出し回数は，最高でも n 回であることが期待されます．"
  "Between(m, n)", "呼びだし回数は，m 回から n 回（これを含む）であることが期待されます．"
  "Exactly(n) or n", "呼び出しは，正確に n 回であることが期待されます．特に，n が 0 の場合は，呼び出しは起こりません．"

.. Expectation Order
.. _cheatsheet_expectation_order:

Expectation の順序
=====================

.. By default, the expectations can be matched in any order. If some or all expectations must be matched in a given order, there are two ways to specify it. They can be used either independently or together.
デフォルトでは，Expectation は任意の順序でマッチすることができます．いくつかの，またはすべての Expectaion を指定した順序通りにマッチする必要がある場合，それを行う方法は2つあります．これらの方法は，独立にも一緒にも利用できます．

.. The After Clause
.. _cheatsheet_the_after_clause:

After 節
----------------------

.. code-block:: c

  using ::testing::Expectation;
  ...
  Expectation init_x = EXPECT_CALL(foo, InitX());
  Expectation init_y = EXPECT_CALL(foo, InitY());
  EXPECT_CALL(foo, Bar())
      .After(init_x, init_y);

.. says that Bar() can be called only after both InitX() and InitY() have been called.
これは，InitX() および InitY() が呼び出された後でのみ，Bar() を呼び出すことができる，ということを意味します．

.. If you don't know how many pre-requisites an expectation has when you write it, you can use an ExpectationSet to collect them:
Expectation を書くときにはまだ，事前に必要な処理の回数が不明な場合， ExpectationSet を利用して，それを数えることができます：

.. code-block:: c

  using ::testing::ExpectationSet;
  ...
  ExpectationSet all_inits;
  for (int i = 0; i < element_count; i++) {
    all_inits += EXPECT_CALL(foo, InitElement(i));
  }
  EXPECT_CALL(foo, Bar())
      .After(all_inits);

.. says that Bar() can be called only after all elements have been initialized (but we don't care about which elements get initialized before the others).
これは，全ての要素が初期化された後でのみ（ただし，要素の初期化される順番には関心がありません），Bar() を呼び出すことができる，ということを意味します．

.. Modifying an ExpectationSet after using it in an .After() doesn't affect the meaning of the .After().
.After() で利用した後に ExpectationSet を変更しても，.After() の意味は変わりません．

.. Sequences
.. _cheatsheet_sequences:

シーケンス
-------------------

.. When you have a long chain of sequential expectations, it's easier to specify the order using sequences, which don't require you to given each expectation in the chain a different name. All expected calls in the same sequence must occur in the order they are specified.
シーケンシャルな Expectation の長い連鎖がある場合は，シーケンスを利用して順序を指定するのが簡単です．この場合，連鎖 の中の各 Expectation に別々の名前を与える必要がありません．同じシーケンスに属する呼び出しは全て，指定された順番で呼び出される必要があります．

.. code-block:: c

  using ::testing::Sequence;
  Sequence s1, s2;
  ...
  EXPECT_CALL(foo, Reset())
      .InSequence(s1, s2)
      .WillOnce(Return(true));
  EXPECT_CALL(foo, GetSize())
      .InSequence(s1)
      .WillOnce(Return(1));
  EXPECT_CALL(foo, Describe(A<const char*>()))
      .InSequence(s2)
      .WillOnce(Return("dummy"));

.. says that Reset() must be called before both GetSize() and Describe(), and the latter two can occur in any order.
これは，GetSize() および Describe() の後でのみ（これらの順序は任意です）， Reset() が呼び出されることを意味します．

.. To put many expectations in a sequence conveniently:
シーケンスに含まれる Expectation の数が多い場合には，便利な方法があります：

.. code-block:: c

  using ::testing::InSequence;
  {
    InSequence dummy;
  
    EXPECT_CALL(...)...;
    EXPECT_CALL(...)...;
    ...
    EXPECT_CALL(...)...;
  }

.. says that all expected calls in the scope of dummy must occur in strict order. The name dummy is irrelevant.)
これは，dummy と同じスコープ内にあるすべての呼び出しが，その順序で発生する必要があることを意味します．dummy という名前には，特に意味はありません．

.. Verifying and Resetting a Mock
.. _cheatsheet_verifying_and_resetting_a_mock:

モックを検証・リセットする
=======================

.. Google Mock will verify the expectations on a mock object when it is destructed, or you can do it earlier:
Google Mock は，モックオブジェクトがデストラクトされた際に，その Expectation を検証します．また，デストラクトよりも前のタイミングでそれを行うこともできます．

.. code-block:: c

  using ::testing::Mock;
  ...
  // mock_obj の Expectation を検証して削除します．
  // 成功した場合のみ true を返します．
  Mock::VerifyAndClearExpectations(&mock_obj);
  ...
  // mock_obj の Expectation を検証して削除します．
  // ON_CALL() で設定されたデフォルト Action も削除されます．
  // 成功した場合のみ true を返します．
  Mock::VerifyAndClear(&mock_obj);

.. You can also tell Google Mock that a mock object can be leaked and doesn't need to be verified:
Google Mock が，特定のモックオブジェクトを検証しないようにすることもできます：

.. code-block:: c

  Mock::AllowLeak(&mock_obj);

.. Mock Classes
.. _cheatsheet_mock_classes:

モッククラス
==============

.. Google Mock defines a convenient mock class template
Google Mock には，便利なモッククラステンプレートが定義されています．

.. code-block:: c

  class MockFunction<R(A1, ..., An)> {
   public:
    MOCK_METHODn(Call, R(A1, ..., An));
  };

.. See this recipe for one application of it.
応用は， :ref:`このレシピ <cookbook_using_check_points>` を参照してください．

.. Flags
.. _cheatsheet_flags:

フラグ
===========

.. csv-table::
  :header:
  :widths: 10,30

  "---gmock_catch_leaked_mocks=0", "検証しないモックオブジェクトを失敗として報告しないようにします．"
  "---gmock_verbose=LEVEL", "Google Mock メッセージの出力レベル（情報，警告，エラー）を設定します．"