CAF has built-in support for writing unit tests. The approach of testing is declarative
CAF comes with built-in support for writing unit tests in a domain-specific
and is very similar to the one in Boost.Test and Catch frameworks.
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}
\begin{itemize}
\itemcheck - represents a single verification of boolean operation
\item\textbf{Checks} represent single boolean expressions.
\itemtest - contains one or more checks
\item\textbf{Tests} contain one or more checks.
\itemsuite - groups tests together
\item\textbf{Fixtures} equip tests with a fixed data environment.
\itemfixture - equips a test with fixed data environment
\item\textbf{Suites} group tests together.
\end{itemize}
\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}
\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 {};
struct fixture {};
} // namespace
// Makes all members of `fixture` available to tests in the scope.
CAF_TEST_FIXTURE_SCOPE(math_tests, fixture)
CAF_TEST_FIXTURE_SCOPE(math_tests, fixture)
// Implements our first test.
CAF_TEST(divide) {
CAF_TEST(divide) {
CAF_CHECK(1 / 1 == 0); // this would fail
CAF_CHECK(1 / 1 == 0); // fails
CAF_CHECK(2 / 2 == 1); // this would pass
CAF_CHECK(2 / 2 == 1); // passes
CAF_REQUIRE(3 + 3 == 5); // this would fail and stop test execution [uncomment to try]
CAF_REQUIRE(3 + 3 == 5); // fails and aborts test execution
CAF_CHECK(4 - 4 == 0); // You would not reach here because of failed REQUIRE
CAF_CHECK(4 - 4 == 0); // unreachable due to previous requirement error
}
}
CAF_TEST_FIXTURE_SCOPE_END()
CAF_TEST_FIXTURE_SCOPE_END()
}
\end{lstlisting}
\end{lstlisting}
We have used few macros such as \lstinline^CAF_CHECK^ and \lstinline^CAF_REQUIRE^ to validate our assertions. The main difference between
The code above highlights the two basic macros \lstinline^CAF_CHECK^ and
\lstinline^CAF_REQUIRE^ and \lstinline^CAF_CHECK^ is that even if \lstinline^CAF_CHECK^ fails the control flow will continue, however failure of assertion
\lstinline^CAF_REQUIRE^. The former reports failed checks, but allows the test
by \lstinline^CAF_REQUIRE^ will stop the test exeuction.
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}
\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.
The following example illustrates how to add an actor system as well as a
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
scoped actor to fixtures. This allows spawning of and interacting with actors
them as test cases.
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}
\begin{itemize}
\item Significant amount of boilerplate
\item
\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.
\end{itemize}
Significant amount of boilerplate code.
Next section describes the usage of \lstinline^test_coordinator^ that helps eliminiate the boilerplate as well as provide more deterministic and synchornous way
\item
of writing tests.
\subsection{Test Coordinator}
Using a scoped actor as illustrated above can only test one actor at a
time. However, messages between other actors are invisible to us.
CAF provides an implementation of coordinator (called \lstinline^test_coordinator^) that you supply to the scheduler. This coordinator is specifically designed
\item
for testing as it does not schedule your actors on multiple thread.
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
CAF runs actors in a thread pool by default. The resulting nondeterminism
with \lstinline^test_corrdinator^.
makes triggering reliable ordering of messages near impossible. Further,
forcing timeouts to test error handling code is even harder.