CAF has built-in support for writing unit tests. The approach of testing is declarative
and is very similar to the one in Boost.Test and Catch frameworks.
CAF comes with built-in support for writing unit tests in a domain-specific
language (DSL). The API looks similar to well-known testing frameworks such as
Boost.Test and Catch but adds CAF-specific macros for testing messaging between
actors.
There are four main concepts represented as macros in the testing framework.
Our design leverages four main concepts:
\begin{itemize}
\itemcheck - represents a single verification of boolean operation
\itemtest - contains one or more checks
\itemsuite - groups tests together
\itemfixture - equips a test with fixed data environment
\item\textbf{Checks} represent single boolean expressions.
\item\textbf{Tests} contain one or more checks.
\item\textbf{Fixtures} equip tests with a fixed data environment.
\item\textbf{Suites} group tests together.
\end{itemize}
Here is a very basic test case that captures the four main concepts described above.
The following code illustrates a very basic test case that captures the four
main concepts described above.
\begin{lstlisting}
// Adds all tests in this compilation unit to the suite "math".
#define CAF_SUITE math
namespace n1 {
// Pulls in all the necessary macros.
#include "caf/test/dsl.hpp"
namespace {
struct fixture {};
} // namespace
// Makes all members of `fixture` available to tests in the scope.
CAF_TEST_FIXTURE_SCOPE(math_tests, fixture)
// Implements our first test.
CAF_TEST(divide) {
CAF_CHECK(1 / 1 == 0); // this would fail
CAF_CHECK(2 / 2 == 1); // this would pass
CAF_REQUIRE(3 + 3 == 5); // this would fail and stop test execution [uncomment to try]
CAF_CHECK(4 - 4 == 0); // You would not reach here because of failed REQUIRE
CAF_CHECK(1 / 1 == 0); // fails
CAF_CHECK(2 / 2 == 1); // passes
CAF_REQUIRE(3 + 3 == 5); // fails and aborts test execution
CAF_CHECK(4 - 4 == 0); // unreachable due to previous requirement error
}
CAF_TEST_FIXTURE_SCOPE_END()
}
\end{lstlisting}
We have used few macros such as \lstinline^CAF_CHECK^ and \lstinline^CAF_REQUIRE^ to validate our assertions. The main difference between
\lstinline^CAF_REQUIRE^ and \lstinline^CAF_CHECK^ is that even if \lstinline^CAF_CHECK^ fails the control flow will continue, however failure of assertion
by \lstinline^CAF_REQUIRE^ will stop the test exeuction.
The code above highlights the two basic macros \lstinline^CAF_CHECK^ and
\lstinline^CAF_REQUIRE^. The former reports failed checks, but allows the test
to continue on error. The latter stops test execution if the boolean expression
evaluates to false.
The third macro worth mentioning is \lstinline^CAF_FAIL^. It unconditionally
stops test execution with an error message. This is particularly useful for
stopping program execution after receiving unexpected messages, as we will see
later.
\subsection{Testing Actors}
A simple example of a test case is shown below. This example shows that you can create the actor system in your fixture, spawn actors and send messages to them.
In other words, below code is not very different from your regular program however here we are using the macros such as \lstinline^CAF_CHECK^ and have arranged
them as test cases.
The following example illustrates how to add an actor system as well as a
scoped actor to fixtures. This allows spawning of and interacting with actors
in a similar way regular programs would. Except that we are using macros such
as \lstinline^CAF_CHECK^ and provide tests rather than implementing a
While the above example works, very soon you would start to face following problems -
The example above works, but suffers from several issues:
\begin{itemize}
\item Significant amount of boilerplate
\item Above is a simple example of one actor, if you are unit testing one actor it would work however in most cases you would have an actor under test sending messages to
other actors. Writing code to validate all messages exchanges would not be trivial.
\item When testing the primary goal is to check the interaction between the actors and not necessarily the scheduling on multiple threads and/or the asynchronous nature of it.
\item
Significant amount of boilerplate code.
\item
Using a scoped actor as illustrated above can only test one actor at a
time. However, messages between other actors are invisible to us.
\item
CAF runs actors in a thread pool by default. The resulting nondeterminism
makes triggering reliable ordering of messages near impossible. Further,
forcing timeouts to test error handling code is even harder.
\end{itemize}
Next section describes the usage of \lstinline^test_coordinator^ that helps eliminiate the boilerplate as well as provide more deterministic and synchornous way
of writing tests.
\subsection{Deterministic Testing}
\subsection{Test Coordinator}
CAF provides a scheduler implementation specifically tailored for writing unit
tests called \lstinline^test_coordinator^. It does not start any threads and
instead gives unit tests full control over message dispatching and timeout
management.
CAF provides an implementation of coordinator (called \lstinline^test_coordinator^) that you supply to the scheduler. This coordinator is specifically designed
for testing as it does not schedule your actors on multiple thread.
To reduce boilerplate code, CAF also provides a fixture template called
\lstinline^test_coordinator_fixture^ that comes with ready-to-use actor system
(\lstinline^sys^) and testing scheduler (\lstinline^sched^). The optional
template parameter allows unit tests to plugin custom actor system
configuration classes.
There is also a fixture class called \lstinline^test_coordinator_fixture^ that is provided to hide the details and reduce the boilerplate for setting up the scheduler
with \lstinline^test_corrdinator^.
Using this fixture unlocks three additional macros: