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 *allocation;
  kunit_resource_free_t free;
};

Members

allocation
for the user to store arbitrary data.
free
a user supplied function to free the resource. Populated by kunit_alloc_resource().

Description

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

Example

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->allocation = kmalloc(params->size, params->gfp);

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

        return 0;
}

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

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

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

        res = kunit_alloc_resource(test, kunit_kmalloc_init,
                kunit_kmalloc_free, &params);
        if (res)
                return res->allocation;

        return NULL;
}
struct kunit_case

represents an individual test case.

Definition

struct kunit_case {
  void (*run_case)(struct kunit *test);
  const char *name;
};

Members

run_case
the function representing the actual test case.
name
the name of the test case.

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.

Example

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),
        {}
};
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.

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;
  struct dentry *debugfs;
  char *log;
};

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

used to register one or more struct kunit_suite with KUnit.

Parameters

...
variable arguments

Description

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

When builtin, KUnit tests are all run as late_initcalls; this means that they cannot test anything where tests must run at a different init phase. One significant restriction resulting from this is that KUnit cannot reliably test anything that is initialize in the late_init phase; another is that KUnit is useless to test things that need to be run in an earlier init phase.

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

TODO(brendanhiggins**google.com**): Don’t run all KUnit tests as late_initcalls. I have some future work planned to dispatch all KUnit tests from the same place, and at the very least to do so after everything else is definitely initialized.

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 each 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, const void * res, void * match_data)

Match a resource with the same instance.

Parameters

struct kunit * test
Test case to which the resource belongs.
const void * res
The data stored in kunit_resource->allocation.
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.

int kunit_resource_destroy(struct kunit * test, kunit_resource_match_t match, kunit_resource_free_t free, 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.
kunit_resource_free_t free
Must match free on the kunit_resource to free.
void * match_data
Data passed into match.

Description

Free the latest kunit_resource of test for which free matches the kunit_resource_free_t associated with the resource and for which match returns true.

Return

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

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.