trompeloeil/docs/FAQ.md

FAQ

• Q. Why a name that can neither be pronounced nor spelled?
• Q. Which compilers supports Trompeloeil?
• Q. How do I use Trompeloeil with XXX unit test framework?
• Q. Is Trompeloeil thread safe?
• Q. Can a mock function be marked override?
• Q. Why can't I .RETURN() a reference?
• Q. Why can't I change a local variable in .SIDE_EFFECT()?
• Q. Why the "local reference" .LR_*() variants? Why not always capture by reference?
• Q. Is it possible to allow all calls to all mocked functions for all mock objects?
• Q. Why are parameters referenced by position and not by name?
• Q. Why the need to provide the number of parameters in MAKE_MOCKn() when all information is in the signature?
• Q. Why C++14 and not C++11 or C++03 that is more widely spread?
• Q. Why are my parameter values printed as hexadecimal dumps in violation reports
• Q. Can I mock a C function API?
• Q. Can I match a value pointed to by a pointer parameter?
• Q. Can I negate the effect of a matcher?

Q. Why a name that can neither be pronounced nor spelled?

A. It's a parallel to arts. Trompe-l'œil, which literally means "trick the eye," refers to an art form where the artist creates something that tricks the viewer into thinking they see something other than what is there. Writing mocks for testing has resemblances to creating Trompe-l'œil art, in that you create mocks that "tricks" the test object as if it was interacting with the intended real world. When you use mocks in a test program, you are the Trompe-l'œil artist, tricking the code under test.

Perhaps Illusionist or Puppeteer would have sufficed as names, but they were taken many times over for other projects, and besides, the author has a soft spot for Trompe-l'œil art.

If you really cannot handle the name, you can use the following renaming mechanism. Assume that you'd like the name chimera instead.

Create a file chimera.hpp with the following contents:

#ifndef CHIMERA_HPP
#define CHIMERA_HPP

#include <trompeloeil.hpp>
namespace chimera = trompeloeil;

#endif /* include guard */

Your tests can now #include <chimera.hpp> and use (for example) chimera::expectation and chimera::deathwatched<T>

Q. Which compilers supports Trompeloeil?

A. Trompeloeil is known to work well with:

• g++ 4.9 and later.
• clang++ 3.6 and later
• VisualStudio 2015 and later.

Q. How do I use Trompeloeil with XXX unit test framework?

A. By default, Trompeloeil reports violations by throwing an exception, explaining the problem in the what() string.

Depending on your test frame work and your runtime environment, this may, or may not, suffice.

Trompeloeil offers support for adaptation to any test frame work. Adaptation examples for some popular unit test frame works are listed in the cook book

Q. Is Trompeloeil thread safe?

A. Yes, with caveats.

In a unit test you don't want to depend on the scheduler, which is typically out of your control. However, some times it is convenient to use a unit test like environment to exercise a larger aspect of your code. In this setting, using mock objects with different expectations can make sense when statistically searching for synchronization problems.

To enable this, Trompeloeil uses a global recursive_mutex which protects expectations.

Expectations can come and go in different threads, and mock functions can be called in different threads, all protected by the global lock. However, it is essential that the mock object is not deleted while establishing the expectation or calling the mock function, as per normal thread safety diligence.

Should you need to access the lock in your tests, you can do so with

  auto lock = trompeloeil::get_lock();

lock holds the recursive_mutex until it goes out of scope.

Q. Can a mock function be marked override?

A. Yes, just add override a third parameter to MAKE_MOCKn() or MAKE_CONST_MOCKn()

Example:

class Interface
{
public:
  virtual ~Interface() = default;
  virtual int func1(int) = 0;
};

class Mock : public Interface
{
public:
  MAKE_MOCK1(func1, int(int), override); // overridden
  MAKE_MOCK1(func2, int(int));           // not overridden
};

Q. Why can't I .RETURN() a reference?

A. You can, but the language is a bit peculiar.

For parameters or returned references from function calls, just use .RETURN(value). For local variables you need .LR_RETURN(), and for both global and local variables you either need to use std::ref(value) or std::cref(value) for it, or just enclose the value in an extra parenthesis, like this .LR_RETURN((value))

Example:

class C
{
public:
  MAKE_MOCK1(lookup, std::string&(int));
};

using trompeloeil::_;
using trompeloeil::lt;

TEST(some_test)
{
  C mock_obj;
  
  std::map<int, std::string> dictionary{ {...} };
  
  std::string default_string;
  
  ALLOW_CALL(mock_obj, lookup(_))
    .LR_RETURN(dictionary.at(_1)); // function call
  
  ALLOW_CALL(mock_obj, lookup(trompeloeil::lt(0)))
    .LR_RETURN((default_string)); // extra parenthesis
    
  ALLOW_CALL(mock_obj, lookup(0))
    .LR_RETURN(std::ref(default_string));

  test_func(&mock_obj);
}

Above, the expectations on function lookup() is that any call is allowed and will return an lvalue-reference to either a match in dictionary, or to the local variable default_string. The reference is non-const, so test_func() is allowed to change the returned string.

Q. Why can't I change a local variable in .SIDE_EFFECT()?

A. It would almost certainly be very confusing. All local variables referenced in .WITH(), .SIDE_EFFECT(), .RETURN() and .THROW() are captured by value, i.e. each such clause has its own copy of the local variable. If you could change it, it would change the value in that clause only and not in any of the others.

Example:

class C
{
public:
  MAKE_MOCK1(func, void(int));
};

using trompeloeil::_;

TEST(some_test)
{
  C mock_obj;
  
  unsigned abs_sum = 0;
  
  ALLOW_CALL(mock_obj, func(trompeloeil::gt(0)))
    .SIDE_EFFECT(abs_sum+= _1); // illegal code!
     
  ALLOW_CALL(mock_obj, func(trompeloeil::lt(0))
    .SIDE_EFFECT(abs_sum-= _1); // illegal code!
     
  ALLOW_CALL(mock_obj, func(0));
  
  test_func(&mock_obj);

The two SIDE_EFFECT() clauses above each have their own copy of the local variable abs_sum. Allowing them to update their own copies would be very confusing, and it would also be difficult to get the value back to the test.

If you need to change the value of a local variable it is better to use the alternative "local reference" forms LR_SIDE_EFFECT(), LR_WITH(), LR_RETURN() or LR_THROW().

Q. Why the "local reference" .LR_*() variants? Why not always capture by reference?

A. It's safer. Lifetime management can be tricky in C++, and even more so when complex functionality is hiding behind hideous macros in a frame work. Experiences from the alpha phase, where this distinction wasn't made, made the problem glaringly obvious. Making the default safe, and providing the option to very visibly use the potentially unsafe, is considerably better, although it makes the test code somewhat visually unpleasant.

Q. Is it possible to allow all calls to all mocked functions for all mock objects?

A. No, it is not. There are two reasons for this, technical and philosophical.

Technical There is a problem with the return value. It is difficult, if at all possible, to come up with a generic return that works for all types. This could be overcome by allowing all calls to all functions with a certain return type, for all objects.

Philosophical While there are no doubt situations where this would be convenient, it could be a very dangerous convenience that opens up for relaxing tests unnecessarily, simply because it's so easy to allow everything, and then when you introduce a bug, you never notice because everything is allowed. If a safe way of allowing all calls is thought of, then this may change, but having a perhaps unnecessarily strict rule that can be relaxed is safer than the alternative.

Q. Why are parameters referenced by position and not by name?

A. If you can figure out a way to refer to parameters by name, please open an issue discussing the idea. If you can provide a pull request, so much the better.

Q. Why the need to provide the number of parameters in MAKE_MOCKn() when all information is in the signature?

A. If you can figure out a way to infer the information necessary to generate a mocked implementation without an explicit parameter count, please open an issue discussing the idea. If you can provide a pull request, so much the better.

Q. Why C++14 and not C++11 or C++03 that is more widely spread?

A. C++03 and older is completely out. The functionality needed for Trompeloeil isn't there. Lambdas and variadic templates are absolutely necessary.

The only thing "needed" that C++11 doesn't provide is generic lambdas It is perhaps possible that "needed" is too strong a word, that it is in fact possible without them, in which case a back port to C++11 could be made.

Q. Why are my parameter values printed as hexadecimal dumps in violation reports?

A. By default Trompeloeil prints parameter values using the stream insertion operators for the type, but if none exists, it presents a hexadecimal dump of the memory occupied by the value.

You can change that either by providing a stream insertion operator for your type, or by providing a custom formatter for it.

Q. Can I mock a C function API?

A. Trompeloeil can mock member functions only. However, there are tricks you can use to mock a function API, provided that it is OK to use a link seam and link your test program with a special test implementation of the API that calls mocks. Heres's an example:

/* c_api.h */
#ifdef __cplusplus
extern "C" {
#endif

int func1(const char*);
const char* func2(int);

#ifdef __cplusplus
}
#endif

With the above C-API mocks can be made:

/* mock_c_api.h */
#ifndef MOCK_C_API_H
#define MOCK_C_API_H

#include <c_api.h>
#include <cassert>
#include <string>
#include <trompeloeil.hpp>

struct mock_api
{
  static mock_api*& instance() { static mock_api* obj = nullptr; return obj; }
  mock_api() { assert(instance() == nullptr); instance() = this; }
  ~mock_api() { assert(instance() == this); instance() = nullptr; }
  mock_api(const mock_api&) = delete;
  mock_api& operator=(const mock_api&) = delete;

  MAKE_CONST_MOCK1(func1, int(std::string)); // strings are easier to deal with
  MAKE_CONST_MOCK1(func2, const char*(int));
};

endif /* include guard */

Note that the mock constructor stores a globally available pointer to the instance, and the destructor clears it.

With the mock available the test version the C-API can easily be implemented:

#include "mock_c_api.h"

int func1(const char* str)
{
  auto obj = mock_api::instance();
  assert(obj);
  return obj->func1(str); // creates a std::string
}

const char* func2(int value)
{
  auto obj = mock_api::instance();
  assert(obj);
  return obj->func2(value);
}

Now your tests becomes simple:

#include "mock_c_api.h"
#include "my_obj.h"
TEST("my obj calls func1 with empty string when poked")
{
  mock_api api;
  my_obj tested;
  {
    REQUIRE_CALL(api, func1(""))
      .RETURN(0);
    tested.poke(0);
  }
}

Q. Can I match a value pointed to by a pointer parameter?

A. You can always match with _ and use LR_WITH() or WITH() using whatever logic you like. But using matchers you can match the value pointed to using unary operator * on the matcher

See Matching pointers to values in the Cook Book.

Q. Can I negate the effect of a matcher?

A. You can always match with _ and use LR_WITH() or WITH() using whatever logic you like. But using matchers you can negate the effect of the matcher, allowing what the match er disallows and vice versa, using operator ! on the matcher

See Matching the opposite of a matcher in the Cook Book.