Test API¶

This file documents all of the standard testing API excluding mocking or mocking related features.

struct kunit_resource¶: represents a test managed resource

Definition

struct kunit_resource {
  void *data;
  const char *name;
  kunit_resource_free_t free;
};

Members

data: for the user to store arbitrary data.
name: optional name
free: a user supplied function to free the resource. Populated by kunit_resource_alloc().

Description

Represents a test managed resource, a resource which will automatically be cleaned up at the end of a test case.

Resources are reference counted so if a resource is retrieved via kunit_alloc_and_get_resource() or kunit_find_resource(), we need to call kunit_put_resource() to reduce the resource reference count when finished with it. Note that kunit_alloc_resource() does not require a kunit_resource_put() because it does not retrieve the resource itself.

struct kunit_kmalloc_params {
        size_t size;
        gfp_t gfp;
};

static int kunit_kmalloc_init(struct kunit_resource *res, void *context)
{
        struct kunit_kmalloc_params *params = context;
        res->data = kmalloc(params->size, params->gfp);

        if (!res->data)
                return -ENOMEM;

        return 0;
}

static void kunit_kmalloc_free(struct kunit_resource *res)
{
        kfree(res->data);
}

void *kunit_kmalloc(struct kunit *test, size_t size, gfp_t gfp)
{
        struct kunit_kmalloc_params params;

        params.size = size;
        params.gfp = gfp;

        return kunit_alloc_resource(test, kunit_kmalloc_init,
                kunit_kmalloc_free, &params);
}

Resources can also be named, with lookup/removal done on a name basis also. kunit_add_named_resource(), kunit_find_named_resource() and kunit_destroy_named_resource(). Resource names must be unique within the test instance.

Example

struct kunit_case¶: represents an individual test case.

Definition

struct kunit_case {
  void (*run_case)(struct kunit *test);
  const char *name;
  const void* (*generate_params)(const void *prev, char *desc);
};

Members

run_case: the function representing the actual test case.
name: the name of the test case.
generate_params: the generator function for parameterized tests.

Description

A test case is a function with the signature, void (*)(struct kunit *) that makes expectations and assertions (see KUNIT_EXPECT_TRUE() and KUNIT_ASSERT_TRUE()) about code under test. Each test case is associated with a struct kunit_suite and will be run after the suite’s init function and followed by the suite’s exit function.

A test case should be static and should only be created with the KUNIT_CASE() macro; additionally, every array of test cases should be terminated with an empty test case.

void add_test_basic(struct kunit *test)
{
        KUNIT_EXPECT_EQ(test, 1, add(1, 0));
        KUNIT_EXPECT_EQ(test, 2, add(1, 1));
        KUNIT_EXPECT_EQ(test, 0, add(-1, 1));
        KUNIT_EXPECT_EQ(test, INT_MAX, add(0, INT_MAX));
        KUNIT_EXPECT_EQ(test, -1, add(INT_MAX, INT_MIN));
}

static struct kunit_case example_test_cases[] = {
        KUNIT_CASE(add_test_basic),
        {}
};

Example

KUNIT_CASE(test_name)¶: A helper for creating a struct kunit_case

Parameters

test_name: a reference to a test case function.

Description

Takes a symbol for a function representing a test case and creates a struct kunit_case object from it. See the documentation for struct kunit_case for an example on how to use it.

KUNIT_CASE_PARAM(test_name, gen_params)¶: A helper for creation a parameterized struct kunit_case

Parameters

test_name: a reference to a test case function.
gen_params: a reference to a parameter generator function.

Description

The generator function:

const void* gen_params(const void *prev, char *desc)

is used to lazily generate a series of arbitrarily typed values that fit into a void*. The argument prev is the previously returned value, which should be used to derive the next value; prev is set to NULL on the initial generator call. When no more values are available, the generator must return NULL. Optionally write a string into desc (size of KUNIT_PARAM_DESC_SIZE) describing the parameter.

struct kunit_suite¶: describes a related collection of struct kunit_case

Definition

struct kunit_suite {
  const char name[256];
  int (*init)(struct kunit *test);
  void (*exit)(struct kunit *test);
  struct kunit_case *test_cases;
};

Members

name: the name of the test. Purely informational.
init: called before every test case.
exit: called after every test case.
test_cases: a null terminated array of test cases.

Description

A kunit_suite is a collection of related struct kunit_case s, such that init is called before every test case and exit is called after every test case, similar to the notion of a test fixture or a test class in other unit testing frameworks like JUnit or Googletest.

Every struct kunit_case must be associated with a kunit_suite for KUnit to run it.

struct kunit¶: represents a running instance of a test.

Definition

struct kunit {
  void *priv;
};

Members

priv: for user to store arbitrary data. Commonly used to pass data created in the init function (see struct kunit_suite).

Description

Used to store information about the current context under which the test is running. Most of this data is private and should only be accessed indirectly via public functions; the one exception is priv which can be used by the test writer to store arbitrary data.

kunit_test_suites_for_module(__suites)¶: used to register one or more struct kunit_suite with KUnit.

Parameters

__suites: a statically allocated list of struct kunit_suite.

Description

Registers __suites with the test framework. See struct kunit_suite for more information.

If a test suite is built-in, module_init() gets translated into an initcall which we don’t want as the idea is that for builtins the executor will manage execution. So ensure we do not define module_{init|exit} functions for the builtin case when registering suites via kunit_test_suites() below.

kunit_test_suites(__suites…)¶: used to register one or more struct kunit_suite with KUnit.

Parameters

__suites...: a statically allocated list of struct kunit_suite.

Description

Registers suites with the test framework. See struct kunit_suite for more information.

When builtin, KUnit tests are all run via executor; this is done by placing the array of struct kunit_suite * in the .kunit_test_suites ELF section.

An alternative is to build the tests as a module. Because modules do not support multiple initcall()s, we need to initialize an array of suites for a module.

void kunit_get_resource(struct kunit_resource *res)¶: Hold resource for use. Should not need to be used by most users as we automatically get resources retrieved by kunit_find_resource*().

Parameters

struct kunit_resource *res: resource

void kunit_put_resource(struct kunit_resource *res)¶: When caller is done with retrieved resource, kunit_put_resource() should be called to drop reference count. The resource list maintains a reference count on resources, so if no users are utilizing a resource and it is removed from the resource list, it will be freed via the associated free function (if any). Only needs to be used if we alloc_and_get() or find() resource.

Parameters

struct kunit_resource *res: resource

int kunit_add_resource(struct kunit *test, kunit_resource_init_t init, kunit_resource_free_t free, struct kunit_resource *res, void *data)¶: Add a test managed resource.

Parameters

struct kunit *test: The test context object.
kunit_resource_init_t init: a user-supplied function to initialize the result (if needed). If none is supplied, the resource data value is simply set to data. If an init function is supplied, data is passed to it instead.
kunit_resource_free_t free: a user-supplied function to free the resource (if needed).
struct kunit_resource *res: The resource.
void *data: value to pass to init function or set in resource data field.

int kunit_add_named_resource(struct kunit *test, kunit_resource_init_t init, kunit_resource_free_t free, struct kunit_resource *res, const char *name, void *data)¶: Add a named test managed resource.

Parameters

struct kunit *test: The test context object.
kunit_resource_init_t init: a user-supplied function to initialize the resource data, if needed.
kunit_resource_free_t free: a user-supplied function to free the resource data, if needed.
struct kunit_resource *res: The resource.
const char *name: name to be set for resource.
void *data: value to pass to init function or set in resource data field.

void * kunit_alloc_resource(struct kunit *test, kunit_resource_init_t init, kunit_resource_free_t free, gfp_t internal_gfp, void *context)¶: Allocates a test managed resource.

Parameters

struct kunit *test: The test context object.
kunit_resource_init_t init: a user supplied function to initialize the resource.
kunit_resource_free_t free: a user supplied function to free the resource.
gfp_t internal_gfp: gfp to use for internal allocations, if unsure, use GFP_KERNEL
void *context: for the user to pass in arbitrary data to the init function.

Description

Allocates a test managed resource, a resource which will automatically be cleaned up at the end of a test case. See struct kunit_resource for an example.

Note

KUnit needs to allocate memory for a kunit_resource object. You must specify an internal_gfp that is compatible with the use context of your resource.

bool kunit_resource_instance_match(struct kunit *test, struct kunit_resource *res, void *match_data)¶: Match a resource with the same instance.

Parameters

struct kunit *test: Test case to which the resource belongs.
struct kunit_resource *res: The resource.
void *match_data: The resource pointer to match against.

Description

An instance of kunit_resource_match_t that matches a resource whose allocation matches match_data.

bool kunit_resource_name_match(struct kunit *test, struct kunit_resource *res, void *match_name)¶: Match a resource with the same name.

Parameters

struct kunit *test: Test case to which the resource belongs.
struct kunit_resource *res: The resource.
void *match_name: The name to match against.

struct kunit_resource * kunit_find_resource(struct kunit *test, kunit_resource_match_t match, void *match_data)¶: Find a resource using match function/data.

Parameters

struct kunit *test: Test case to which the resource belongs.
kunit_resource_match_t match: match function to be applied to resources/match data.
void *match_data: data to be used in matching.

struct kunit_resource * kunit_find_named_resource(struct kunit *test, const char *name)¶: Find a resource using match name.

Parameters

struct kunit *test: Test case to which the resource belongs.
const char *name: match name.

int kunit_destroy_resource(struct kunit *test, kunit_resource_match_t match, void *match_data)¶: Find a kunit_resource and destroy it.

Parameters

struct kunit *test: Test case to which the resource belongs.
kunit_resource_match_t match: Match function. Returns whether a given resource matches match_data.
void *match_data: Data passed into match.

Return

0 if kunit_resource is found and freed, -ENOENT if not found.

void kunit_remove_resource(struct kunit *test, struct kunit_resource *res)¶: remove resource from resource list associated with test.

Parameters

struct kunit *test: The test context object.
struct kunit_resource *res: The resource to be removed.

Description

Note that the resource will not be immediately freed since it is likely the caller has a reference to it via alloc_and_get() or find(); in this case a final call to kunit_put_resource() is required.

void * kunit_kmalloc(struct kunit *test, size_t size, gfp_t gfp)¶: Like kmalloc() except the allocation is test managed.

Parameters

struct kunit *test: The test context object.
size_t size: The size in bytes of the desired memory.
gfp_t gfp: flags passed to underlying kmalloc().

Description

Just like kmalloc(…), except the allocation is managed by the test case and is automatically cleaned up after the test case concludes. See struct kunit_resource for more information.

void kunit_kfree(struct kunit *test, const void *ptr)¶: Like kfree except for allocations managed by KUnit.

Parameters

struct kunit *test: The test case to which the resource belongs.
const void *ptr: The memory allocation to free.

void * kunit_kzalloc(struct kunit *test, size_t size, gfp_t gfp)¶: Just like kunit_kmalloc(), but zeroes the allocation.

Parameters

struct kunit *test: The test context object.
size_t size: The size in bytes of the desired memory.
gfp_t gfp: flags passed to underlying kmalloc().

Description

See kzalloc() and kunit_kmalloc() for more information.

kunit_info(test, fmt, …)¶: Prints an INFO level message associated with test.

Parameters

test: The test context object.
fmt: A printk() style format string.
...: variable arguments

Description

Prints an info level message associated with the test suite being run. Takes a variable number of format parameters just like printk().

kunit_warn(test, fmt, …)¶: Prints a WARN level message associated with test.

Parameters

test: The test context object.
fmt: A printk() style format string.
...: variable arguments

Description

Prints a warning level message.

kunit_err(test, fmt, …)¶: Prints an ERROR level message associated with test.

Parameters

test: The test context object.
fmt: A printk() style format string.
...: variable arguments

Description

Prints an error level message.

KUNIT_SUCCEED(test)¶: A no-op expectation. Only exists for code clarity.

Parameters

test: The test context object.

Description

The opposite of KUNIT_FAIL(), it is an expectation that cannot fail. In other words, it does nothing and only exists for code clarity. See KUNIT_EXPECT_TRUE() for more information.

KUNIT_FAIL(test, fmt, …)¶: Always causes a test to fail when evaluated.

Parameters

test: The test context object.
fmt: an informational message to be printed when the assertion is made.
...: string format arguments.

Description

The opposite of KUNIT_SUCCEED(), it is an expectation that always fails. In other words, it always results in a failed expectation, and consequently always causes the test case to fail when evaluated. See KUNIT_EXPECT_TRUE() for more information.

KUNIT_EXPECT_TRUE(test, condition)¶: Causes a test failure when the expression is not true.

Parameters

test: The test context object.
condition: an arbitrary boolean expression. The test fails when this does not evaluate to true.

Description

This and expectations of the form KUNIT_EXPECT_* will cause the test case to fail when the specified condition is not met; however, it will not prevent the test case from continuing to run; this is otherwise known as an expectation failure.

KUNIT_EXPECT_FALSE(test, condition)¶: Makes a test failure when the expression is not false.

Parameters

test: The test context object.
condition: an arbitrary boolean expression. The test fails when this does not evaluate to false.

Description

Sets an expectation that condition evaluates to false. See KUNIT_EXPECT_TRUE() for more information.

KUNIT_EXPECT_EQ(test, left, right)¶: Sets an expectation that left and right are equal.

Parameters

test: The test context object.
left: an arbitrary expression that evaluates to a primitive C type.
right: an arbitrary expression that evaluates to a primitive C type.

Description

Sets an expectation that the values that left and right evaluate to are equal. This is semantically equivalent to KUNIT_EXPECT_TRUE(test, (left) == (right)). See KUNIT_EXPECT_TRUE() for more information.

KUNIT_EXPECT_PTR_EQ(test, left, right)¶: Expects that pointers left and right are equal.

Parameters

test: The test context object.
left: an arbitrary expression that evaluates to a pointer.
right: an arbitrary expression that evaluates to a pointer.

Description

Sets an expectation that the values that left and right evaluate to are equal. This is semantically equivalent to KUNIT_EXPECT_TRUE(test, (left) == (right)). See KUNIT_EXPECT_TRUE() for more information.

KUNIT_EXPECT_NE(test, left, right)¶: An expectation that left and right are not equal.

Parameters

test: The test context object.
left: an arbitrary expression that evaluates to a primitive C type.
right: an arbitrary expression that evaluates to a primitive C type.

Description

Sets an expectation that the values that left and right evaluate to are not equal. This is semantically equivalent to KUNIT_EXPECT_TRUE(test, (left) != (right)). See KUNIT_EXPECT_TRUE() for more information.

KUNIT_EXPECT_PTR_NE(test, left, right)¶: Expects that pointers left and right are not equal.

Parameters

test: The test context object.
left: an arbitrary expression that evaluates to a pointer.
right: an arbitrary expression that evaluates to a pointer.

Description

Sets an expectation that the values that left and right evaluate to are not equal. This is semantically equivalent to KUNIT_EXPECT_TRUE(test, (left) != (right)). See KUNIT_EXPECT_TRUE() for more information.

KUNIT_EXPECT_LT(test, left, right)¶: An expectation that left is less than right.

Parameters

test: The test context object.
left: an arbitrary expression that evaluates to a primitive C type.
right: an arbitrary expression that evaluates to a primitive C type.

Description

Sets an expectation that the value that left evaluates to is less than the value that right evaluates to. This is semantically equivalent to KUNIT_EXPECT_TRUE(test, (left) < (right)). See KUNIT_EXPECT_TRUE() for more information.

KUNIT_EXPECT_LE(test, left, right)¶: Expects that left is less than or equal to right.

Parameters

test: The test context object.
left: an arbitrary expression that evaluates to a primitive C type.
right: an arbitrary expression that evaluates to a primitive C type.

Description

Sets an expectation that the value that left evaluates to is less than or equal to the value that right evaluates to. Semantically this is equivalent to KUNIT_EXPECT_TRUE(test, (left) <= (right)). See KUNIT_EXPECT_TRUE() for more information.

KUNIT_EXPECT_GT(test, left, right)¶: An expectation that left is greater than right.

Parameters

test: The test context object.
left: an arbitrary expression that evaluates to a primitive C type.
right: an arbitrary expression that evaluates to a primitive C type.

Description

Sets an expectation that the value that left evaluates to is greater than the value that right evaluates to. This is semantically equivalent to KUNIT_EXPECT_TRUE(test, (left) > (right)). See KUNIT_EXPECT_TRUE() for more information.

KUNIT_EXPECT_GE(test, left, right)¶: Expects that left is greater than or equal to right.

Parameters

test: The test context object.
left: an arbitrary expression that evaluates to a primitive C type.
right: an arbitrary expression that evaluates to a primitive C type.

Description

Sets an expectation that the value that left evaluates to is greater than the value that right evaluates to. This is semantically equivalent to KUNIT_EXPECT_TRUE(test, (left) >= (right)). See KUNIT_EXPECT_TRUE() for more information.

KUNIT_EXPECT_STREQ(test, left, right)¶: Expects that strings left and right are equal.

Parameters

test: The test context object.
left: an arbitrary expression that evaluates to a null terminated string.
right: an arbitrary expression that evaluates to a null terminated string.

Description

Sets an expectation that the values that left and right evaluate to are equal. This is semantically equivalent to KUNIT_EXPECT_TRUE(test, !strcmp((left), (right))). See KUNIT_EXPECT_TRUE() for more information.

KUNIT_EXPECT_STRNEQ(test, left, right)¶: Expects that strings left and right are not equal.

Parameters

test: The test context object.
left: an arbitrary expression that evaluates to a null terminated string.
right: an arbitrary expression that evaluates to a null terminated string.

Description

Sets an expectation that the values that left and right evaluate to are not equal. This is semantically equivalent to KUNIT_EXPECT_TRUE(test, strcmp((left), (right))). See KUNIT_EXPECT_TRUE() for more information.

KUNIT_EXPECT_NOT_ERR_OR_NULL(test, ptr)¶: Expects that ptr is not null and not err.

Parameters

test: The test context object.
ptr: an arbitrary pointer.

Description

Sets an expectation that the value that ptr evaluates to is not null and not an errno stored in a pointer. This is semantically equivalent to KUNIT_EXPECT_TRUE(test, !IS_ERR_OR_NULL(ptr)). See KUNIT_EXPECT_TRUE() for more information.

KUNIT_ASSERT_TRUE(test, condition)¶: Sets an assertion that condition is true.

Parameters

test: The test context object.
condition: an arbitrary boolean expression. The test fails and aborts when this does not evaluate to true.

Description

This and assertions of the form KUNIT_ASSERT_* will cause the test case to fail and immediately abort when the specified condition is not met. Unlike an expectation failure, it will prevent the test case from continuing to run; this is otherwise known as an assertion failure.

KUNIT_ASSERT_FALSE(test, condition)¶: Sets an assertion that condition is false.

Parameters

test: The test context object.
condition: an arbitrary boolean expression.

Description

Sets an assertion that the value that condition evaluates to is false. This is the same as KUNIT_EXPECT_FALSE(), except it causes an assertion failure (see KUNIT_ASSERT_TRUE()) when the assertion is not met.

KUNIT_ASSERT_EQ(test, left, right)¶: Sets an assertion that left and right are equal.

Parameters

test: The test context object.
left: an arbitrary expression that evaluates to a primitive C type.
right: an arbitrary expression that evaluates to a primitive C type.

Description

Sets an assertion that the values that left and right evaluate to are equal. This is the same as KUNIT_EXPECT_EQ(), except it causes an assertion failure (see KUNIT_ASSERT_TRUE()) when the assertion is not met.

KUNIT_ASSERT_PTR_EQ(test, left, right)¶: Asserts that pointers left and right are equal.

Parameters

test: The test context object.
left: an arbitrary expression that evaluates to a pointer.
right: an arbitrary expression that evaluates to a pointer.

Description

Sets an assertion that the values that left and right evaluate to are equal. This is the same as KUNIT_EXPECT_EQ(), except it causes an assertion failure (see KUNIT_ASSERT_TRUE()) when the assertion is not met.

KUNIT_ASSERT_NE(test, left, right)¶: An assertion that left and right are not equal.

Parameters

test: The test context object.
left: an arbitrary expression that evaluates to a primitive C type.
right: an arbitrary expression that evaluates to a primitive C type.

Description

Sets an assertion that the values that left and right evaluate to are not equal. This is the same as KUNIT_EXPECT_NE(), except it causes an assertion failure (see KUNIT_ASSERT_TRUE()) when the assertion is not met.

KUNIT_ASSERT_PTR_NE(test, left, right)¶: Asserts that pointers left and right are not equal. KUNIT_ASSERT_PTR_EQ() - Asserts that pointers left and right are equal.

Parameters

test: The test context object.
left: an arbitrary expression that evaluates to a pointer.
right: an arbitrary expression that evaluates to a pointer.

Description

Sets an assertion that the values that left and right evaluate to are not equal. This is the same as KUNIT_EXPECT_NE(), except it causes an assertion failure (see KUNIT_ASSERT_TRUE()) when the assertion is not met.

KUNIT_ASSERT_LT(test, left, right)¶: An assertion that left is less than right.

Parameters

test: The test context object.
left: an arbitrary expression that evaluates to a primitive C type.
right: an arbitrary expression that evaluates to a primitive C type.

Description

Sets an assertion that the value that left evaluates to is less than the value that right evaluates to. This is the same as KUNIT_EXPECT_LT(), except it causes an assertion failure (see KUNIT_ASSERT_TRUE()) when the assertion is not met.

KUNIT_ASSERT_LE(test, left, right)¶: An assertion that left is less than or equal to right.

Parameters

test: The test context object.
left: an arbitrary expression that evaluates to a primitive C type.
right: an arbitrary expression that evaluates to a primitive C type.

Description

Sets an assertion that the value that left evaluates to is less than or equal to the value that right evaluates to. This is the same as KUNIT_EXPECT_LE(), except it causes an assertion failure (see KUNIT_ASSERT_TRUE()) when the assertion is not met.

KUNIT_ASSERT_GT(test, left, right)¶: An assertion that left is greater than right.

Parameters

test: The test context object.
left: an arbitrary expression that evaluates to a primitive C type.
right: an arbitrary expression that evaluates to a primitive C type.

Description

Sets an assertion that the value that left evaluates to is greater than the value that right evaluates to. This is the same as KUNIT_EXPECT_GT(), except it causes an assertion failure (see KUNIT_ASSERT_TRUE()) when the assertion is not met.

KUNIT_ASSERT_GE(test, left, right)¶: Assertion that left is greater than or equal to right.

Parameters

test: The test context object.
left: an arbitrary expression that evaluates to a primitive C type.
right: an arbitrary expression that evaluates to a primitive C type.

Description

Sets an assertion that the value that left evaluates to is greater than the value that right evaluates to. This is the same as KUNIT_EXPECT_GE(), except it causes an assertion failure (see KUNIT_ASSERT_TRUE()) when the assertion is not met.

KUNIT_ASSERT_STREQ(test, left, right)¶: An assertion that strings left and right are equal.

Parameters

test: The test context object.
left: an arbitrary expression that evaluates to a null terminated string.
right: an arbitrary expression that evaluates to a null terminated string.

Description

Sets an assertion that the values that left and right evaluate to are equal. This is the same as KUNIT_EXPECT_STREQ(), except it causes an assertion failure (see KUNIT_ASSERT_TRUE()) when the assertion is not met.

KUNIT_ASSERT_STRNEQ(test, left, right)¶: Expects that strings left and right are not equal.

Parameters

test: The test context object.
left: an arbitrary expression that evaluates to a null terminated string.
right: an arbitrary expression that evaluates to a null terminated string.

Description

Sets an expectation that the values that left and right evaluate to are not equal. This is semantically equivalent to KUNIT_ASSERT_TRUE(test, strcmp((left), (right))). See KUNIT_ASSERT_TRUE() for more information.

KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ptr)¶: Assertion that ptr is not null and not err.

Parameters

test: The test context object.
ptr: an arbitrary pointer.

Description

Sets an assertion that the value that ptr evaluates to is not null and not an errno stored in a pointer. This is the same as KUNIT_EXPECT_NOT_ERR_OR_NULL(), except it causes an assertion failure (see KUNIT_ASSERT_TRUE()) when the assertion is not met.

KUNIT_ARRAY_PARAM(name, array, get_desc)¶: Define test parameter generator from an array.

Parameters

name: prefix for the test parameter generator function.
array: array of test parameters.
get_desc: function to convert param to description; NULL to use default

Description

Define function name_gen_params which uses array to generate parameters.