Mocking with Fakes 🔗

Fakes let you intercept a function call and redirect it to a different function known as the fake function. For the fake function to work correctly, its type signature must be identical to the original function’s type signature, otherwise, the behavior is undefined.

The fake function can include custom logic for parameter validation, call through to the original function, and return its own test-specific return value.

In Audition, C functions are faked with the FAKE macro. This macro accepts two arguments: the function to fake and the function to redirect to.

In the following example, the FAKE macro is used to redirect all calls from the foo function to the fake_foo function.

int foo(void); // forward declaration

static int fake_foo(void) {
    return 42;
}

TEST(spam, eggs) {
    FAKE(foo, fake_foo);             // mocks foo()
    printf("foo: %d\n", fake_foo()); // prints 42
}

Mocking with Stubs 🔗

Stubs let you intercept a function call and return a hard-coded value without needing to write a dedicated fake function. This is useful in situations where the primary purpose of your fake function is to simply return a predetermined value.

In Audition, C functions are stubbed with the STUB macro. This macro accepts two arguments: the function to stub and a constant to return.

The following example is identical to the fake function example except there is no need to implement a separate fake_foo function.

TEST(spam, eggs) {
    STUB(foo, 42);              // mocks foo()
    printf("foo: %d\n", foo()); // prints 42
}

Stubbing a function requires the type of the constant to match the return type of the function being stubbed, e.g. if a function returns an integer, do not stub it to return a floating-point value. If it returns a long integer, then add the L suffix. If the return types mismatch, then the behavior is undefined.

Mocking Lifecycle 🔗

Understanding the lifecycle of mocks is crucial for effective testing. Here’s what you need to know about the duration, management, and cleanup of mocks.

TEST_SETUP(spam) {
    STUB(foo, 42); // mocks foo() before each test case
}

TEST(spam, eggs) {
    printf("foo: %d\n", foo()); // prints 42
}

TEST(spam, ham) {
    printf("foo: %d\n", foo()); // prints 42
}

TEST(spam, eggs) {
    STUB(foo, 42);              // mock foo()
    printf("foo: %d\n", foo()); // prints 42
    RESTORE(foo);               // unregister the mock for foo()
    printf("foo: %d\n", foo()); // calls original foo()
}

TEST(spam, eggs) {
    STUB(foo, 42);              // mock foo()
    printf("foo: %d\n", foo()); // prints 42

    SUSPEND_MOCKS();            // suspends all mocks
    printf("foo: %d\n", foo()); // calls original foo()
    RESTORE_MOCKS();            // restores all mocks

    printf("foo: %d\n", foo()); // prints 42
}

Calling Through to the Original Function 🔗

When a function is mocked, all calls to the original function will be redirected to the mock. The mock may be implemented as a fake or stub, but regardless the original function is never invoked.

Sometimes you do need to call the original function without unregistering the mock with RESTORE or suppressing all mocks with SUSPEND_MOCKS. For these situations, Audition provides the macros CALL and CALL_GET to invoke the original function. The CALL macro lets you invoke the original function and discard any return value it may have. The CALL_GET macro lets you invoke the original function and store its return value in a variable.

The following example uses CALL_GET to invoke the original sum function.

int sum(int x, int y) {
    return x + y;
}

TEST(spam, eggs) {
    STUB(sum, 42);                  // stub sum()
    printf("sum: %d\n", sum(1, 2)); // prints 42

    int result;
    CALL_GET(sum, &result, 1, 2);   // call original sum()
    printf("sum: %d\n", result);    // prints 3
}

You can invoke CALL and CALL_GET macros from a fake function, however, if the function being mocked is invoked recursively then subsequent invocations will not use your fake function. This is because CALL and CALL_GET suspend the mock until they return. It is only after the outermost recursive call returns that the mock will be restored.

Spying Using Fakes 🔗

A spy is a technique used to monitor the behavior of a function, particularly its input arguments and return values, without altering its behavior. Spies let you verify that functions are called with the expected parameters and that they return the correct results.

Audition does not have a built-in spy feature, but you can implement one by redirecting function calls to a fake function. In this fake function, you can assert the input arguments, call the original function, verify the results, and return the actual return value. The following code example demonstrates how to implement spying using this approach. In the example, the original foo function is called, and its return value is transparently passed back. The presence of the fake function remains transparent to the calling code.

int foo(int x); // original function declaration

static int spy_foo(int x) {
    EXPECT_EQ(x, 42);          // assert the argument

    int result;
    CALL_GET(foo, &result, x); // call the original foo()

    EXPECT_EQ(result, 123);    // assert the return value
    return result;
}

TEST(spam, argument_spy) {
    FAKE(foo, spy_foo);  // redirect foo() to spy_foo()
    foo(42);             // transparently calls through spy_foo()
}

In the previous example, the foo function was called directly from the test case, but in real world code, foo might be invoked as part of a hierarchy of function calls. In the call hierarchy, memory and other resources might be allocated that need to be released after foo returns. It is therefore recommended to use the EXPECT_ family of assertion macros in the fake function because these macros do not abort the test case. This lets the function return to the call site for resource cleanup. With the ASSERT_ family of assertion macros, if an assertion fails, it would abort the test thereby leaking any intermediate resources.

Safe Mocking Practices 🔗

While mocking is a powerful tool for isolating tests and controlling the behavior of functions, it comes with certain risks that users should be aware of. Improper use of mocking can lead to unexpected behavior and challenging to diagnose issues.

Mocking system functions, like malloc, can potentially lead to problems, especially when those functions are fundamental to the operation of your code and third-party libraries you depend on. For example:

• Mocking malloc() - If you stub malloc to return NULL, then any code that relies on malloc will be adversely affected.
• Mocking exit() - Implementing a fake for exit that does not terminate will lead to code expecting it to terminate to continue executing, likely leading to unintended consequences.

Additionally, some compilers may replace specific C standard function calls with their own implementations in the generated assembly code. At the time of this writing, GCC replaces calls to printf with __printf_chk when optimizations are enabled. In this case mocking printf won’t work because it’s __printf_chk that’s called!

To mitigate these issues, consider limiting your mocks to functions within your application’s business logic rather than core system functions. If you must mock a core system function, then carefully consider its potential impact on the overall system. Similarly, mocking public functions from third-party libraries that your code calls directly is usually fine, but be mindful of any other libraries that invoke those same functions and the impact your mock may have on them.

Limitations of Mocking 🔗

In Audition, function mocking is implemented by patching the prologue of the target function at runtime to redirect execution to a mock implementation. The ability to patch functions in memory requires an operating system which supports modifying memory protection permissions. Please review the supported platforms and compilers.

When a mock is uninstalled, Audition restores the original prologue.

cannot mock foo(): function implementation too small

// GCC
void __attribute__((noinline)) foo(void)
{
    ...
}

// MSVC
__declspec(noinline) void foo(void)
{
    ...
}