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 match the original function's type signature precisely; 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 can be 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 to 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 can be stubbed with the STUB macro. This macro accepts two arguments: the function to stub and the hard-coded return value. The following example is identical to the fake function example from before, 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 hard-coded return value to precisely match the return type of the function being stubbed. For example, if a function returns an integer, then do not stub it to return a float-point value. If it returns a long value, then be sure to add the L suffix to your integer. 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 will never be invoked.

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

The following code example invokes both CALL_GET to invoke the original sum function.

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

TEST(spam, eggs) {
    STUB(sum, 42);                  // mocks 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 go through your fake function. This is because CALL and CALL_GET suspend the mock until they return.

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 concept, however, you can achieve similar functionality by redirecting function calls to a fake function, enabling you to validate both the input arguments and the return value of the original function. The following code snippet demonstrates implementing spying with a fake function. In this example the original foo function is invoked and its value returned. The fake remains entirely transparent to the calling code.

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

static int fake_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, fake_foo); // redirect foo() to fake_foo()
    foo(42);             // trigger fake_foo()
}

When spying it is recommended to use the EXPECT_ family of assertion macros because they do not abort the test thereby allowing the fake function to return to the calling code allowing it to perform resource cleanup. So, for example, while we called the foo function directly from our test in real world code, foo may be invoked internally as part of a hierarchy of function calls. In the call hierarchy, memory and other resources may be allocated that need to be cleaned after foo returns. With the ASSERT_ family of assertion macros, if an assertion fails, it would abort the test thereby preventing code being tested from releasing 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)
{
    ...
}