Skip to main content

Unit Testing C++ Templates and Mock Injection Using Traits

Unit testing your template code comes up from time to time. (You test your templates, right?) Some templates are easy to test. No others. Sometimes it's not clear how to about injecting mock code into the template code that's under test. I've seen several reasons why code injection becomes challenging.

Here I've outlined some examples below with roughly increasing code injection difficulty.
  1. Template accepts a type argument and an object of the same type by reference in constructor
  2. Template accepts a type argument. Makes a copy of the constructor argument or simply does not take one
  3. Template accepts a type argument and instantiates multiple interrelated templates without virtual functions
Lets start with the easy ones.

Template accepts a type argument and an object of the same type by reference in constructor

This one appears straight-forward because the unit test simply instantiates the template under test with a mock type. Some assertion might be tested in the mock class. And that's about it.

Of course, testing with just a single type argument says nothing about rest of the infinite number of types that one could pass to the template. A fancy way to say the same thing is templates are universally quantified so we might have to get little more clever for more scientific testing. More on that later.

For example,
template <class T>
class TemplateUnderTest {
  T *t_;
public:
  TemplateUnderTest(T *t) : t_(t) {}

  void SomeMethod() {
    t->DoSomething();
    t->DoSomeOtherThing();
  }
};

struct MockT {
  void DoSomething() { 
    // Some assertions here. 
  }
  void DoSomeOtherThing() { 
    // Some more assertions here. 
  }
};

class UnitTest {
  void Test1() {
    MockT mock;
    TemplateUnderTest<MockT> test(&mock);
    test.SomeMethod();
    assert(DoSomethingWasCalled(mock));
    assert(DoSomeOtherThingWasCalled(mock));
  }
};

Template accepts a type argument. Makes a copy of the constructor argument or simply does not take one

In this case accessing the object inside the template might be inaccessible due to access privileges. friend classes could be used.
template <class T>
class TemplateUnderTest {
  T t_;
  friend class UnitTest;
public:
  void SomeMethod() {
    t.DoSomething();
    t.DoSomeOtherThing();
  }
};
class UnitTest {
  void Test2() {
    TemplateUnderTest<MockT> test;
    test.SomeMethod();
    assert(DoSomethingWasCalled(test.t_)); // access guts
    assert(DoSomeOtherThingWasCalled(test.t_)); // access guts
  }
};
The UnitTest::Test2 can simply reach into the guts of TemplateUnderTest and verify the assertions on the internal copy of MockT.

Template accepts a type argument and instantiates multiple interrelated templates without virtual functions

For this case, I'll take a real-life example: Asynchronous Google RPC
In C++ async gRPC, there's something called CallData, which as the name suggests, stores the data related to an RPC call. A CallData template can handle multiple RPC of different types. So it's not uncommon to make it a template.
A generic CallData accepts two type arguments Request and Response. This is how it may look like
template <class Request, class Response>
class CallData {
  grpc::ServerCompletionQueue *cq_;
  grpc::ServerContext context_;
  grpc::ServerAsyncResponseWriter<Response> responder_;
  // ... some more state
public:
  using RequestType = Request;
  using ResponseType = Response;

  CallData(grpc::ServerCompletionQueue *q)
    : cq_(q),
      responder_(&context_) 
  {}
  void HandleRequest(Request *req); // application-specific code
  Response *GetResponse(); // application-specific code
};
The unit test for CallData template must verify the behavior of HandleRequest and HandleResponse. These functions call a number of functions of the members. So making sure they are called in correctly is paramount to the correctness of CallData. However, there's a catch.
  1. Some types from grpc namespace are instantiated internally and not passed via the constructor. ServerAsyncResponseWriter and ServerContext, for example.
  2. grpc::ServerCompletionQueue is passed as an argument to the constructor but it has no virtual functions. Only virtual destructor.
  3. grpc::ServerContext is created internally and has no virtual functions
The question is how to test CallData without using full-blown gRPC in the tests? How to mock ServerCompletionQueue? How to mock ServerAsyncResponseWriter, which is itself a template? and on and on...

Without virtual functions, substituting custom behavior becomes challenging. Hardcoded types such as grpc::ServerAsyncResponseWriter are impossible to mock because, well, they are hardcoded and not injected.

It makes little sense to start passing them as constructor arguments. Even if do that, it may be meaningless because they may be final classes or simply have no virtual functions.

So, what gives?

Solution: Traits

Instead of injecting custom behavior by inheriting from a common type (as done in Object-Oriented programming), INJECT THE TYPE ITSELF. We use traits for that. We specialize the traits differently depending upon whether it's production code or unit test code.

Consider the following CallDataTraits
template <class CallData>
class CallDataTraits {
  using ServerCompletionQueue = grpc::ServerCompletionQueue;
  using ServerContext = grpc::ServerContext;
  using ServerAsyncResponseWriter = grpc::ServerAsyncResponseWrite<typename CallData::ResponseType>;
};
This is the primary template for the trait and used for "production" code. Let's use it in the CallData template.
/// Unit testable CallData
template <class Request, class Response>
class CallData { 
  typename CallDataTraits<CallData>::ServerCompletionQueue *cq_;
  typename CallDataTraits<CallData>::ServerContext context_;
  typename CallDataTraits<CallData>::ServerAsyncResponseWriter responder_;
  // ... some more state
public:
  using RequestType = Request;
  using ResponseType = Response;

  CallData(typename CallDataTraits::ServerCompletionQueue *q)
    : cq_(q),
      responder_(&context_) 
  {}
  void HandleRequest(Request *req); // application-specific code
  Response *GetResponse(); // application-specific code
};
Given the above code, it's clear that production code is still using the types from the grpc namespace. However, we can easily replace the grpc types with mock types. Checkout below.
/// In unit test code
struct TestRequest{};
struct TestResponse{};
struct MockServerCompletionQueue{};
struct MockServerContext{};
struct MockServerAsyncResponseWriter{};

/// We want to unit test this type.
using CallDataUnderTest = CallData<TestRequest, TestResponse>;

/// A specialization of CallDataTraits for unit testing purposes only.
template <>
class CallDataTraits<CallDataUnderTest> {
  using ServerCompletionQueue = MockServerCompletionQueue;
  using ServerContext = MockServerContext;
  using ServerAsyncResponseWriter = MockServerAsyncResponseWrite;
};

MockServerCompletionQueue mock_queue;
CallDataUnderTest cdut(&mock_queue); // Now injected with mock types.
Traits allowed us to choose the types injected in CallData depending upon the situation. This technique has zero performance overhead as no unnecessary virtual functions were created to inject functionality. The technique can be used with final classes as well.

Comments

Popular Content

Covariance and Contravariance in C++ Standard Library

Covariance and Contravariance are concepts that come up often as you go deeper into generic programming. While designing a language that supports parametric polymorphism (e.g., templates in C++, generics in Java, C#), the language designer has a choice between Invariance, Covariance, and Contravariance when dealing with generic types. C++'s choice is "invariance". Let's look at an example. struct Vehicle {}; struct Car : Vehicle {}; std::vector<Vehicle *> vehicles; std::vector<Car *> cars; vehicles = cars; // Does not compile The above program does not compile because C++ templates are invariant. Of course, each time a C++ template is instantiated, the compiler creates a brand new type that uniquely represents that instantiation. Any other type to the same template creates another unique type that has nothing to do with the earlier one. Any two unrelated user-defined types in C++ can't be assigned to each-other by default. You have to provide a

Multi-dimensional arrays in C++11

What new can be said about multi-dimensional arrays in C++? As it turns out, quite a bit! With the advent of C++11, we get new standard library class std::array. We also get new language features, such as template aliases and variadic templates. So I'll talk about interesting ways in which they come together. It all started with a simple question of how to define a multi-dimensional std::array. It is a great example of deceptively simple things. Are the following the two arrays identical except that one is native and the other one is std::array? int native[3][4]; std::array<std::array<int, 3>, 4> arr; No! They are not. In fact, arr is more like an int[4][3]. Note the difference in the array subscripts. The native array is an array of 3 elements where every element is itself an array of 4 integers. 3 rows and 4 columns. If you want a std::array with the same layout, what you really need is: std::array<std::array<int, 4>, 3> arr; That's quite annoying for