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 KUNIT_T *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 KUNIT_T *test, int expected);
struct mock_param_matcher *int_ne(struct KUNIT_T *test, int expected);
struct mock_param_matcher *int_lt(struct KUNIT_T *test, int expected);
struct mock_param_matcher *int_le(struct KUNIT_T *test, int expected);
struct mock_param_matcher *int_gt(struct KUNIT_T *test, int expected);
struct mock_param_matcher *int_ge(struct KUNIT_T *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¶

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¶

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¶

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¶

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

Description

// 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 KUNIT_T *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

Description

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

Description

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

Return

the same struct mock_expectation passed in

InSequence¶

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

Description

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¶

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¶

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...: parameters of the method

Description

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

DECLARE_STRUCT_CLASS_MOCK_VOID_RETURN¶

DECLARE_STRUCT_CLASS_MOCK_VOID_RETURN (name, struct_name, param_types...)

Parameters

name: method name
struct_name: name of the class/struct
param_types...: parameters of the method

Description

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

DECLARE_STRUCT_CLASS_MOCK_INIT¶

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¶

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¶

DEFINE_REDIRECT_MOCKABLE (name, return_type, param_types...)

Parameters

name: name of the function
return_type: return type of the function
param_types...: parameter types of the function

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().

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 KUNIT_T *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;
}

Example

DEFINE_STRUCT_CLASS_MOCK¶

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...: parameters to method to be created.

Description

See EXPECT_CALL() for example usage.

DEFINE_STRUCT_CLASS_MOCK_VOID_RETURN¶

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...: parameters to method to be created.

Description

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

DEFINE_STRUCT_CLASS_MOCK_INIT¶

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¶

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¶

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¶

__mockable ()

A function decorator that allows the function to be mocked.

Parameters

Example

Description

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

__visible_for_testing¶

__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¶

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. .. code-block::c

static int some_test(struct KUNIT_T *test) {

// imagine a mocked function: int add(int a, int b) struct mock_param_capturer *capturer =

mock_int_capturer_create(test, any(test));

EXPECT_CALL(add(any(test), capturer_to_matcher(capturer))); ASSERT_PARAM_CAPTURED(test, capturer);

int captured_value = mock_capturer_get(capturer, int);

}

Example

struct mock_param_capturer *mock_int_capturer_create(struct KUNIT_T *test, struct mock_param_matcher *child_matcher)¶: creates a int parameter capturer

Parameters

struct KUNIT_T *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 KUNIT_T *test, struct mock_param_matcher *child_matcher)¶: creates a generic pointer parameter capturer

Parameters

struct KUNIT_T *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_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¶

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¶

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¶

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.