usage.rst

   1.. SPDX-License-Identifier: GPL-2.0
   2
   3Writing Tests
   4=============
   5
   6Test Cases
   7----------
   8
   9The fundamental unit in KUnit is the test case. A test case is a function with
  10the signature ``void (*)(struct kunit *test)``. It calls the function under test
  11and then sets *expectations* for what should happen. For example:
  12
  13.. code-block:: c
  14
  15	void example_test_success(struct kunit *test)
  16	{
  17	}
  18
  19	void example_test_failure(struct kunit *test)
  20	{
  21		KUNIT_FAIL(test, "This test never passes.");
  22	}
  23
  24In the above example, ``example_test_success`` always passes because it does
  25nothing; no expectations are set, and therefore all expectations pass. On the
  26other hand ``example_test_failure`` always fails because it calls ``KUNIT_FAIL``,
  27which is a special expectation that logs a message and causes the test case to
  28fail.
  29
  30Expectations
  31~~~~~~~~~~~~
  32An *expectation* specifies that we expect a piece of code to do something in a
  33test. An expectation is called like a function. A test is made by setting
  34expectations about the behavior of a piece of code under test. When one or more
  35expectations fail, the test case fails and information about the failure is
  36logged. For example:
  37
  38.. code-block:: c
  39
  40	void add_test_basic(struct kunit *test)
  41	{
  42		KUNIT_EXPECT_EQ(test, 1, add(1, 0));
  43		KUNIT_EXPECT_EQ(test, 2, add(1, 1));
  44	}
  45
  46In the above example, ``add_test_basic`` makes a number of assertions about the
  47behavior of a function called ``add``. The first parameter is always of type
  48``struct kunit *``, which contains information about the current test context.
  49The second parameter, in this case, is what the value is expected to be. The
  50last value is what the value actually is. If ``add`` passes all of these
  51expectations, the test case, ``add_test_basic`` will pass; if any one of these
  52expectations fails, the test case will fail.
  53
  54A test case *fails* when any expectation is violated; however, the test will
  55continue to run, and try other expectations until the test case ends or is
  56otherwise terminated. This is as opposed to *assertions* which are discussed
  57later.
  58
  59To learn about more KUnit expectations, see Documentation/dev-tools/kunit/api/test.rst.
  60
  61.. note::
  62   A single test case should be short, easy to understand, and focused on a
  63   single behavior.
  64
  65For example, if we want to rigorously test the ``add`` function above, create
  66additional tests cases which would test each property that an ``add`` function
  67should have as shown below:
  68
  69.. code-block:: c
  70
  71	void add_test_basic(struct kunit *test)
  72	{
  73		KUNIT_EXPECT_EQ(test, 1, add(1, 0));
  74		KUNIT_EXPECT_EQ(test, 2, add(1, 1));
  75	}
  76
  77	void add_test_negative(struct kunit *test)
  78	{
  79		KUNIT_EXPECT_EQ(test, 0, add(-1, 1));
  80	}
  81
  82	void add_test_max(struct kunit *test)
  83	{
  84		KUNIT_EXPECT_EQ(test, INT_MAX, add(0, INT_MAX));
  85		KUNIT_EXPECT_EQ(test, -1, add(INT_MAX, INT_MIN));
  86	}
  87
  88	void add_test_overflow(struct kunit *test)
  89	{
  90		KUNIT_EXPECT_EQ(test, INT_MIN, add(INT_MAX, 1));
  91	}
  92
  93Assertions
  94~~~~~~~~~~
  95
  96An assertion is like an expectation, except that the assertion immediately
  97terminates the test case if the condition is not satisfied. For example:
  98
  99.. code-block:: c
 100
 101	static void test_sort(struct kunit *test)
 102	{
 103		int *a, i, r = 1;
 104		a = kunit_kmalloc_array(test, TEST_LEN, sizeof(*a), GFP_KERNEL);
 105		KUNIT_ASSERT_NOT_ERR_OR_NULL(test, a);
 106		for (i = 0; i < TEST_LEN; i++) {
 107			r = (r * 725861) % 6599;
 108			a[i] = r;
 109		}
 110		sort(a, TEST_LEN, sizeof(*a), cmpint, NULL);
 111		for (i = 0; i < TEST_LEN-1; i++)
 112			KUNIT_EXPECT_LE(test, a[i], a[i + 1]);
 113	}
 114
 115In this example, we need to be able to allocate an array to test the ``sort()``
 116function. So we use ``KUNIT_ASSERT_NOT_ERR_OR_NULL()`` to abort the test if
 117there's an allocation error.
 118
 119.. note::
 120   In other test frameworks, ``ASSERT`` macros are often implemented by calling
 121   ``return`` so they only work from the test function. In KUnit, we stop the
 122   current kthread on failure, so you can call them from anywhere.
 123
 124.. note::
 125   Warning: There is an exception to the above rule. You shouldn't use assertions
 126   in the suite's exit() function, or in the free function for a resource. These
 127   run when a test is shutting down, and an assertion here prevents further
 128   cleanup code from running, potentially leading to a memory leak.
 129
 130Customizing error messages
 131--------------------------
 132
 133Each of the ``KUNIT_EXPECT`` and ``KUNIT_ASSERT`` macros have a ``_MSG``
 134variant.  These take a format string and arguments to provide additional
 135context to the automatically generated error messages.
 136
 137.. code-block:: c
 138
 139	char some_str[41];
 140	generate_sha1_hex_string(some_str);
 141
 142	/* Before. Not easy to tell why the test failed. */
 143	KUNIT_EXPECT_EQ(test, strlen(some_str), 40);
 144
 145	/* After. Now we see the offending string. */
 146	KUNIT_EXPECT_EQ_MSG(test, strlen(some_str), 40, "some_str='%s'", some_str);
 147
 148Alternatively, one can take full control over the error message by using
 149``KUNIT_FAIL()``, e.g.
 150
 151.. code-block:: c
 152
 153	/* Before */
 154	KUNIT_EXPECT_EQ(test, some_setup_function(), 0);
 155
 156	/* After: full control over the failure message. */
 157	if (some_setup_function())
 158		KUNIT_FAIL(test, "Failed to setup thing for testing");
 159
 160
 161Test Suites
 162~~~~~~~~~~~
 163
 164We need many test cases covering all the unit's behaviors. It is common to have
 165many similar tests. In order to reduce duplication in these closely related
 166tests, most unit testing frameworks (including KUnit) provide the concept of a
 167*test suite*. A test suite is a collection of test cases for a unit of code
 168with optional setup and teardown functions that run before/after the whole
 169suite and/or every test case.
 170
 171.. note::
 172   A test case will only run if it is associated with a test suite.
 173
 174For example:
 175
 176.. code-block:: c
 177
 178	static struct kunit_case example_test_cases[] = {
 179		KUNIT_CASE(example_test_foo),
 180		KUNIT_CASE(example_test_bar),
 181		KUNIT_CASE(example_test_baz),
 182		{}
 183	};
 184
 185	static struct kunit_suite example_test_suite = {
 186		.name = "example",
 187		.init = example_test_init,
 188		.exit = example_test_exit,
 189		.suite_init = example_suite_init,
 190		.suite_exit = example_suite_exit,
 191		.test_cases = example_test_cases,
 192	};
 193	kunit_test_suite(example_test_suite);
 194
 195In the above example, the test suite ``example_test_suite`` would first run
 196``example_suite_init``, then run the test cases ``example_test_foo``,
 197``example_test_bar``, and ``example_test_baz``. Each would have
 198``example_test_init`` called immediately before it and ``example_test_exit``
 199called immediately after it. Finally, ``example_suite_exit`` would be called
 200after everything else. ``kunit_test_suite(example_test_suite)`` registers the
 201test suite with the KUnit test framework.
 202
 203.. note::
 204   The ``exit`` and ``suite_exit`` functions will run even if ``init`` or
 205   ``suite_init`` fail. Make sure that they can handle any inconsistent
 206   state which may result from ``init`` or ``suite_init`` encountering errors
 207   or exiting early.
 208
 209``kunit_test_suite(...)`` is a macro which tells the linker to put the
 210specified test suite in a special linker section so that it can be run by KUnit
 211either after ``late_init``, or when the test module is loaded (if the test was
 212built as a module).
 213
 214For more information, see Documentation/dev-tools/kunit/api/test.rst.
 215
 216.. _kunit-on-non-uml:
 217
 218Writing Tests For Other Architectures
 219-------------------------------------
 220
 221It is better to write tests that run on UML to tests that only run under a
 222particular architecture. It is better to write tests that run under QEMU or
 223another easy to obtain (and monetarily free) software environment to a specific
 224piece of hardware.
 225
 226Nevertheless, there are still valid reasons to write a test that is architecture
 227or hardware specific. For example, we might want to test code that really
 228belongs in ``arch/some-arch/*``. Even so, try to write the test so that it does
 229not depend on physical hardware. Some of our test cases may not need hardware,
 230only few tests actually require the hardware to test it. When hardware is not
 231available, instead of disabling tests, we can skip them.
 232
 233Now that we have narrowed down exactly what bits are hardware specific, the
 234actual procedure for writing and running the tests is same as writing normal
 235KUnit tests.
 236
 237.. important::
 238   We may have to reset hardware state. If this is not possible, we may only
 239   be able to run one test case per invocation.
 240
 241.. TODO(brendanhiggins@google.com): Add an actual example of an architecture-
 242   dependent KUnit test.
 243
 244Common Patterns
 245===============
 246
 247Isolating Behavior
 248------------------
 249
 250Unit testing limits the amount of code under test to a single unit. It controls
 251what code gets run when the unit under test calls a function. Where a function
 252is exposed as part of an API such that the definition of that function can be
 253changed without affecting the rest of the code base. In the kernel, this comes
 254from two constructs: classes, which are structs that contain function pointers
 255provided by the implementer, and architecture-specific functions, which have
 256definitions selected at compile time.
 257
 258Classes
 259~~~~~~~
 260
 261Classes are not a construct that is built into the C programming language;
 262however, it is an easily derived concept. Accordingly, in most cases, every
 263project that does not use a standardized object oriented library (like GNOME's
 264GObject) has their own slightly different way of doing object oriented
 265programming; the Linux kernel is no exception.
 266
 267The central concept in kernel object oriented programming is the class. In the
 268kernel, a *class* is a struct that contains function pointers. This creates a
 269contract between *implementers* and *users* since it forces them to use the
 270same function signature without having to call the function directly. To be a
 271class, the function pointers must specify that a pointer to the class, known as
 272a *class handle*, be one of the parameters. Thus the member functions (also
 273known as *methods*) have access to member variables (also known as *fields*)
 274allowing the same implementation to have multiple *instances*.
 275
 276A class can be *overridden* by *child classes* by embedding the *parent class*
 277in the child class. Then when the child class *method* is called, the child
 278implementation knows that the pointer passed to it is of a parent contained
 279within the child. Thus, the child can compute the pointer to itself because the
 280pointer to the parent is always a fixed offset from the pointer to the child.
 281This offset is the offset of the parent contained in the child struct. For
 282example:
 283
 284.. code-block:: c
 285
 286	struct shape {
 287		int (*area)(struct shape *this);
 288	};
 289
 290	struct rectangle {
 291		struct shape parent;
 292		int length;
 293		int width;
 294	};
 295
 296	int rectangle_area(struct shape *this)
 297	{
 298		struct rectangle *self = container_of(this, struct rectangle, parent);
 299
 300		return self->length * self->width;
 301	};
 302
 303	void rectangle_new(struct rectangle *self, int length, int width)
 304	{
 305		self->parent.area = rectangle_area;
 306		self->length = length;
 307		self->width = width;
 308	}
 309
 310In this example, computing the pointer to the child from the pointer to the
 311parent is done by ``container_of``.
 312
 313Faking Classes
 314~~~~~~~~~~~~~~
 315
 316In order to unit test a piece of code that calls a method in a class, the
 317behavior of the method must be controllable, otherwise the test ceases to be a
 318unit test and becomes an integration test.
 319
 320A fake class implements a piece of code that is different than what runs in a
 321production instance, but behaves identical from the standpoint of the callers.
 322This is done to replace a dependency that is hard to deal with, or is slow. For
 323example, implementing a fake EEPROM that stores the "contents" in an
 324internal buffer. Assume we have a class that represents an EEPROM:
 325
 326.. code-block:: c
 327
 328	struct eeprom {
 329		ssize_t (*read)(struct eeprom *this, size_t offset, char *buffer, size_t count);
 330		ssize_t (*write)(struct eeprom *this, size_t offset, const char *buffer, size_t count);
 331	};
 332
 333And we want to test code that buffers writes to the EEPROM:
 334
 335.. code-block:: c
 336
 337	struct eeprom_buffer {
 338		ssize_t (*write)(struct eeprom_buffer *this, const char *buffer, size_t count);
 339		int flush(struct eeprom_buffer *this);
 340		size_t flush_count; /* Flushes when buffer exceeds flush_count. */
 341	};
 342
 343	struct eeprom_buffer *new_eeprom_buffer(struct eeprom *eeprom);
 344	void destroy_eeprom_buffer(struct eeprom *eeprom);
 345
 346We can test this code by *faking out* the underlying EEPROM:
 347
 348.. code-block:: c
 349
 350	struct fake_eeprom {
 351		struct eeprom parent;
 352		char contents[FAKE_EEPROM_CONTENTS_SIZE];
 353	};
 354
 355	ssize_t fake_eeprom_read(struct eeprom *parent, size_t offset, char *buffer, size_t count)
 356	{
 357		struct fake_eeprom *this = container_of(parent, struct fake_eeprom, parent);
 358
 359		count = min(count, FAKE_EEPROM_CONTENTS_SIZE - offset);
 360		memcpy(buffer, this->contents + offset, count);
 361
 362		return count;
 363	}
 364
 365	ssize_t fake_eeprom_write(struct eeprom *parent, size_t offset, const char *buffer, size_t count)
 366	{
 367		struct fake_eeprom *this = container_of(parent, struct fake_eeprom, parent);
 368
 369		count = min(count, FAKE_EEPROM_CONTENTS_SIZE - offset);
 370		memcpy(this->contents + offset, buffer, count);
 371
 372		return count;
 373	}
 374
 375	void fake_eeprom_init(struct fake_eeprom *this)
 376	{
 377		this->parent.read = fake_eeprom_read;
 378		this->parent.write = fake_eeprom_write;
 379		memset(this->contents, 0, FAKE_EEPROM_CONTENTS_SIZE);
 380	}
 381
 382We can now use it to test ``struct eeprom_buffer``:
 383
 384.. code-block:: c
 385
 386	struct eeprom_buffer_test {
 387		struct fake_eeprom *fake_eeprom;
 388		struct eeprom_buffer *eeprom_buffer;
 389	};
 390
 391	static void eeprom_buffer_test_does_not_write_until_flush(struct kunit *test)
 392	{
 393		struct eeprom_buffer_test *ctx = test->priv;
 394		struct eeprom_buffer *eeprom_buffer = ctx->eeprom_buffer;
 395		struct fake_eeprom *fake_eeprom = ctx->fake_eeprom;
 396		char buffer[] = {0xff};
 397
 398		eeprom_buffer->flush_count = SIZE_MAX;
 399
 400		eeprom_buffer->write(eeprom_buffer, buffer, 1);
 401		KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0);
 402
 403		eeprom_buffer->write(eeprom_buffer, buffer, 1);
 404		KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0);
 405
 406		eeprom_buffer->flush(eeprom_buffer);
 407		KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0xff);
 408		KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0xff);
 409	}
 410
 411	static void eeprom_buffer_test_flushes_after_flush_count_met(struct kunit *test)
 412	{
 413		struct eeprom_buffer_test *ctx = test->priv;
 414		struct eeprom_buffer *eeprom_buffer = ctx->eeprom_buffer;
 415		struct fake_eeprom *fake_eeprom = ctx->fake_eeprom;
 416		char buffer[] = {0xff};
 417
 418		eeprom_buffer->flush_count = 2;
 419
 420		eeprom_buffer->write(eeprom_buffer, buffer, 1);
 421		KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0);
 422
 423		eeprom_buffer->write(eeprom_buffer, buffer, 1);
 424		KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0xff);
 425		KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0xff);
 426	}
 427
 428	static void eeprom_buffer_test_flushes_increments_of_flush_count(struct kunit *test)
 429	{
 430		struct eeprom_buffer_test *ctx = test->priv;
 431		struct eeprom_buffer *eeprom_buffer = ctx->eeprom_buffer;
 432		struct fake_eeprom *fake_eeprom = ctx->fake_eeprom;
 433		char buffer[] = {0xff, 0xff};
 434
 435		eeprom_buffer->flush_count = 2;
 436
 437		eeprom_buffer->write(eeprom_buffer, buffer, 1);
 438		KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0);
 439
 440		eeprom_buffer->write(eeprom_buffer, buffer, 2);
 441		KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0xff);
 442		KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0xff);
 443		/* Should have only flushed the first two bytes. */
 444		KUNIT_EXPECT_EQ(test, fake_eeprom->contents[2], 0);
 445	}
 446
 447	static int eeprom_buffer_test_init(struct kunit *test)
 448	{
 449		struct eeprom_buffer_test *ctx;
 450
 451		ctx = kunit_kzalloc(test, sizeof(*ctx), GFP_KERNEL);
 452		KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ctx);
 453
 454		ctx->fake_eeprom = kunit_kzalloc(test, sizeof(*ctx->fake_eeprom), GFP_KERNEL);
 455		KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ctx->fake_eeprom);
 456		fake_eeprom_init(ctx->fake_eeprom);
 457
 458		ctx->eeprom_buffer = new_eeprom_buffer(&ctx->fake_eeprom->parent);
 459		KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ctx->eeprom_buffer);
 460
 461		test->priv = ctx;
 462
 463		return 0;
 464	}
 465
 466	static void eeprom_buffer_test_exit(struct kunit *test)
 467	{
 468		struct eeprom_buffer_test *ctx = test->priv;
 469
 470		destroy_eeprom_buffer(ctx->eeprom_buffer);
 471	}
 472
 473Testing Against Multiple Inputs
 474-------------------------------
 475
 476Testing just a few inputs is not enough to ensure that the code works correctly,
 477for example: testing a hash function.
 478
 479We can write a helper macro or function. The function is called for each input.
 480For example, to test ``sha1sum(1)``, we can write:
 481
 482.. code-block:: c
 483
 484	#define TEST_SHA1(in, want) \
 485		sha1sum(in, out); \
 486		KUNIT_EXPECT_STREQ_MSG(test, out, want, "sha1sum(%s)", in);
 487
 488	char out[40];
 489	TEST_SHA1("hello world",  "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed");
 490	TEST_SHA1("hello world!", "430ce34d020724ed75a196dfc2ad67c77772d169");
 491
 492Note the use of the ``_MSG`` version of ``KUNIT_EXPECT_STREQ`` to print a more
 493detailed error and make the assertions clearer within the helper macros.
 494
 495The ``_MSG`` variants are useful when the same expectation is called multiple
 496times (in a loop or helper function) and thus the line number is not enough to
 497identify what failed, as shown below.
 498
 499In complicated cases, we recommend using a *table-driven test* compared to the
 500helper macro variation, for example:
 501
 502.. code-block:: c
 503
 504	int i;
 505	char out[40];
 506
 507	struct sha1_test_case {
 508		const char *str;
 509		const char *sha1;
 510	};
 511
 512	struct sha1_test_case cases[] = {
 513		{
 514			.str = "hello world",
 515			.sha1 = "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed",
 516		},
 517		{
 518			.str = "hello world!",
 519			.sha1 = "430ce34d020724ed75a196dfc2ad67c77772d169",
 520		},
 521	};
 522	for (i = 0; i < ARRAY_SIZE(cases); ++i) {
 523		sha1sum(cases[i].str, out);
 524		KUNIT_EXPECT_STREQ_MSG(test, out, cases[i].sha1,
 525		                      "sha1sum(%s)", cases[i].str);
 526	}
 527
 528
 529There is more boilerplate code involved, but it can:
 530
 531* be more readable when there are multiple inputs/outputs (due to field names).
 532
 533  * For example, see ``fs/ext4/inode-test.c``.
 534
 535* reduce duplication if test cases are shared across multiple tests.
 536
 537  * For example: if we want to test ``sha256sum``, we could add a ``sha256``
 538    field and reuse ``cases``.
 539
 540* be converted to a "parameterized test".
 541
 542Parameterized Testing
 543~~~~~~~~~~~~~~~~~~~~~
 544
 545To run a test case against multiple inputs, KUnit provides a parameterized
 546testing framework. This feature formalizes and extends the concept of
 547table-driven tests discussed previously.
 548
 549A KUnit test is determined to be parameterized if a parameter generator function
 550is provided when registering the test case. A test user can either write their
 551own generator function or use one that is provided by KUnit. The generator
 552function is stored in  ``kunit_case->generate_params`` and can be set using the
 553macros described in the section below.
 554
 555To establish the terminology, a "parameterized test" is a test which is run
 556multiple times (once per "parameter" or "parameter run"). Each parameter run has
 557both its own independent ``struct kunit`` (the "parameter run context") and
 558access to a shared parent ``struct kunit`` (the "parameterized test context").
 559
 560Passing Parameters to a Test
 561^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 562There are three ways to provide the parameters to a test:
 563
 564Array Parameter Macros:
 565
 566   KUnit provides special support for the common table-driven testing pattern.
 567   By applying either ``KUNIT_ARRAY_PARAM`` or ``KUNIT_ARRAY_PARAM_DESC`` to the
 568   ``cases`` array from the previous section, we can create a parameterized test
 569   as shown below:
 570
 571.. code-block:: c
 572
 573	// This is copy-pasted from above.
 574	struct sha1_test_case {
 575		const char *str;
 576		const char *sha1;
 577	};
 578	static const struct sha1_test_case cases[] = {
 579		{
 580			.str = "hello world",
 581			.sha1 = "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed",
 582		},
 583		{
 584			.str = "hello world!",
 585			.sha1 = "430ce34d020724ed75a196dfc2ad67c77772d169",
 586		},
 587	};
 588
 589	// Creates `sha1_gen_params()` to iterate over `cases` while using
 590	// the struct member `str` for the case description.
 591	KUNIT_ARRAY_PARAM_DESC(sha1, cases, str);
 592
 593	// Looks no different from a normal test.
 594	static void sha1_test(struct kunit *test)
 595	{
 596		// This function can just contain the body of the for-loop.
 597		// The former `cases[i]` is accessible under test->param_value.
 598		char out[40];
 599		struct sha1_test_case *test_param = (struct sha1_test_case *)(test->param_value);
 600
 601		sha1sum(test_param->str, out);
 602		KUNIT_EXPECT_STREQ_MSG(test, out, test_param->sha1,
 603				      "sha1sum(%s)", test_param->str);
 604	}
 605
 606	// Instead of KUNIT_CASE, we use KUNIT_CASE_PARAM and pass in the
 607	// function declared by KUNIT_ARRAY_PARAM or KUNIT_ARRAY_PARAM_DESC.
 608	static struct kunit_case sha1_test_cases[] = {
 609		KUNIT_CASE_PARAM(sha1_test, sha1_gen_params),
 610		{}
 611	};
 612
 613Custom Parameter Generator Function:
 614
 615   The generator function is responsible for generating parameters one-by-one
 616   and has the following signature:
 617   ``const void* (*)(struct kunit *test, const void *prev, char *desc)``.
 618   You can pass the generator function to the ``KUNIT_CASE_PARAM``
 619   or ``KUNIT_CASE_PARAM_WITH_INIT`` macros.
 620
 621   The function receives the previously generated parameter as the ``prev`` argument
 622   (which is ``NULL`` on the first call) and can also access the parameterized
 623   test context passed as the ``test`` argument. KUnit calls this function
 624   repeatedly until it returns ``NULL``, which signifies that a parameterized
 625   test ended.
 626
 627   Below is an example of how it works:
 628
 629.. code-block:: c
 630
 631	#define MAX_TEST_BUFFER_SIZE 8
 632
 633	// Example generator function. It produces a sequence of buffer sizes that
 634	// are powers of two, starting at 1 (e.g., 1, 2, 4, 8).
 635	static const void *buffer_size_gen_params(struct kunit *test, const void *prev, char *desc)
 636	{
 637		long prev_buffer_size = (long)prev;
 638		long next_buffer_size = 1; // Start with an initial size of 1.
 639
 640		// Stop generating parameters if the limit is reached or exceeded.
 641		if (prev_buffer_size >= MAX_TEST_BUFFER_SIZE)
 642			return NULL;
 643
 644		// For subsequent calls, calculate the next size by doubling the previous one.
 645		if (prev)
 646			next_buffer_size = prev_buffer_size << 1;
 647
 648		return (void *)next_buffer_size;
 649	}
 650
 651	// Simple test to validate that kunit_kzalloc provides zeroed memory.
 652	static void buffer_zero_test(struct kunit *test)
 653	{
 654		long buffer_size = (long)test->param_value;
 655		// Use kunit_kzalloc to allocate a zero-initialized buffer. This makes the
 656		// memory "parameter run managed," meaning it's automatically cleaned up at
 657		// the end of each parameter run.
 658		int *buf = kunit_kzalloc(test, buffer_size * sizeof(int), GFP_KERNEL);
 659
 660		// Ensure the allocation was successful.
 661		KUNIT_ASSERT_NOT_NULL(test, buf);
 662
 663		// Loop through the buffer and confirm every element is zero.
 664		for (int i = 0; i < buffer_size; i++)
 665			KUNIT_EXPECT_EQ(test, buf[i], 0);
 666	}
 667
 668	static struct kunit_case buffer_test_cases[] = {
 669		KUNIT_CASE_PARAM(buffer_zero_test, buffer_size_gen_params),
 670		{}
 671	};
 672
 673Runtime Parameter Array Registration in the Init Function:
 674
 675   For scenarios where you might need to initialize a parameterized test, you
 676   can directly register a parameter array to the parameterized test context.
 677
 678   To do this, you must pass the parameterized test context, the array itself,
 679   the array size, and a ``get_description()`` function to the
 680   ``kunit_register_params_array()`` macro. This macro populates
 681   ``struct kunit_params`` within the parameterized test context, effectively
 682   storing a parameter array object. The ``get_description()`` function will
 683   be used for populating parameter descriptions and has the following signature:
 684   ``void (*)(struct kunit *test, const void *param, char *desc)``. Note that it
 685   also has access to the parameterized test context.
 686
 687      .. important::
 688         When using this way to register a parameter array, you will need to
 689         manually pass ``kunit_array_gen_params()`` as the generator function to
 690         ``KUNIT_CASE_PARAM_WITH_INIT``. ``kunit_array_gen_params()`` is a KUnit
 691         helper that will use the registered array to generate the parameters.
 692
 693	 If needed, instead of passing the KUnit helper, you can also pass your
 694	 own custom generator function that utilizes the parameter array. To
 695	 access the parameter array from within the parameter generator
 696	 function use ``test->params_array.params``.
 697
 698   The ``kunit_register_params_array()`` macro should be called within a
 699   ``param_init()`` function that initializes the parameterized test and has
 700   the following signature ``int (*)(struct kunit *test)``. For a detailed
 701   explanation of this mechanism please refer to the "Adding Shared Resources"
 702   section that is after this one. This method supports registering both
 703   dynamically built and static parameter arrays.
 704
 705   The code snippet below shows the ``example_param_init_dynamic_arr`` test that
 706   utilizes ``make_fibonacci_params()`` to create a dynamic array, which is then
 707   registered using ``kunit_register_params_array()``. To see the full code
 708   please refer to lib/kunit/kunit-example-test.c.
 709
 710.. code-block:: c
 711
 712	/*
 713	* Example of a parameterized test param_init() function that registers a dynamic
 714	* array of parameters.
 715	*/
 716	static int example_param_init_dynamic_arr(struct kunit *test)
 717	{
 718		size_t seq_size;
 719		int *fibonacci_params;
 720
 721		kunit_info(test, "initializing parameterized test\n");
 722
 723		seq_size = 6;
 724		fibonacci_params = make_fibonacci_params(test, seq_size);
 725		if (!fibonacci_params)
 726			return -ENOMEM;
 727		/*
 728		* Passes the dynamic parameter array information to the parameterized test
 729		* context struct kunit. The array and its metadata will be stored in
 730		* test->parent->params_array. The array itself will be located in
 731		* params_data.params.
 732		*/
 733		kunit_register_params_array(test, fibonacci_params, seq_size,
 734					example_param_dynamic_arr_get_desc);
 735		return 0;
 736	}
 737
 738	static struct kunit_case example_test_cases[] = {
 739		/*
 740		 * Note how we pass kunit_array_gen_params() to use the array we
 741		 * registered in example_param_init_dynamic_arr() to generate
 742		 * parameters.
 743		 */
 744		KUNIT_CASE_PARAM_WITH_INIT(example_params_test_with_init_dynamic_arr,
 745					   kunit_array_gen_params,
 746					   example_param_init_dynamic_arr,
 747					   example_param_exit_dynamic_arr),
 748		{}
 749	};
 750
 751Adding Shared Resources
 752^^^^^^^^^^^^^^^^^^^^^^^
 753All parameter runs in this framework hold a reference to the parameterized test
 754context, which can be accessed using the parent ``struct kunit`` pointer. The
 755parameterized test context is not used to execute any test logic itself; instead,
 756it serves as a container for shared resources.
 757
 758It's possible to add resources to share between parameter runs within a
 759parameterized test by using ``KUNIT_CASE_PARAM_WITH_INIT``, to which you pass
 760custom ``param_init()`` and ``param_exit()`` functions. These functions run once
 761before and once after the parameterized test, respectively.
 762
 763The ``param_init()`` function, with the signature ``int (*)(struct kunit *test)``,
 764can be used for adding resources to the ``resources`` or ``priv`` fields of
 765the parameterized test context, registering the parameter array, and any other
 766initialization logic.
 767
 768The ``param_exit()`` function, with the signature ``void (*)(struct kunit *test)``,
 769can be used to release any resources that were not parameterized test managed (i.e.
 770not automatically cleaned up after the parameterized test ends) and for any other
 771exit logic.
 772
 773Both ``param_init()`` and ``param_exit()`` are passed the parameterized test
 774context behind the scenes. However, the test case function receives the parameter
 775run context. Therefore, to manage and access shared resources from within a test
 776case function, you must use ``test->parent``.
 777
 778For instance, finding a shared resource allocated by the Resource API requires
 779passing ``test->parent`` to ``kunit_find_resource()``. This principle extends to
 780all other APIs that might be used in the test case function, including
 781``kunit_kzalloc()``, ``kunit_kmalloc_array()``, and others (see
 782Documentation/dev-tools/kunit/api/test.rst and the
 783Documentation/dev-tools/kunit/api/resource.rst).
 784
 785.. note::
 786   The ``suite->init()`` function, which executes before each parameter run,
 787   receives the parameter run context. Therefore, any resources set up in
 788   ``suite->init()`` are cleaned up after each parameter run.
 789
 790The code below shows how you can add the shared resources. Note that this code
 791utilizes the Resource API, which you can read more about here:
 792Documentation/dev-tools/kunit/api/resource.rst. To see the full version of this
 793code please refer to lib/kunit/kunit-example-test.c.
 794
 795.. code-block:: c
 796
 797	static int example_resource_init(struct kunit_resource *res, void *context)
 798	{
 799		... /* Code that allocates memory and stores context in res->data. */
 800	}
 801
 802	/* This function deallocates memory for the kunit_resource->data field. */
 803	static void example_resource_free(struct kunit_resource *res)
 804	{
 805		kfree(res->data);
 806	}
 807
 808	/* This match function locates a test resource based on defined criteria. */
 809	static bool example_resource_alloc_match(struct kunit *test, struct kunit_resource *res,
 810						 void *match_data)
 811	{
 812		return res->data && res->free == example_resource_free;
 813	}
 814
 815	/* Function to initialize the parameterized test. */
 816	static int example_param_init(struct kunit *test)
 817	{
 818		int ctx = 3; /* Data to be stored. */
 819		void *data = kunit_alloc_resource(test, example_resource_init,
 820						  example_resource_free,
 821						  GFP_KERNEL, &ctx);
 822		if (!data)
 823			return -ENOMEM;
 824		kunit_register_params_array(test, example_params_array,
 825					    ARRAY_SIZE(example_params_array));
 826		return 0;
 827	}
 828
 829	/* Example test that uses shared resources in test->resources. */
 830	static void example_params_test_with_init(struct kunit *test)
 831	{
 832		int threshold;
 833		const struct example_param *param = test->param_value;
 834		/*  Here we pass test->parent to access the parameterized test context. */
 835		struct kunit_resource *res = kunit_find_resource(test->parent,
 836								 example_resource_alloc_match,
 837								 NULL);
 838
 839		threshold = *((int *)res->data);
 840		KUNIT_ASSERT_LE(test, param->value, threshold);
 841		kunit_put_resource(res);
 842	}
 843
 844	static struct kunit_case example_test_cases[] = {
 845		KUNIT_CASE_PARAM_WITH_INIT(example_params_test_with_init, kunit_array_gen_params,
 846					   example_param_init, NULL),
 847		{}
 848	};
 849
 850As an alternative to using the KUnit Resource API for sharing resources, you can
 851place them in ``test->parent->priv``. This serves as a more lightweight method
 852for resource storage, best for scenarios where complex resource management is
 853not required.
 854
 855As stated previously ``param_init()`` and ``param_exit()`` get the parameterized
 856test context. So, you can directly use ``test->priv`` within ``param_init/exit``
 857to manage shared resources. However, from within the test case function, you must
 858navigate up to the parent ``struct kunit`` i.e. the parameterized test context.
 859Therefore, you need to use ``test->parent->priv`` to access those same
 860resources.
 861
 862The resources placed in ``test->parent->priv`` will need to be allocated in
 863memory to persist across the parameter runs. If memory is allocated using the
 864KUnit memory allocation APIs (described more in the "Allocating Memory" section
 865below), you won't need to worry about deallocation. The APIs will make the memory
 866parameterized test 'managed', ensuring that it will automatically get cleaned up
 867after the parameterized test concludes.
 868
 869The code below demonstrates example usage of the ``priv`` field for shared
 870resources:
 871
 872.. code-block:: c
 873
 874	static const struct example_param {
 875		int value;
 876	} example_params_array[] = {
 877		{ .value = 3, },
 878		{ .value = 2, },
 879		{ .value = 1, },
 880		{ .value = 0, },
 881	};
 882
 883	/* Initialize the parameterized test context. */
 884	static int example_param_init_priv(struct kunit *test)
 885	{
 886		int ctx = 3; /* Data to be stored. */
 887		int arr_size = ARRAY_SIZE(example_params_array);
 888
 889		/*
 890		 * Allocate memory using kunit_kzalloc(). Since the `param_init`
 891		 * function receives the parameterized test context, this memory
 892		 * allocation will be scoped to the lifetime of the parameterized test.
 893		 */
 894		test->priv = kunit_kzalloc(test, sizeof(int), GFP_KERNEL);
 895
 896		/* Assign the context value to test->priv.*/
 897		*((int *)test->priv) = ctx;
 898
 899		/* Register the parameter array. */
 900		kunit_register_params_array(test, example_params_array, arr_size, NULL);
 901		return 0;
 902	}
 903
 904	static void example_params_test_with_init_priv(struct kunit *test)
 905	{
 906		int threshold;
 907		const struct example_param *param = test->param_value;
 908
 909		/* By design, test->parent will not be NULL. */
 910		KUNIT_ASSERT_NOT_NULL(test, test->parent);
 911
 912		/* Here we use test->parent->priv to access the shared resource. */
 913		threshold = *(int *)test->parent->priv;
 914
 915		KUNIT_ASSERT_LE(test, param->value, threshold);
 916	}
 917
 918	static struct kunit_case example_tests[] = {
 919		KUNIT_CASE_PARAM_WITH_INIT(example_params_test_with_init_priv,
 920					   kunit_array_gen_params,
 921					   example_param_init_priv, NULL),
 922		{}
 923	};
 924
 925Allocating Memory
 926-----------------
 927
 928Where you might use ``kzalloc``, you can instead use ``kunit_kzalloc`` as KUnit
 929will then ensure that the memory is freed once the test completes.
 930
 931This is useful because it lets us use the ``KUNIT_ASSERT_EQ`` macros to exit
 932early from a test without having to worry about remembering to call ``kfree``.
 933For example:
 934
 935.. code-block:: c
 936
 937	void example_test_allocation(struct kunit *test)
 938	{
 939		char *buffer = kunit_kzalloc(test, 16, GFP_KERNEL);
 940		/* Ensure allocation succeeded. */
 941		KUNIT_ASSERT_NOT_ERR_OR_NULL(test, buffer);
 942
 943		KUNIT_ASSERT_STREQ(test, buffer, "");
 944	}
 945
 946Registering Cleanup Actions
 947---------------------------
 948
 949If you need to perform some cleanup beyond simple use of ``kunit_kzalloc``,
 950you can register a custom "deferred action", which is a cleanup function
 951run when the test exits (whether cleanly, or via a failed assertion).
 952
 953Actions are simple functions with no return value, and a single ``void*``
 954context argument, and fulfill the same role as "cleanup" functions in Python
 955and Go tests, "defer" statements in languages which support them, and
 956(in some cases) destructors in RAII languages.
 957
 958These are very useful for unregistering things from global lists, closing
 959files or other resources, or freeing resources.
 960
 961For example:
 962
 963.. code-block:: C
 964
 965	static void cleanup_device(void *ctx)
 966	{
 967		struct device *dev = (struct device *)ctx;
 968
 969		device_unregister(dev);
 970	}
 971
 972	void example_device_test(struct kunit *test)
 973	{
 974		struct my_device dev;
 975
 976		device_register(&dev);
 977
 978		kunit_add_action(test, &cleanup_device, &dev);
 979	}
 980
 981Note that, for functions like device_unregister which only accept a single
 982pointer-sized argument, it's possible to automatically generate a wrapper
 983with the ``KUNIT_DEFINE_ACTION_WRAPPER()`` macro, for example:
 984
 985.. code-block:: C
 986
 987	KUNIT_DEFINE_ACTION_WRAPPER(device_unregister, device_unregister_wrapper, struct device *);
 988	kunit_add_action(test, &device_unregister_wrapper, &dev);
 989
 990You should do this in preference to manually casting to the ``kunit_action_t`` type,
 991as casting function pointers will break Control Flow Integrity (CFI).
 992
 993``kunit_add_action`` can fail if, for example, the system is out of memory.
 994You can use ``kunit_add_action_or_reset`` instead which runs the action
 995immediately if it cannot be deferred.
 996
 997If you need more control over when the cleanup function is called, you
 998can trigger it early using ``kunit_release_action``, or cancel it entirely
 999with ``kunit_remove_action``.
1000
1001
1002Testing Static Functions
1003------------------------
1004
1005If you want to test static functions without exposing those functions outside of
1006testing, one option is conditionally export the symbol. When KUnit is enabled,
1007the symbol is exposed but remains static otherwise. To use this method, follow
1008the template below.
1009
1010.. code-block:: c
1011
1012	/* In the file containing functions to test "my_file.c" */
1013
1014	#include <kunit/visibility.h>
1015	#include <my_file.h>
1016	...
1017	VISIBLE_IF_KUNIT int do_interesting_thing()
1018	{
1019	...
1020	}
1021	EXPORT_SYMBOL_IF_KUNIT(do_interesting_thing);
1022
1023	/* In the header file "my_file.h" */
1024
1025	#if IS_ENABLED(CONFIG_KUNIT)
1026		int do_interesting_thing(void);
1027	#endif
1028
1029	/* In the KUnit test file "my_file_test.c" */
1030
1031	#include <kunit/visibility.h>
1032	#include <my_file.h>
1033	...
1034	MODULE_IMPORT_NS("EXPORTED_FOR_KUNIT_TESTING");
1035	...
1036	// Use do_interesting_thing() in tests
1037
1038For a full example, see this `patch <https://lore.kernel.org/all/20221207014024.340230-3-rmoar@google.com/>`_
1039where a test is modified to conditionally expose static functions for testing
1040using the macros above.
1041
1042As an **alternative** to the method above, you could conditionally ``#include``
1043the test file at the end of your .c file. This is not recommended but works
1044if needed. For example:
1045
1046.. code-block:: c
1047
1048	/* In "my_file.c" */
1049
1050	static int do_interesting_thing();
1051
1052	#ifdef CONFIG_MY_KUNIT_TEST
1053	#include "my_kunit_test.c"
1054	#endif
1055
1056Injecting Test-Only Code
1057------------------------
1058
1059Similar to as shown above, we can add test-specific logic. For example:
1060
1061.. code-block:: c
1062
1063	/* In my_file.h */
1064
1065	#ifdef CONFIG_MY_KUNIT_TEST
1066	/* Defined in my_kunit_test.c */
1067	void test_only_hook(void);
1068	#else
1069	void test_only_hook(void) { }
1070	#endif
1071
1072This test-only code can be made more useful by accessing the current ``kunit_test``
1073as shown in next section: *Accessing The Current Test*.
1074
1075Accessing The Current Test
1076--------------------------
1077
1078In some cases, we need to call test-only code from outside the test file.  This
1079is helpful, for example, when providing a fake implementation of a function, or
1080to fail any current test from within an error handler.
1081We can do this via the ``kunit_test`` field in ``task_struct``, which we can
1082access using the ``kunit_get_current_test()`` function in ``kunit/test-bug.h``.
1083
1084``kunit_get_current_test()`` is safe to call even if KUnit is not enabled. If
1085KUnit is not enabled, or if no test is running in the current task, it will
1086return ``NULL``. This compiles down to either a no-op or a static key check,
1087so will have a negligible performance impact when no test is running.
1088
1089The example below uses this to implement a "mock" implementation of a function, ``foo``:
1090
1091.. code-block:: c
1092
1093	#include <kunit/test-bug.h> /* for kunit_get_current_test */
1094
1095	struct test_data {
1096		int foo_result;
1097		int want_foo_called_with;
1098	};
1099
1100	static int fake_foo(int arg)
1101	{
1102		struct kunit *test = kunit_get_current_test();
1103		struct test_data *test_data = test->priv;
1104
1105		KUNIT_EXPECT_EQ(test, test_data->want_foo_called_with, arg);
1106		return test_data->foo_result;
1107	}
1108
1109	static void example_simple_test(struct kunit *test)
1110	{
1111		/* Assume priv (private, a member used to pass test data from
1112		 * the init function) is allocated in the suite's .init */
1113		struct test_data *test_data = test->priv;
1114
1115		test_data->foo_result = 42;
1116		test_data->want_foo_called_with = 1;
1117
1118		/* In a real test, we'd probably pass a pointer to fake_foo somewhere
1119		 * like an ops struct, etc. instead of calling it directly. */
1120		KUNIT_EXPECT_EQ(test, fake_foo(1), 42);
1121	}
1122
1123In this example, we are using the ``priv`` member of ``struct kunit`` as a way
1124of passing data to the test from the init function. In general ``priv`` is
1125pointer that can be used for any user data. This is preferred over static
1126variables, as it avoids concurrency issues.
1127
1128Had we wanted something more flexible, we could have used a named ``kunit_resource``.
1129Each test can have multiple resources which have string names providing the same
1130flexibility as a ``priv`` member, but also, for example, allowing helper
1131functions to create resources without conflicting with each other. It is also
1132possible to define a clean up function for each resource, making it easy to
1133avoid resource leaks. For more information, see Documentation/dev-tools/kunit/api/resource.rst.
1134
1135Failing The Current Test
1136------------------------
1137
1138If we want to fail the current test, we can use ``kunit_fail_current_test(fmt, args...)``
1139which is defined in ``<kunit/test-bug.h>`` and does not require pulling in ``<kunit/test.h>``.
1140For example, we have an option to enable some extra debug checks on some data
1141structures as shown below:
1142
1143.. code-block:: c
1144
1145	#include <kunit/test-bug.h>
1146
1147	#ifdef CONFIG_EXTRA_DEBUG_CHECKS
1148	static void validate_my_data(struct data *data)
1149	{
1150		if (is_valid(data))
1151			return;
1152
1153		kunit_fail_current_test("data %p is invalid", data);
1154
1155		/* Normal, non-KUnit, error reporting code here. */
1156	}
1157	#else
1158	static void my_debug_function(void) { }
1159	#endif
1160
1161``kunit_fail_current_test()`` is safe to call even if KUnit is not enabled. If
1162KUnit is not enabled, or if no test is running in the current task, it will do
1163nothing. This compiles down to either a no-op or a static key check, so will
1164have a negligible performance impact when no test is running.
1165
1166Managing Fake Devices and Drivers
1167---------------------------------
1168
1169When testing drivers or code which interacts with drivers, many functions will
1170require a ``struct device`` or ``struct device_driver``. In many cases, setting
1171up a real device is not required to test any given function, so a fake device
1172can be used instead.
1173
1174KUnit provides helper functions to create and manage these fake devices, which
1175are internally of type ``struct kunit_device``, and are attached to a special
1176``kunit_bus``. These devices support managed device resources (devres), as
1177described in Documentation/driver-api/driver-model/devres.rst
1178
1179To create a KUnit-managed ``struct device_driver``, use ``kunit_driver_create()``,
1180which will create a driver with the given name, on the ``kunit_bus``. This driver
1181will automatically be destroyed when the corresponding test finishes, but can also
1182be manually destroyed with ``driver_unregister()``.
1183
1184To create a fake device, use the ``kunit_device_register()``, which will create
1185and register a device, using a new KUnit-managed driver created with ``kunit_driver_create()``.
1186To provide a specific, non-KUnit-managed driver, use ``kunit_device_register_with_driver()``
1187instead. Like with managed drivers, KUnit-managed fake devices are automatically
1188cleaned up when the test finishes, but can be manually cleaned up early with
1189``kunit_device_unregister()``.
1190
1191The KUnit devices should be used in preference to ``root_device_register()``, and
1192instead of ``platform_device_register()`` in cases where the device is not otherwise
1193a platform device.
1194
1195For example:
1196
1197.. code-block:: c
1198
1199	#include <kunit/device.h>
1200
1201	static void test_my_device(struct kunit *test)
1202	{
1203		struct device *fake_device;
1204		const char *dev_managed_string;
1205
1206		// Create a fake device.
1207		fake_device = kunit_device_register(test, "my_device");
1208		KUNIT_ASSERT_NOT_ERR_OR_NULL(test, fake_device)
1209
1210		// Pass it to functions which need a device.
1211		dev_managed_string = devm_kstrdup(fake_device, "Hello, World!");
1212
1213		// Everything is cleaned up automatically when the test ends.
1214	}