Class and Function Mocking

This file documents class and function mocking features.

Note

If possible, prefer class mocking over arbitrary function mocking. Class mocking has a much more limited scope and provides more control. This file documents class mocking and most mocking features that do not depend on function or platform mocking.

Readability Macros

When defining and declaring mock stubs, use these readability macros.

#define CLASS(struct_name) struct_name
#define HANDLE_INDEX(index) index
#define METHOD(method_name) method_name
#define RETURNS(return_type) return_type
#define PARAMS(...) __VA_ARGS__

Consider a struct Foo with a member function int add(struct Foo*, int a, int b);

When generating a mock stub with DEFINE_STRUCT_CLASS_MOCK(), which takes a method name, struct name, return type, and method parameters, the arguments should be passed in with the readability macros.

DEFINE_STRUCT_CLASS_MOCK(
        METHOD(add),
        CLASS(Foo),
        RETURNS(int),
        PARAMS(struct Foo *, int, int)
);

For a more detailed example of this, take a look at the example in Getting Started

These macros should only be used in the context of the mock stub generators.

Built in Matchers

These are the matchers that can be used when matching arguments in EXPECT_CALL() (more can be defined manually).

For example, there’s a matcher that matches any arguments:

struct mock_param_matcher *any(struct test *test);

There are matchers for integers based on the binary condition:

  • eq: equals to
  • ne: not equal to
  • lt: less than
  • le: less than or equal to
  • gt: greater than
  • ge: greater than or equal to
struct mock_param_matcher *int_eq(struct test *test, int expected);
struct mock_param_matcher *int_ne(struct test *test, int expected);
struct mock_param_matcher *int_lt(struct test *test, int expected);
struct mock_param_matcher *int_le(struct test *test, int expected);
struct mock_param_matcher *int_gt(struct test *test, int expected);
struct mock_param_matcher *int_ge(struct test *test, int expected);

For a detailed list, please see include/linux/mock.h.

Mock Returns

These functions can be used to specify a value to be returned (ret) when a mocked function is intercepted via EXPECT_CALL().

struct mock_action *int_return(struct test *test, int ret);
struct mock_action *u32_return(struct test *test, u32 ret);

API

struct mock_param_matcher

represents a matcher used in a call expectation

Definition

struct mock_param_matcher {
  bool (*match)(struct mock_param_matcher *this,struct test_stream *stream, const void *param);
};

Members

match
the function that performs the matching

Description

The matching function takes a couple of parameters:

  • this: refers to the parent struct
  • stream: a test_stream to which a detailed message should be added as to why the parameter matches or not
  • param: a pointer to the parameter to check for a match

The matching function should return whether or not the passed parameter matches.

struct mock_action

Represents an action that a mock performs when expectation is matched

Definition

struct mock_action {
  void *(*do_action)(struct mock_action *this,const void **params, int len);
};

Members

do_action
the action to perform

Description

The action function is given some parameters:

  • this: refers to the parent struct
  • params: an array of pointers to the params passed into the mocked method or function. The class argument is excluded for a mocked class method.
  • len: size of params

The action function returns a pointer to the value that the mocked method or function should be returning.

struct mock_expectation

represents a call expectation on a function.

Definition

struct mock_expectation {
  struct mock_action *action;
  int max_calls_expected;
  int min_calls_expected;
  bool retire_on_saturation;
};

Members

action
A struct mock_action to perform when the function is called.
max_calls_expected
maximum number of times an expectation may be called.
min_calls_expected
minimum number of times an expectation may be called.
retire_on_saturation
no longer match once max_calls_expected is reached.

Description

Represents a call expectation on a function created with EXPECT_CALL().

STRICT_MOCK(mock)

sets the mock to be strict and returns the mock

Parameters

mock
the mock

Description

For an example, see The Nice, the Strict, and the Naggy under Using KUnit.

NICE_MOCK(mock)

sets the mock to be nice and returns the mock

Parameters

mock
the mock

Description

For an example, see The Nice, the Strict, and the Naggy under Using KUnit.

NAGGY_MOCK(mock)

sets the mock to be naggy and returns the mock

Parameters

mock
the mock

Description

For an example, see The Nice, the Strict, and the Naggy under Using KUnit.

EXPECT_CALL(expectation_call)

Declares a call expectation on a mock method or function.

Parameters

expectation_call
a mocked method or function with parameters replaced with matchers.

Example

// Class to mock.
struct example {
        int (*foo)(struct example *, int);
};

// Define the mock.
DECLARE_STRUCT_CLASS_MOCK_PREREQS(example);

DEFINE_STRUCT_CLASS_MOCK(METHOD(foo), CLASS(example),
                         RETURNS(int),
                         PARAMS(struct example *, int));

static int example_init(struct MOCK(example) *mock_example)
{
        struct example *example = mock_get_trgt(mock_example);

        example->foo = foo;
        return 0;
}

DEFINE_STRUCT_CLASS_MOCK_INIT(example, example_init);

static void foo_example_test_success(struct test *test)
{
        struct MOCK(example) *mock_example;
        struct example *example = mock_get_trgt(mock_example);
        struct mock_expectation *handle;

        mock_example = CONSTRUCT_MOCK(example, test);

        handle = EXPECT_CALL(foo(mock_get_ctrl(mock_example),
                             int_eq(test, 5)));
        handle->action = int_return(test, 2);

        EXPECT_EQ(test, 2, example_bar(example, 5));
}

Return

A struct mock_expectation representing the call expectation. allowing additional conditions and actions to be specified.

struct mock_expectation * Times(int times, struct mock_expectation * expectation)

sets the number of times a method is expected be called with the matching parameters

Parameters

int times
the number of times expected
struct mock_expectation * expectation
the expectation to set

Return

the same struct mock_expectation passed in

struct mock_expectation * AtLeast(int times, struct mock_expectation * expectation)

sets the minimum number of times a method is expected to be called with matching parameters

Parameters

int times
the minimum number of times expected
struct mock_expectation * expectation
the expectation to set

Return

the same struct mock_expectation passed in

struct mock_expectation * AtMost(int times, struct mock_expectation * expectation)

sets the maximum number of times a method is expected to be called with matching parameters

Parameters

int times
the maximum number of times expected
struct mock_expectation * expectation
the expectation to set

Return

the same struct mock_expectation passed in

struct mock_expectation * Between(int min_times, int max_times, struct mock_expectation * expectation)

sets the minimum and maximum number of times a method is expected to be called with matching parameters

Parameters

int min_times
the minimum number of times expected
int max_times
the maximum number of times expected
struct mock_expectation * expectation
the expectation to set

Return

the same struct mock_expectation passed in

struct mock_expectation * Never(struct mock_expectation * expectation)

alias for Times(0)

Parameters

struct mock_expectation * expectation
the expectation to set

Return

the same struct mock_expectation passed in

struct mock_expectation * RetireOnSaturation(struct mock_expectation * expectation)

sets the expectation to retire on saturation

Parameters

struct mock_expectation * expectation
the expectation to set

Return

the same struct mock_expectation passed in

struct mock_expectation * ActionOnMatch(struct mock_expectation * expectation, struct mock_action * action)

sets a action of the expectation when matched

Parameters

struct mock_expectation * expectation
the expectation to set the action of
struct mock_action * action
action to perform when expectation matches

Example

ActionOnMatch(EXPECT_CALL(...), INVOKE_REAL(test, ...));

Return

the same struct mock_expectation passed in

struct mock_expectation * Returns(struct mock_expectation * expectation, struct mock_action * return_action)

sets a action of the expectation to return a value

Parameters

struct mock_expectation * expectation
the expectation to set the return value of
struct mock_action * return_action
a return action

Example

Returns(EXPECT_CALL(...), int_return(test, 10));

Return

the same struct mock_expectation passed in

InSequence(test, first, )

defines an order for expectations to be matched

Parameters

test
the test, used for internal resource allocations
first
the first struct mock_expectation in the sequence
...
the rest of the expectations in order following

Example

struct mock_expectation *a = EXPECT_CALL(...);
struct mock_expectation *b = EXPECT_CALL(...);
struct mock_expectation *c = EXPECT_CALL(...);

InSequence(test, a, b, c);

Return

0 if everything was successful, otherwise a memory allocation error

DECLARE_STRUCT_CLASS_MOCK_PREREQS(struct_name)

Create a mock child class

Parameters

struct_name
name of the class/struct to be mocked

Description

Creates a mock child class of struct_name named struct MOCK(struct_name) along with supporting internally used methods.

See EXPECT_CALL() for example usages.

DECLARE_STRUCT_CLASS_MOCK(name, struct_name, return_type, param_types…)

Parameters

name
method name
struct_name
name of the class/struct
return_type
return type of the method
param_types...
variable arguments

Description

Same as DEFINE_STRUCT_CLASS_MOCK(), but only makes header compatible declarations.

DECLARE_STRUCT_CLASS_MOCK_VOID_RETURN(name, struct_name, param_types…)

Parameters

name
method name
struct_name
name of the class/struct
param_types...
variable arguments

Description

Same as DEFINE_STRUCT_CLASS_MOCK_VOID_RETURN(), but only makes header compatible declarations.

DECLARE_STRUCT_CLASS_MOCK_INIT(struct_name)

Parameters

struct_name
name of the class/struct

Description

Same as DEFINE_STRUCT_CLASS_MOCK_INIT(), but only makes header compatible declarations.

CONSTRUCT_MOCK(struct_name, test)

Parameters

struct_name
name of the class
test
associated test

Description

Constructs and allocates a test managed struct MOCK(struct_name) given the name of the class for which the mock is defined and a test object.

See EXPECT_CALL() for example usage.

DEFINE_REDIRECT_MOCKABLE(name, return_type, param_types…)

Parameters

name
name of the function
return_type
return type of the function
param_types...
variable arguments

Description

Used to define a function which is redirect-mockable, which allows the function to be mocked and refer to the original definition via INVOKE_REAL().

Example

DEFINE_REDIRECT_MOCKABLE(i2c_add_adapter,
                         RETURNS(int), PARAMS(struct i2c_adapter *));
int REAL_ID(i2c_add_adapter)(struct i2c_adapter *adapter)
{
        ...
}

static int aspeed_i2c_test_init(struct test *test)
{
        struct mock_param_capturer *adap_capturer;
        struct mock_expectation *handle;
        struct aspeed_i2c_test *ctx;
        int ret;

        ctx = test_kzalloc(test, sizeof(*ctx), GFP_KERNEL);
        if (!ctx)
                return -ENOMEM;
        test->priv = ctx;

        handle = EXPECT_CALL(
                        i2c_add_adapter(capturer_to_matcher(
                                        adap_capturer)));
        handle->action = INVOKE_REAL(test, i2c_add_adapter);
        ret = of_fake_probe_platform_by_name(test,
                                             "aspeed-i2c-bus",
                                             "test-i2c-bus");
        if (ret < 0)
                return ret;

        ASSERT_PARAM_CAPTURED(test, adap_capturer);
        ctx->adap = mock_capturer_get(adap_capturer,
                                      struct i2c_adapter *);

        return 0;
}
DEFINE_STRUCT_CLASS_MOCK(name, struct_name, return_type, param_types…)

Parameters

name
name of the method
struct_name
name of the class of which the method belongs
return_type
return type of the method to be created. Must not be void.
param_types...
variable arguments

Description

See EXPECT_CALL() for example usage.

DEFINE_STRUCT_CLASS_MOCK_VOID_RETURN(name, struct_name, param_types…)

Parameters

name
name of the method
struct_name
name of the class of which the method belongs
param_types...
variable arguments

Description

Same as DEFINE_STRUCT_CLASS_MOCK() except the method has a void return type.

DEFINE_STRUCT_CLASS_MOCK_INIT(struct_name, init_func)

Parameters

struct_name
name of the class
init_func
a function of type int (*)(struct MOCK(struct_name) *). This function is passed a pointer to an allocated, but not initialized, struct MOCK(struct_name). The job of this user provided function is to perform remaining initialization. Usually this entails assigning mock methods to the function pointers in the parent struct.

Description

See EXPECT_CALL() for example usage.

DEFINE_FUNCTION_MOCK(name, return_type, param_types…)

Parameters

name
name of the function
return_type
return type of the function
param_types...
variable arguments

Description

Same as DEFINE_STRUCT_CLASS_MOCK() except can be used to mock any function declared __mockable or DEFINE_REDIRECT_MOCKABLE()

DEFINE_FUNCTION_MOCK_VOID_RETURN(name, param_types…)

Parameters

name
name of the function
param_types...
variable arguments

Description

Same as DEFINE_FUNCTION_MOCK() except the method has a void return type.

__mockable()

A function decorator that allows the function to be mocked.

Parameters

Example

int __mockable example(int arg) { ... }
__visible_for_testing()

Makes a static function visible when testing.

Parameters

Description

A macro that replaces the static specifier on functions and global variables that is static when compiled normally and visible when compiled for tests.

struct mock_struct_matcher_entry

composed with other struct mock_struct_matcher_entry to make a struct struct_matcher

Definition

struct mock_struct_matcher_entry {
  size_t member_offset;
  struct mock_param_matcher *matcher;
};

Members

member_offset
offset of this member
matcher
matcher for this particular member

Description

This is used for struct_cmp() matchers.

INIT_MOCK_STRUCT_MATCHER_ENTRY(entry, type, member, matcher)

Parameters

entry
the struct mock_struct_matcher_entry to initialize
type
the struct being matched
member
the member of the struct being matched, used to calculate the offset
matcher
matcher to match that member

Description

Initializes entry to match type->member with matcher.

struct mock_param_capturer

used to capture parameter when matching

Definition

struct mock_param_capturer {
};

Members

Description

Use the associated helper macros to access relevant fields.

Example

struct mock_param_capturer * mock_int_capturer_create(struct test * test, struct mock_param_matcher * child_matcher)

creates a int parameter capturer

Parameters

struct test * test
associated test
struct mock_param_matcher * child_matcher
matcher used to match the integer

Description

The capturer will capture the value if the matcher is satisfied.

struct mock_param_capturer * mock_ptr_capturer_create(struct test * test, struct mock_param_matcher * child_matcher)

creates a generic pointer parameter capturer

Parameters

struct test * test
associated test
struct mock_param_matcher * child_matcher
matcher used to match the pointer

Description

The capturer will capture the value if the matcher is satisfied

capturer_to_matcher(capturer)

Parameters

capturer
the param capturer

Description

Use this function when passing a capturer into an EXPECT_CALL() where a matcher would be expected. See the example for struct mock_param_capturer.

ASSERT_PARAM_CAPTURED(test, capturer)

Parameters

test
the associated test
capturer
the param capturer

Description

See struct mock_param_capturer for an example.

mock_capturer_get(capturer, type)

Parameters

capturer
the param capturer
type
the type of the value

Description

See struct mock_param_capturer for an example.

INVOKE_REAL(test, func_name)

Parameters

test
associated test
func_name
name of the function

Description

See DEFINE_REDIRECT_MOCKABLE() for an example.

Return

struct mock_action that makes the associated mock method or function
call the original function definition of a redirect-mockable function.