Test API¶
This file documents all of the standard testing API excluding mocking or mocking related features.
-
struct KUNIT_RESOURCE_T¶
represents a test managed resource
Definition
struct KUNIT_RESOURCE_T {
void *allocation;
void (*free)(struct KUNIT_RESOURCE_T *res);
};
Members
allocation
for the user to store arbitrary data.
free
a user supplied function to free the resource. Populated by
test_alloc_resource()
.
Description
Represents a test managed resource, a resource which will automatically be cleaned up at the end of a test case.
struct test_kmalloc_params {
size_t size;
gfp_t gfp;
};
static int test_kmalloc_init(struct KUNIT_RESOURCE_T *res, void *context)
{
struct test_kmalloc_params *params = context;
res->allocation = kmalloc(params->size, params->gfp);
if (!res->allocation)
return -ENOMEM;
return 0;
}
static void test_kmalloc_free(struct KUNIT_RESOURCE_T *res)
{
kfree(res->allocation);
}
void *test_kmalloc(struct KUNIT_T *test, size_t size, gfp_t gfp)
{
struct test_kmalloc_params params;
struct KUNIT_RESOURCE_T *res;
params.size = size;
params.gfp = gfp;
// TODO(felixguo@google.com): The & gets interpreted via
// Kerneldoc but we don't want that.
res = test_alloc_resource(test, test_kmalloc_init,
test_kmalloc_free, & params);
if (res)
return res->allocation;
else
return NULL;
}
Example
-
struct KUNIT_CASE_T¶
represents an individual test case.
Definition
struct KUNIT_CASE_T {
void (*run_case)(struct KUNIT_T *test);
const char name[256];
};
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_T *)
that makes expectations and assertions (see EXPECT_TRUE()
and ASSERT_TRUE()
)
about code under test. Each test case is associated with a
struct KUNIT_SUITE_T
and will be run after the module’s init function and
followed by the module’s exit function.
A test case should be static and should only be created with the TEST_CASE()
macro; additionally, every array of test cases should be terminated with an
empty test case.
void add_test_basic(struct KUNIT_T *test)
{
EXPECT_EQ(test, 1, add(1, 0));
EXPECT_EQ(test, 2, add(1, 1));
EXPECT_EQ(test, 0, add(-1, 1));
EXPECT_EQ(test, INT_MAX, add(0, INT_MAX));
EXPECT_EQ(test, -1, add(INT_MAX, INT_MIN));
}
static struct KUNIT_CASE_T example_test_cases[] = {
TEST_CASE(add_test_basic),
{},
};
Example
-
TEST_CASE¶
TEST_CASE (test_name)
A helper for creating a
struct KUNIT_CASE_T
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
test_case
object from it. See the documentation for struct KUNIT_CASE_T
for an
example on how to use it.
-
struct KUNIT_SUITE_T¶
describes a related collection of
struct KUNIT_CASE_T
s.
Definition
struct KUNIT_SUITE_T {
const char name[256];
int (*init)(struct KUNIT_T *test);
void (*exit)(struct KUNIT_T *test);
struct KUNIT_CASE_T *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 test_module is a collection of related struct KUNIT_CASE_T
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_T
must be associated with a test_module for KUnit to
run it.
-
struct KUNIT_T¶
represents a running instance of a test.
Definition
struct KUNIT_T {
void *priv;
};
Members
priv
for user to store arbitrary data. Commonly used to pass data created in the init function (see
struct KUNIT_SUITE_T
).
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.
-
module_test¶
module_test (module)
used to register a
struct KUNIT_SUITE_T
with KUnit.
Parameters
module
a statically allocated
struct KUNIT_SUITE_T
.
Description
Registers module with the test framework. See struct KUNIT_SUITE_T
for more
information.
Hardcoding the alignment to 8 was chosen as the most likely to remain
between the compiler laying out the test module pointers in the custom
section and the linker script placing the custom section in the output
binary. There must be no gap between the section start and the first
(test_module *) entry nor between any (test_module *) entries because
the test executor views the .test_modules section as an array of
(test_module *) starting at __test_modules_start.
-
struct KUNIT_RESOURCE_T *test_alloc_resource(struct KUNIT_T *test, int (*init)(struct KUNIT_RESOURCE_T*, void*), void (*free)(struct KUNIT_RESOURCE_T*), void *context)¶
Allocates a test managed resource.
Parameters
struct KUNIT_T *test
The test context object.
int (*init)(struct KUNIT_RESOURCE_T *, void *)
a user supplied function to initialize the resource.
void (*free)(struct KUNIT_RESOURCE_T *)
a user supplied function to free the resource.
void *context
for the user to pass in arbitrary data.
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_T
for an
example.
-
void *test_kmalloc(struct KUNIT_T *test, size_t size, gfp_t gfp)¶
Just like kmalloc() except the allocation is test managed.
Parameters
struct KUNIT_T *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_T
for more information.
-
void *test_kzalloc(struct KUNIT_T *test, size_t size, gfp_t gfp)¶
Just like
test_kmalloc()
, but zeroes the allocation.
Parameters
struct KUNIT_T *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 test_kmalloc()
for more information.
-
test_info¶
test_info (test, fmt, ...)
Prints an INFO level message associated with the current 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 module being run. Takes a variable number of format parameters just like printk().
-
test_warn¶
test_warn (test, fmt, ...)
Prints a WARN level message associated with the current test.
Parameters
test
The test context object.
fmt
A printk() style format string.
...
variable arguments
Description
See test_info()
.
-
test_err¶
test_err (test, fmt, ...)
Prints an ERROR level message associated with the current test.
Parameters
test
The test context object.
fmt
A printk() style format string.
...
variable arguments
Description
See test_info()
.
-
SUCCEED¶
SUCCEED (test)
A no-op expectation. Only exists for code clarity.
Parameters
test
The test context object.
Description
The opposite of FAIL()
, it is an expectation that cannot fail. In other
words, it does nothing and only exists for code clarity. See EXPECT_TRUE()
for more information.
-
FAIL¶
FAIL (test, message)
Always causes a test to fail when evaluated.
Parameters
test
The test context object.
message
an informational message to be printed when the assertion is made.
Description
The opposite of 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 EXPECT_TRUE()
for more
information.
-
EXPECT_TRUE¶
EXPECT_TRUE (test, condition)
Causes a test failure when the given 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 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.
-
EXPECT_FALSE¶
EXPECT_FALSE (test, condition)
Causes 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 EXPECT_TRUE()
for
more information.
-
EXPECT_NOT_NULL¶
EXPECT_NOT_NULL (test, expression)
Causes a test failure when expression is NULL.
Parameters
test
The test context object.
expression
an arbitrary pointer expression. The test fails when this evaluates to NULL.
Description
Sets an expectation that expression does not evaluate to NULL. Similar to
EXPECT_TRUE()
but supposed to be used with pointer expressions.
-
EXPECT_NULL¶
EXPECT_NULL (test, expression)
Causes a test failure when expression is not NULL.
Parameters
test
The test context object.
expression
an arbitrary pointer expression. The test fails when this does not evaluate to NULL.
Description
Sets an expectation that expression evaluates to NULL. Similar to
EXPECT_FALSE()
but supposed to be used with pointer expressions.
-
EXPECT_SUCCESS¶
EXPECT_SUCCESS (test, expression)
Causes a test failure if expression does not evaluate to 0.
Parameters
test
The test context object.
expression
an arbitrary expression evaluating to an int error code. The test fails when this does not evaluate to 0.
Description
Sets an expectation that expression evaluates to 0. Implementation assumes that error codes are represented as negative values and if expression evaluates to a negative value failure message will contain a mnemonic representation of the error code (for example, for -1 it will contain EPERM).
-
EXPECT_ERROR¶
EXPECT_ERROR (test, expression, errno)
Causes a test failure when expression evaluates to errno.
Parameters
test
The test context object.
expression
an arbitrary expression evaluating to an int error code. The test fails when this does not evaluate to errno.
errno
expected error value, error values are expected to be negative.
Description
Sets an expectation that expression evaluates to errno, so as opposed to EXPECT_SUCCESS it verifies that expression evaluates to an error.
-
EXPECT_EQ¶
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 EXPECT_TRUE(test, (left) ==
(right)). See EXPECT_TRUE()
for more information.
-
EXPECT_NE¶
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 EXPECT_TRUE(test, (left) !=
(right)). See EXPECT_TRUE()
for more information.
-
EXPECT_LT¶
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
EXPECT_TRUE(test, (left) < (right)). See EXPECT_TRUE()
for more
information.
-
EXPECT_LE¶
EXPECT_LE (test, left, right)
An expectation 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 EXPECT_TRUE(test, (left) <= (right)). See EXPECT_TRUE()
for more
information.
-
EXPECT_GT¶
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
EXPECT_TRUE(test, (left) > (right)). See EXPECT_TRUE()
for more
information.
-
EXPECT_GE¶
EXPECT_GE (test, left, right)
An expectation 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
EXPECT_TRUE(test, (left) >= (right)). See EXPECT_TRUE()
for more
information.
-
EXPECT_STREQ¶
EXPECT_STREQ (test, left, right)
An expectation 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
EXPECT_TRUE(test, !strcmp((left), (right))). See EXPECT_TRUE()
for more
information.
-
EXPECT_NOT_ERR_OR_NULL¶
EXPECT_NOT_ERR_OR_NULL (test, ptr)
An expectation 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
EXPECT_TRUE(test, !IS_ERR_OR_NULL(ptr)). See EXPECT_TRUE()
for more
information.
-
ASSERT_TRUE¶
ASSERT_TRUE (test, condition)
Causes an assertion failure when the expression is not 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 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.
-
ASSERT_FALSE¶
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 EXPECT_FALSE()
, except it causes an assertion failure (see
ASSERT_TRUE()
) when the assertion is not met.
-
ASSERT_NOT_NULL¶
ASSERT_NOT_NULL (test, expression)
Asserts that expression does not evaluate to NULL.
Parameters
test
The test context object.
expression
an arbitrary pointer expression. The test fails when this evaluates to NULL.
Description
Asserts that expression does not evaluate to NULL, see EXPECT_NOT_NULL()
.
-
ASSERT_NULL¶
ASSERT_NULL (test, expression)
Asserts that expression evaluates to NULL.
Parameters
test
The test context object.
expression
an arbitrary pointer expression. The test fails when this does not evaluate to NULL.
Description
Asserts that expression evaluates to NULL, see EXPECT_NULL()
.
-
ASSERT_SUCCESS¶
ASSERT_SUCCESS (test, expression)
Asserts that expression is 0.
Parameters
test
The test context object.
expression
an arbitrary expression evaluating to an int error code.
Description
Asserts that expression evaluates to 0. It’s the same as EXPECT_SUCCESS.
-
ASSERT_ERROR¶
ASSERT_ERROR (test, expression, errno)
Causes a test failure when expression does not evaluate to errno.
Parameters
test
The test context object.
expression
an arbitrary expression evaluating to an int error code. The test fails when this does not evaluate to errno.
errno
expected error value, error values are expected to be negative.
Description
Asserts that expression evaluates to errno, similar to EXPECT_ERROR.
-
ASSERT_EQ¶
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 EXPECT_EQ()
, except it causes an assertion failure
(see ASSERT_TRUE()
) when the assertion is not met.
-
ASSERT_NE¶
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 EXPECT_NE()
, except it causes an assertion failure
(see ASSERT_TRUE()
) when the assertion is not met.
-
ASSERT_LT¶
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 EXPECT_LT()
, except it
causes an assertion failure (see ASSERT_TRUE()
) when the assertion is not
met.
-
ASSERT_LE¶
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
EXPECT_LE()
, except it causes an assertion failure (see ASSERT_TRUE()
) when
the assertion is not met.
-
ASSERT_GT¶
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 EXPECT_GT()
, except it
causes an assertion failure (see ASSERT_TRUE()
) when the assertion is not
met.
-
ASSERT_GE¶
ASSERT_GE (test, left, right)
An 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 EXPECT_GE()
, except it
causes an assertion failure (see ASSERT_TRUE()
) when the assertion is not
met.
-
ASSERT_STREQ¶
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 EXPECT_STREQ()
, except it causes an assertion
failure (see ASSERT_TRUE()
) when the assertion is not met.
-
ASSERT_NOT_ERR_OR_NULL¶
ASSERT_NOT_ERR_OR_NULL (test, ptr)
An 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 EXPECT_NOT_ERR_OR_NULL()
,
except it causes an assertion failure (see ASSERT_TRUE()
) when the assertion
is not met.
-
ASSERT_SIGSEGV¶
ASSERT_SIGSEGV (test, expr)
An assertion that expr will cause a segfault.
Parameters
test
The test context object.
expr
an arbitrary block of code.
Description
Sets an assertion that expr, when evaluated, will cause a segfault. Currently this assertion is only really useful for testing the KUnit framework, as a segmentation fault in normal kernel code is always incorrect. However, the plan is to replace this assertion with an arbitrary death assertion similar to https://github.com/google/googletest/blob/master/googletest/docs/advanced.md#death-tests which will probably be massaged to make sense in the context of the kernel (maybe assert that a panic occurred, or that BUG() was called).
NOTE
no code after this assertion will ever be executed.
-
struct test_stream¶
a std::stream style string builder.
Definition
struct test_stream {
void (*set_level)(struct test_stream *this, const char *level);
void (*add)(struct test_stream *this, const char *fmt, ...);
void (*append)(struct test_stream *this, struct test_stream *other);
void (*commit)(struct test_stream *this);
void (*clear)(struct test_stream *this);
};
Members
set_level
sets the level that this string should be printed at.
add
adds the formatted input to the internal buffer.
commit
prints out the internal buffer to the user.
clear
clears the internal buffer.
Description
A std::stream style string builder. Allows messages to be built up and printed all at once.
-
struct test_stream *test_new_stream(struct KUNIT_T *test)¶
constructs a new
struct test_stream
.
Parameters
struct KUNIT_T *test
The test context object.
Description
Constructs a new test managed struct test_stream
.