Mocking

<Progmasoft/Catch3/Mock.hpp> replaces a dependency of the code under test with a mock that checks how it is called. Mocks report through Catch's assertion path: an unexpected call, a call out of order and an unmet expectation fail the test case that owns the mock, at the line that declared the expectation, in every report the runner writes.

#include <Progmasoft/Catch3/Mock.hpp>
#include <Progmasoft/Catch3/TestMacros.hpp>

class Store
{
public:
    virtual ~Store() = default;
    virtual int Get(const std::string &key) const = 0;
    virtual void Put(const std::string &key, int value) = 0;
};

class MockStore final : public Store
{
public:
    CATCH3_MOCK_METHOD(int, Get, (const std::string &), const override);
    CATCH3_MOCK_METHOD(void, Put, (const std::string &, int), override);
};

TEST_CASE("A score goes up by one")
{
    MockStore store;
    CATCH3_EXPECT_CALL(store.GetMock)("ada").Returns(41);
    CATCH3_EXPECT_CALL(store.PutMock)("ada", 42);

    AddPoint(store, "ada");
}

A mock verifies itself in its destructor, so nothing has to be called at the end of the test case. When the test case is already being left by a failure or a skip, the expectations it did not reach are not reported on top of it. Verify() checks the expectations earlier and forgets them, for a test case that goes on with new ones.

With the amalgamated files, catch_amalgamated.hpp holds all of this.

Declaring mocks

CATCH3_MOCK_METHOD(result, name, (types), specifiers) declares the member function name and the mock nameMock beside it. The specifiers are whatever follows the parameters: const, noexcept, override. Up to 8 parameters are supported, and a type with a comma in it, such as std::map<std::string, int>, needs an alias.

Overloads need mocks with names of their own:

CATCH3_MOCK_OVERLOAD(void, Put, PutOne, (const std::string &, int), override);
CATCH3_MOCK_OVERLOAD(void, Put, PutAll, (const Scores &), override);

CATCH3_MOCK_FUNCTION(name, signature) declares a MockFunction on its own.

Setting expectations

CATCH3_EXPECT_CALL(mock)(arguments...) expects one call. Without arguments it accepts any arguments; otherwise each parameter takes one of these:

Written asAccepts
a valuewhat compares equal to it; strings compare by value, also as const char *, and integers by value whatever their types, so 256 never accepts an unsigned char
a Catch matcher, such as StartsWith("a")what the matcher accepts
Anyanything
Where(predicate, "description")what the predicate accepts

A composition such as StartsWith("a") && EndsWith("z") refers to temporaries that are gone when the mock is called, and Catch's vector matchers, such as Equals(vector), refer to their vector. Neither compiles here; put them in a Where. A matcher of your own has to hold what it compares with.

The result of CATCH3_EXPECT_CALL takes these, in any order:

MemberMeaning
Times(n), Between(a, b), AtLeast(n), AtMost(n), AnyTimes(), Never()how many calls it wants; one by default
Returns(value)the result of each call; a type that cannot be copied moves out on the first one, and a reference result refers to value
Does(function)runs function with the arguments, and returns what it returns; it keeps its state between calls
Throws(exception)throws exception from each call
InSequence(sequence)see below

A call goes to the first expectation, in the order they were declared, that accepts its arguments and can take another call. A call none of them accepts fails the test case and returns a value-initialized result. So does a call they accept when all of them are used up. When the result cannot be made that way, a reference for example, the test case ends there; the same happens to an expectation with no Returns or Does. A noexcept function cannot leave the test case that way, so such a call ends the process.

A mock with no expectation for a call treats it as a failure. An expectation with AnyTimes() is how to allow calls that do not matter to the test.

Sequences

Expectations in a Sequence have to be met in the order they were declared in, across mocks:

Sequence order;
CATCH3_EXPECT_CALL(file.OpenMock)().InSequence(order);
CATCH3_EXPECT_CALL(file.WriteMock)(Any).AtLeast(1).InSequence(order);
CATCH3_EXPECT_CALL(log.FlushMock)().InSequence(order);

A step that is passed takes no more calls. A step reached before the ones ahead of it have their calls fails the test case and names them.

Free functions

Code that reaches a free function through a seam, a std::function or a function pointer it calls through, can be pointed at a mock. ScopedSeam puts the seam back at the end of its scope:

CATCH3_MOCK_FUNCTION(clock, long());
CATCH3_EXPECT_CALL(clock)().Returns(50L);

const ScopedSeam seam(clockSeam, clock.AsFunction());
CHECK(SecondsSince(20) == 30);

The mock has to outlive what AsFunction returns. A function pointer can only take a function without state, so it reaches a mock of static lifetime through one.

Threads

Mocks count and order calls correctly when several threads call them. Reports go through Catch's assertions, which are not safe across threads unless CATCH_CONFIG_EXPERIMENTAL_THREAD_SAFE_ASSERTIONS is set, so a failure in a thread other than the test's needs that setting.

Outside of a test case, such as in the destructor of a global, there is nothing to fail: failures go to standard error.

Diese Seite auf GitHubLizenzen der Dokumentation