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 as | Accepts |
|---|---|
| a value | what 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 |
Any | anything |
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:
| Member | Meaning |
|---|---|
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.