Test API¶

This file documents all of the standard testing API.

enum kunit_status¶: Type of result for a test or test suite

Constants

KUNIT_SUCCESS: Denotes the test suite has not failed nor been skipped
KUNIT_FAILURE: Denotes the test has failed.
KUNIT_SKIPPED: Denotes the test has been skipped.

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)(struct kunit *test, const void *prev, char *desc);
    struct kunit_attributes attr;
    int (*param_init)(struct kunit *test);
    void (*param_exit)(struct kunit *test);
};

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.
attr: the attributes associated with the test
param_init: The init function to run before a parameterized test.
param_exit: The exit function to run after a parameterized test.

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¶

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

KUNIT_CASE_ATTR (test_name, attributes)

A helper for creating a struct kunit_case with attributes

Parameters

test_name: a reference to a test case function.
attributes: a reference to a struct kunit_attributes object containing test attributes

KUNIT_CASE_SLOW¶

KUNIT_CASE_SLOW (test_name)

A helper for creating a struct kunit_case with the slow attribute

Parameters

test_name: a reference to a test case function.

KUNIT_CASE_PARAM¶

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.

KUNIT_CASE_PARAM_ATTR¶

KUNIT_CASE_PARAM_ATTR (test_name, gen_params, attributes)

A helper for creating a parameterized struct kunit_case with attributes

Parameters

test_name: a reference to a test case function.
gen_params: a reference to a parameter generator function.
attributes: a reference to a struct kunit_attributes object containing test attributes

KUNIT_CASE_PARAM_WITH_INIT¶

KUNIT_CASE_PARAM_WITH_INIT (test_name, gen_params, init, exit)

Define a parameterized KUnit test case with custom param_init() and param_exit() functions.

Parameters

test_name: The function implementing the test case.
gen_params: The function to generate parameters for the test case.
init: A reference to the param_init() function to run before a parameterized test.
exit: A reference to the param_exit() function to run after a parameterized test.

Description

Provides the option to register param_init() and param_exit() functions. param_init/exit will be passed the parameterized test context and run once before and once after the parameterized test. The init function can be used to add resources to share between parameter runs, pass parameter arrays, and any other setup logic. The exit function can be used to clean up resources that were not managed by the parameterized test, and any other teardown logic.

Note

If you are registering a parameter array in param_init() with kunit_register_param_array() then you need to pass kunit_array_gen_params() to this as the generator function.

struct kunit_suite¶: describes a related collection of struct kunit_case

Definition:

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

Members

name: the name of the test. Purely informational.
suite_init: called once per test suite before the test cases.
suite_exit: called once per test suite after all test cases.
init: called before every test case.
exit: called after every test case.
test_cases: a null terminated array of test cases.
attr: the attributes associated with the test suite

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.

Note that exit and suite_exit will run even if init or suite_init fail: make sure they can handle any inconsistent state which may result.

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;
    struct kunit *parent;
    struct kunit_params params_array;
};

Members

priv: for user to store arbitrary data. Commonly used to pass data created in the init function (see struct kunit_suite).
parent: reference to the parent context of type struct kunit that can be used for storing shared resources.
params_array: for storing the parameter array.

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 exceptions are priv, parent and params_array which can be used by the test writer to store arbitrary data, access the parent context, and to store the parameter array, respectively.

kunit_test_suites¶

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. This is done by placing the array of struct kunit_suite * in the .kunit_test_suites ELF section.

When builtin, KUnit tests are all run via the executor at boot, and when built as a module, they run on module load.

kunit_test_init_section_suites¶

kunit_test_init_section_suites (__suites...)

used to register one or more struct kunit_suite containing init functions or init data.

Parameters

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

Description

This functions similar to kunit_test_suites() except that it compiles the list of suites during init phase.

This macro also suffixes the array and suite declarations it makes with _probe; so that modpost suppresses warnings about referencing init data for symbols named in this manner.

Note

these init tests are not able to be run after boot so there is no “run” debugfs file generated for these tests.

Also, do not mark the suite or test case structs with __initdata because they will be used after the init phase with debugfs.

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

Parameters

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

Description

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

Note that some internal context data is also allocated with GFP_KERNEL, regardless of the gfp passed in.

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

See kmalloc() and kunit_kmalloc_array() for more information.

Note that some internal context data is also allocated with GFP_KERNEL, regardless of the gfp passed in.

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_array() for more information.

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

Parameters

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

Description

See kcalloc() and kunit_kmalloc_array() for more information.

void kunit_kfree_const(struct kunit *test, const void *x)¶: conditionally free test managed memory

Parameters

struct kunit *test: The test context object.
const void *x: pointer to the memory

Description

Calls kunit_kfree() only if x is not in .rodata section. See kunit_kstrdup_const() for more information.

char *kunit_kstrdup(struct kunit *test, const char *str, gfp_t gfp)¶: Duplicates a string into a test managed allocation.

Parameters

struct kunit *test: The test context object.
const char *str: The NULL-terminated string to duplicate.
gfp_t gfp: flags passed to underlying kmalloc().

Description

See kstrdup() and kunit_kmalloc_array() for more information.

const char *kunit_kstrdup_const(struct kunit *test, const char *str, gfp_t gfp)¶: Conditionally duplicates a string into a test managed allocation.

Parameters

struct kunit *test: The test context object.
const char *str: The NULL-terminated string to duplicate.
gfp_t gfp: flags passed to underlying kmalloc().

Description

Calls kunit_kstrdup() only if str is not in the rodata section. Must be freed with kunit_kfree_const() -- not kunit_kfree(). See kstrdup_const() and kunit_kmalloc_array() for more information.

int kunit_attach_mm(void)¶: Create and attach a new mm if it doesn’t already exist.

Parameters

void: no arguments

Description

Allocates a struct mm_struct and attaches it to current. In most cases, call kunit_vm_mmap() without calling kunit_attach_mm() directly. Only necessary when code under test accesses the mm before executing the mmap (e.g., to perform additional initialization beforehand).

Return

0 on success, -errno on failure.

unsigned long kunit_vm_mmap(struct kunit *test, struct file *file, unsigned long addr, unsigned long len, unsigned long prot, unsigned long flag, unsigned long offset)¶: Allocate KUnit-tracked vm_mmap() area

Parameters

struct kunit *test: The test context object.
struct file *file: struct file pointer to map from, if any
unsigned long addr: desired address, if any
unsigned long len: how many bytes to allocate
unsigned long prot: mmap PROT_* bits
unsigned long flag: mmap flags
unsigned long offset: offset into file to start mapping from.

Description

See vm_mmap() for more information.

kunit_mark_skipped¶

kunit_mark_skipped (test, fmt, ...)

Marks test as skipped

Parameters

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

Description

Marks the test as skipped. fmt is given output as the test status comment, typically the reason the test was skipped.

Test execution continues after kunit_mark_skipped() is called.

kunit_skip¶

kunit_skip (test, fmt, ...)

Marks test as skipped

Parameters

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

Description

Skips the test. fmt is given output as the test status comment, typically the reason the test was skipped.

Test execution is halted after kunit_skip() is called.

kunit_info¶

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¶

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¶

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¶

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¶

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¶

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¶

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¶

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¶

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¶

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¶

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¶

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¶

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¶

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¶

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¶

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¶

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

KUNIT_EXPECT_MEMEQ (test, left, right, size)

Expects that the first size bytes of left and right are equal.

Parameters

test: The test context object.
left: An arbitrary expression that evaluates to the specified size.
right: An arbitrary expression that evaluates to the specified size.
size: Number of bytes compared.

Description

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

Although this expectation works for any memory block, it is not recommended for comparing more structured data, such as structs. This expectation is recommended for comparing, for example, data arrays.

KUNIT_EXPECT_MEMNEQ¶

KUNIT_EXPECT_MEMNEQ (test, left, right, size)

Expects that the first size bytes of left and right are not equal.

Parameters

test: The test context object.
left: An arbitrary expression that evaluates to the specified size.
right: An arbitrary expression that evaluates to the specified size.
size: Number of bytes compared.

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, memcmp((left), (right), (size))). See KUNIT_EXPECT_TRUE() for more information.

Although this expectation works for any memory block, it is not recommended for comparing more structured data, such as structs. This expectation is recommended for comparing, for example, data arrays.

KUNIT_EXPECT_NULL¶

KUNIT_EXPECT_NULL (test, ptr)

Expects that ptr is null.

Parameters

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

Description

Sets an expectation that the value that ptr evaluates to is null. This is semantically equivalent to KUNIT_EXPECT_PTR_EQ(test, ptr, NULL). See KUNIT_EXPECT_TRUE() for more information.

KUNIT_EXPECT_NOT_NULL¶

KUNIT_EXPECT_NOT_NULL (test, ptr)

Expects that ptr is not null.

Parameters

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

Description

Sets an expectation that the value that ptr evaluates to is not null. This is semantically equivalent to KUNIT_EXPECT_PTR_NE(test, ptr, NULL). See KUNIT_EXPECT_TRUE() for more information.

KUNIT_EXPECT_NOT_ERR_OR_NULL¶

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

KUNIT_FAIL_AND_ABORT (test, fmt, ...)

Always causes a test to fail and abort 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 assertion that always fails. In other words, it always results in a failed assertion, and consequently always causes the test case to fail and abort when evaluated. See KUNIT_ASSERT_TRUE() for more information.

KUNIT_ASSERT_TRUE¶

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¶

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¶

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¶

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¶

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¶

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¶

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¶

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¶

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¶

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¶

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¶

KUNIT_ASSERT_STRNEQ (test, left, right)

An assertion 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 assertion 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_MEMEQ¶

KUNIT_ASSERT_MEMEQ (test, left, right, size)

Asserts that the first size bytes of left and right are equal.

Parameters

test: The test context object.
left: An arbitrary expression that evaluates to the specified size.
right: An arbitrary expression that evaluates to the specified size.
size: Number of bytes compared.

Description

Sets an assertion that the values that left and right evaluate to are equal. This is semantically equivalent to KUNIT_ASSERT_TRUE(test, !memcmp((left), (right), (size))). See KUNIT_ASSERT_TRUE() for more information.

Although this assertion works for any memory block, it is not recommended for comparing more structured data, such as structs. This assertion is recommended for comparing, for example, data arrays.

KUNIT_ASSERT_MEMNEQ¶

KUNIT_ASSERT_MEMNEQ (test, left, right, size)

Asserts that the first size bytes of left and right are not equal.

Parameters

test: The test context object.
left: An arbitrary expression that evaluates to the specified size.
right: An arbitrary expression that evaluates to the specified size.
size: Number of bytes compared.

Description

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

Although this assertion works for any memory block, it is not recommended for comparing more structured data, such as structs. This assertion is recommended for comparing, for example, data arrays.

KUNIT_ASSERT_NULL¶

KUNIT_ASSERT_NULL (test, ptr)

Asserts that pointers ptr is null.

Parameters

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

Description

Sets an assertion that the values that ptr evaluates to is null. This is the same as KUNIT_EXPECT_NULL(), except it causes an assertion failure (see KUNIT_ASSERT_TRUE()) when the assertion is not met.

KUNIT_ASSERT_NOT_NULL¶

KUNIT_ASSERT_NOT_NULL (test, ptr)

Asserts that pointers ptr is not null.

Parameters

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

Description

Sets an assertion that the values that ptr evaluates to is not null. This is the same as KUNIT_EXPECT_NOT_NULL(), except it causes an assertion failure (see KUNIT_ASSERT_TRUE()) when the assertion is not met.

KUNIT_ASSERT_NOT_ERR_OR_NULL¶

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¶

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.

KUNIT_ARRAY_PARAM_DESC¶

KUNIT_ARRAY_PARAM_DESC (name, array, desc_member)

Define test parameter generator from an array.

Parameters

name: prefix for the test parameter generator function.
array: array of test parameters.
desc_member: structure member from array element to use as description

Description

Define function name_gen_params which uses array to generate parameters.

kunit_register_params_array¶

kunit_register_params_array (test, array, param_count, get_desc)

Register parameter array for a KUnit test.

Parameters

test: The KUnit test structure to which parameters will be added.
array: An array of test parameters.
param_count: Number of parameters.
get_desc: Function that generates a string description for a given parameter element.

Description

This macro initializes the test’s parameter array data, storing information including the parameter array, its count, the element size, and the parameter description function within test->params_array.

Note

If using this macro in param_init(), kunit_array_gen_params() will then need to be manually provided as the parameter generator function to KUNIT_CASE_PARAM_WITH_INIT(). kunit_array_gen_params() is a KUnit function that uses the registered array to generate parameters

kunit_warning_suppress¶

kunit_warning_suppress (test)

Suppress WARN*() backtraces for the duration of a block.

Parameters

test: The test context object.

Description

Scoped form of the suppression API. Suppression starts when the block is entered and ends automatically when the block exits through any path. See the section comment above for the cleanup guarantees on each exit path. Fails the test if suppression is already active; nesting is not supported.

The warning count can be checked inside the block via KUNIT_EXPECT_SUPPRESSED_WARNING_COUNT(). The handle is not accessible after the block exits.

Example:

kunit_warning_suppress(test) {
    trigger_warning();
    KUNIT_EXPECT_SUPPRESSED_WARNING_COUNT(test, 1);
}

KUNIT_SUPPRESSED_WARNING_COUNT¶

KUNIT_SUPPRESSED_WARNING_COUNT ()

Returns the suppressed warning count.

Description

Returns the number of WARN*() calls suppressed since the current suppression block started, or 0 if the handle is NULL. Usable inside a kunit_warning_suppress() block.

KUNIT_EXPECT_SUPPRESSED_WARNING_COUNT¶

KUNIT_EXPECT_SUPPRESSED_WARNING_COUNT (test, expected)

Sets an expectation that the suppressed warning count equals expected.

Parameters

test: The test context object.
expected: an expression that evaluates to the expected warning count.

Description

Sets an expectation that the number of suppressed WARN*() calls equals expected. This is semantically equivalent to KUNIT_EXPECT_EQ(test, KUNIT_SUPPRESSED_WARNING_COUNT(), expected). See KUNIT_EXPECT_EQ() for more information.

KUNIT_ASSERT_SUPPRESSED_WARNING_COUNT¶

KUNIT_ASSERT_SUPPRESSED_WARNING_COUNT (test, expected)

Sets an assertion that the suppressed warning count equals expected.

Parameters

test: The test context object.
expected: an expression that evaluates to the expected warning count.

Description

Sets an assertion that the number of suppressed WARN*() calls equals expected. This is the same as KUNIT_EXPECT_SUPPRESSED_WARNING_COUNT(), except it causes an assertion failure (see KUNIT_ASSERT_TRUE()) when the assertion is not met.

The Linux Kernel

Contents

This Page

Test API¶