€•     Œsphinx.addnodes”Œdocument”“”)”}”(Œ	rawsource”Œ ”Œchildren”]”(Œtranslations”ŒLanguagesNode”“”)”}”(hhh]”(h Œpending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ
attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ	refdomain”Œstd”Œreftype”Œdoc”Œ	reftarget”Œ)/translations/zh_CN/dev-tools/kunit/usage”Œmodname”NŒ	classname”NŒrefexplicit”ˆuŒtagname”hhhubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ)/translations/zh_TW/dev-tools/kunit/usage”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ)/translations/it_IT/dev-tools/kunit/usage”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ)/translations/ja_JP/dev-tools/kunit/usage”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ)/translations/ko_KR/dev-tools/kunit/usage”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒSpanish”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ)/translations/sp_SP/dev-tools/kunit/usage”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h
hhŒ	_document”hŒsource”NŒline”NubhŒcomment”“”)”}”(hŒ SPDX-License-Identifier: GPL-2.0”h]”hŒ SPDX-License-Identifier: GPL-2.0”…””}”hh£sbah}”(h]”h ]”h"]”h$]”h&]”Œ	xml:space”Œpreserve”uh1h¡hhhžhhŸŒC/var/lib/git/docbuild/linux/Documentation/dev-tools/kunit/usage.rst”h KubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒWriting Tests”h]”hŒWriting Tests”…””}”(hh»hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hh¶hžhhŸh³h Kubhµ)”}”(hhh]”(hº)”}”(hŒ
Test Cases”h]”hŒ
Test Cases”…””}”(hhÌhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hhÉhžhhŸh³h KubhŒ	paragraph”“”)”}”(hŒáThe fundamental unit in KUnit is the test case. A test case is a function with
the signature ``void (*)(struct kunit *test)``. It calls the function under test
and then sets *expectations* for what should happen. For example:”h]”(hŒ]The fundamental unit in KUnit is the test case. A test case is a function with
the signature ”…””}”(hhÜhžhhŸNh NubhŒliteral”“”)”}”(hŒ ``void (*)(struct kunit *test)``”h]”hŒvoid (*)(struct kunit *test)”…””}”(hhæhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähhÜubhŒ1. It calls the function under test
and then sets ”…””}”(hhÜhžhhŸNh NubhŒemphasis”“”)”}”(hŒ*expectations*”h]”hŒexpectations”…””}”(hhúhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1høhhÜubhŒ% for what should happen. For example:”…””}”(hhÜhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K	hhÉhžhubhŒliteral_block”“”)”}”(hŒ™void example_test_success(struct kunit *test)
{
}

void example_test_failure(struct kunit *test)
{
        KUNIT_FAIL(test, "This test never passes.");
}”h]”hŒ™void example_test_success(struct kunit *test)
{
}

void example_test_failure(struct kunit *test)
{
        KUNIT_FAIL(test, "This test never passes.");
}”…””}”hj  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²Œforce”‰Œlanguage”Œc”Œhighlight_args”}”uh1j  hŸh³h KhhÉhžhubhÛ)”}”(hXA  In the above example, ``example_test_success`` always passes because it does
nothing; no expectations are set, and therefore all expectations pass. On the
other hand ``example_test_failure`` always fails because it calls ``KUNIT_FAIL``,
which is a special expectation that logs a message and causes the test case to
fail.”h]”(hŒIn the above example, ”…””}”(hj'  hžhhŸNh Nubhå)”}”(hŒ``example_test_success``”h]”hŒexample_test_success”…””}”(hj/  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj'  ubhŒx always passes because it does
nothing; no expectations are set, and therefore all expectations pass. On the
other hand ”…””}”(hj'  hžhhŸNh Nubhå)”}”(hŒ``example_test_failure``”h]”hŒexample_test_failure”…””}”(hjA  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj'  ubhŒ always fails because it calls ”…””}”(hj'  hžhhŸNh Nubhå)”}”(hŒ``KUNIT_FAIL``”h]”hŒ
KUNIT_FAIL”…””}”(hjS  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj'  ubhŒV,
which is a special expectation that logs a message and causes the test case to
fail.”…””}”(hj'  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KhhÉhžhubhµ)”}”(hhh]”(hº)”}”(hŒExpectations”h]”hŒExpectations”…””}”(hjn  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjk  hžhhŸh³h KubhÛ)”}”(hXI  An *expectation* specifies that we expect a piece of code to do something in a
test. An expectation is called like a function. A test is made by setting
expectations about the behavior of a piece of code under test. When one or more
expectations fail, the test case fails and information about the failure is
logged. For example:”h]”(hŒAn ”…””}”(hj|  hžhhŸNh Nubhù)”}”(hŒ*expectation*”h]”hŒexpectation”…””}”(hj„  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1høhj|  ubhX9   specifies that we expect a piece of code to do something in a
test. An expectation is called like a function. A test is made by setting
expectations about the behavior of a piece of code under test. When one or more
expectations fail, the test case fails and information about the failure is
logged. For example:”…””}”(hj|  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K hjk  hžhubj  )”}”(hŒ…void add_test_basic(struct kunit *test)
{
        KUNIT_EXPECT_EQ(test, 1, add(1, 0));
        KUNIT_EXPECT_EQ(test, 2, add(1, 1));
}”h]”hŒ…void add_test_basic(struct kunit *test)
{
        KUNIT_EXPECT_EQ(test, 1, add(1, 0));
        KUNIT_EXPECT_EQ(test, 2, add(1, 1));
}”…””}”hjœ  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²j"  ‰j#  j$  j%  }”uh1j  hŸh³h K&hjk  hžhubhÛ)”}”(hXý  In the above example, ``add_test_basic`` makes a number of assertions about the
behavior of a function called ``add``. The first parameter is always of type
``struct kunit *``, which contains information about the current test context.
The second parameter, in this case, is what the value is expected to be. The
last value is what the value actually is. If ``add`` passes all of these
expectations, the test case, ``add_test_basic`` will pass; if any one of these
expectations fails, the test case will fail.”h]”(hŒIn the above example, ”…””}”(hj«  hžhhŸNh Nubhå)”}”(hŒ``add_test_basic``”h]”hŒadd_test_basic”…””}”(hj³  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj«  ubhŒF makes a number of assertions about the
behavior of a function called ”…””}”(hj«  hžhhŸNh Nubhå)”}”(hŒ``add``”h]”hŒadd”…””}”(hjÅ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj«  ubhŒ(. The first parameter is always of type
”…””}”(hj«  hžhhŸNh Nubhå)”}”(hŒ``struct kunit *``”h]”hŒstruct kunit *”…””}”(hj×  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj«  ubhŒ·, which contains information about the current test context.
The second parameter, in this case, is what the value is expected to be. The
last value is what the value actually is. If ”…””}”(hj«  hžhhŸNh Nubhå)”}”(hŒ``add``”h]”hŒadd”…””}”(hjé  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj«  ubhŒ2 passes all of these
expectations, the test case, ”…””}”(hj«  hžhhŸNh Nubhå)”}”(hŒ``add_test_basic``”h]”hŒadd_test_basic”…””}”(hjû  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj«  ubhŒL will pass; if any one of these
expectations fails, the test case will fail.”…””}”(hj«  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K.hjk  hžhubhÛ)”}”(hŒëA test case *fails* when any expectation is violated; however, the test will
continue to run, and try other expectations until the test case ends or is
otherwise terminated. This is as opposed to *assertions* which are discussed
later.”h]”(hŒA test case ”…””}”(hj  hžhhŸNh Nubhù)”}”(hŒ*fails*”h]”hŒfails”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1høhj  ubhŒ± when any expectation is violated; however, the test will
continue to run, and try other expectations until the test case ends or is
otherwise terminated. This is as opposed to ”…””}”(hj  hžhhŸNh Nubhù)”}”(hŒ*assertions*”h]”hŒ
assertions”…””}”(hj-  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1høhj  ubhŒ which are discussed
later.”…””}”(hj  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K6hjk  hžhubhÛ)”}”(hŒWTo learn about more KUnit expectations, see Documentation/dev-tools/kunit/api/test.rst.”h]”hŒWTo learn about more KUnit expectations, see Documentation/dev-tools/kunit/api/test.rst.”…””}”(hjE  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K;hjk  hžhubhŒnote”“”)”}”(hŒYA single test case should be short, easy to understand, and focused on a
single behavior.”h]”hÛ)”}”(hŒYA single test case should be short, easy to understand, and focused on a
single behavior.”h]”hŒYA single test case should be short, easy to understand, and focused on a
single behavior.”…””}”(hjY  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K>hjU  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jS  hjk  hžhhŸh³h NubhÛ)”}”(hŒ¸For example, if we want to rigorously test the ``add`` function above, create
additional tests cases which would test each property that an ``add`` function
should have as shown below:”h]”(hŒ/For example, if we want to rigorously test the ”…””}”(hjm  hžhhŸNh Nubhå)”}”(hŒ``add``”h]”hŒadd”…””}”(hju  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjm  ubhŒV function above, create
additional tests cases which would test each property that an ”…””}”(hjm  hžhhŸNh Nubhå)”}”(hŒ``add``”h]”hŒadd”…””}”(hj‡  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjm  ubhŒ% function
should have as shown below:”…””}”(hjm  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KAhjk  hžhubj  )”}”(hXê  void add_test_basic(struct kunit *test)
{
        KUNIT_EXPECT_EQ(test, 1, add(1, 0));
        KUNIT_EXPECT_EQ(test, 2, add(1, 1));
}

void add_test_negative(struct kunit *test)
{
        KUNIT_EXPECT_EQ(test, 0, add(-1, 1));
}

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

void add_test_overflow(struct kunit *test)
{
        KUNIT_EXPECT_EQ(test, INT_MIN, add(INT_MAX, 1));
}”h]”hXê  void add_test_basic(struct kunit *test)
{
        KUNIT_EXPECT_EQ(test, 1, add(1, 0));
        KUNIT_EXPECT_EQ(test, 2, add(1, 1));
}

void add_test_negative(struct kunit *test)
{
        KUNIT_EXPECT_EQ(test, 0, add(-1, 1));
}

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

void add_test_overflow(struct kunit *test)
{
        KUNIT_EXPECT_EQ(test, INT_MIN, add(INT_MAX, 1));
}”…””}”hjŸ  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²j"  ‰j#  j$  j%  }”uh1j  hŸh³h KEhjk  hžhubeh}”(h]”Œexpectations”ah ]”h"]”Œexpectations”ah$]”h&]”uh1h´hhÉhžhhŸh³h Kubhµ)”}”(hhh]”(hº)”}”(hŒ
Assertions”h]”hŒ
Assertions”…””}”(hj¹  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj¶  hžhhŸh³h K^ubhÛ)”}”(hŒ“An assertion is like an expectation, except that the assertion immediately
terminates the test case if the condition is not satisfied. For example:”h]”hŒ“An assertion is like an expectation, except that the assertion immediately
terminates the test case if the condition is not satisfied. For example:”…””}”(hjÇ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K`hj¶  hžhubj  )”}”(hXÊ  static void test_sort(struct kunit *test)
{
        int *a, i, r = 1;
        a = kunit_kmalloc_array(test, TEST_LEN, sizeof(*a), GFP_KERNEL);
        KUNIT_ASSERT_NOT_ERR_OR_NULL(test, a);
        for (i = 0; i < TEST_LEN; i++) {
                r = (r * 725861) % 6599;
                a[i] = r;
        }
        sort(a, TEST_LEN, sizeof(*a), cmpint, NULL);
        for (i = 0; i < TEST_LEN-1; i++)
                KUNIT_EXPECT_LE(test, a[i], a[i + 1]);
}”h]”hXÊ  static void test_sort(struct kunit *test)
{
        int *a, i, r = 1;
        a = kunit_kmalloc_array(test, TEST_LEN, sizeof(*a), GFP_KERNEL);
        KUNIT_ASSERT_NOT_ERR_OR_NULL(test, a);
        for (i = 0; i < TEST_LEN; i++) {
                r = (r * 725861) % 6599;
                a[i] = r;
        }
        sort(a, TEST_LEN, sizeof(*a), cmpint, NULL);
        for (i = 0; i < TEST_LEN-1; i++)
                KUNIT_EXPECT_LE(test, a[i], a[i + 1]);
}”…””}”hjÕ  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²j"  ‰j#  j$  j%  }”uh1j  hŸh³h Kchj¶  hžhubhÛ)”}”(hŒ¸In this example, we need to be able to allocate an array to test the ``sort()``
function. So we use ``KUNIT_ASSERT_NOT_ERR_OR_NULL()`` to abort the test if
there's an allocation error.”h]”(hŒEIn this example, we need to be able to allocate an array to test the ”…””}”(hjä  hžhhŸNh Nubhå)”}”(hŒ
``sort()``”h]”hŒsort()”…””}”(hjì  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjä  ubhŒ
function. So we use ”…””}”(hjä  hžhhŸNh Nubhå)”}”(hŒ"``KUNIT_ASSERT_NOT_ERR_OR_NULL()``”h]”hŒKUNIT_ASSERT_NOT_ERR_OR_NULL()”…””}”(hjþ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjä  ubhŒ4 to abort the test if
thereâ€™s an allocation error.”…””}”(hjä  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Kshj¶  hžhubjT  )”}”(hŒ×In other test frameworks, ``ASSERT`` macros are often implemented by calling
``return`` so they only work from the test function. In KUnit, we stop the
current kthread on failure, so you can call them from anywhere.”h]”hÛ)”}”(hŒ×In other test frameworks, ``ASSERT`` macros are often implemented by calling
``return`` so they only work from the test function. In KUnit, we stop the
current kthread on failure, so you can call them from anywhere.”h]”(hŒIn other test frameworks, ”…””}”(hj  hžhhŸNh Nubhå)”}”(hŒ
``ASSERT``”h]”hŒASSERT”…””}”(hj"  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj  ubhŒ) macros are often implemented by calling
”…””}”(hj  hžhhŸNh Nubhå)”}”(hŒ
``return``”h]”hŒreturn”…””}”(hj4  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj  ubhŒ€ so they only work from the test function. In KUnit, we stop the
current kthread on failure, so you can call them from anywhere.”…””}”(hj  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Kxhj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jS  hj¶  hžhhŸh³h NubjT  )”}”(hX&  Warning: There is an exception to the above rule. You shouldn't use assertions
in the suite's exit() function, or in the free function for a resource. These
run when a test is shutting down, and an assertion here prevents further
cleanup code from running, potentially leading to a memory leak.”h]”hÛ)”}”(hX&  Warning: There is an exception to the above rule. You shouldn't use assertions
in the suite's exit() function, or in the free function for a resource. These
run when a test is shutting down, and an assertion here prevents further
cleanup code from running, potentially leading to a memory leak.”h]”hX*  Warning: There is an exception to the above rule. You shouldnâ€™t use assertions
in the suiteâ€™s exit() function, or in the free function for a resource. These
run when a test is shutting down, and an assertion here prevents further
cleanup code from running, potentially leading to a memory leak.”…””}”(hjV  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K}hjR  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jS  hj¶  hžhhŸh³h Nubeh}”(h]”Œ
assertions”ah ]”h"]”Œ
assertions”ah$]”h&]”uh1h´hhÉhžhhŸh³h K^ubeh}”(h]”Œ
test-cases”ah ]”h"]”Œ
test cases”ah$]”h&]”uh1h´hh¶hžhhŸh³h Kubhµ)”}”(hhh]”(hº)”}”(hŒCustomizing error messages”h]”hŒCustomizing error messages”…””}”(hj}  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjz  hžhhŸh³h KƒubhÛ)”}”(hŒÈEach of the ``KUNIT_EXPECT`` and ``KUNIT_ASSERT`` macros have a ``_MSG``
variant.  These take a format string and arguments to provide additional
context to the automatically generated error messages.”h]”(hŒEach of the ”…””}”(hj‹  hžhhŸNh Nubhå)”}”(hŒ``KUNIT_EXPECT``”h]”hŒKUNIT_EXPECT”…””}”(hj“  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj‹  ubhŒ and ”…””}”(hj‹  hžhhŸNh Nubhå)”}”(hŒ``KUNIT_ASSERT``”h]”hŒKUNIT_ASSERT”…””}”(hj¥  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj‹  ubhŒ macros have a ”…””}”(hj‹  hžhhŸNh Nubhå)”}”(hŒ``_MSG``”h]”hŒ_MSG”…””}”(hj·  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj‹  ubhŒ€
variant.  These take a format string and arguments to provide additional
context to the automatically generated error messages.”…””}”(hj‹  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K…hjz  hžhubj  )”}”(hX  char some_str[41];
generate_sha1_hex_string(some_str);

/* Before. Not easy to tell why the test failed. */
KUNIT_EXPECT_EQ(test, strlen(some_str), 40);

/* After. Now we see the offending string. */
KUNIT_EXPECT_EQ_MSG(test, strlen(some_str), 40, "some_str='%s'", some_str);”h]”hX  char some_str[41];
generate_sha1_hex_string(some_str);

/* Before. Not easy to tell why the test failed. */
KUNIT_EXPECT_EQ(test, strlen(some_str), 40);

/* After. Now we see the offending string. */
KUNIT_EXPECT_EQ_MSG(test, strlen(some_str), 40, "some_str='%s'", some_str);”…””}”hjÏ  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²j"  ‰j#  j$  j%  }”uh1j  hŸh³h K‰hjz  hžhubhÛ)”}”(hŒ_Alternatively, one can take full control over the error message by using
``KUNIT_FAIL()``, e.g.”h]”(hŒIAlternatively, one can take full control over the error message by using
”…””}”(hjÞ  hžhhŸNh Nubhå)”}”(hŒ``KUNIT_FAIL()``”h]”hŒKUNIT_FAIL()”…””}”(hjæ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjÞ  ubhŒ, e.g.”…””}”(hjÞ  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K”hjz  hžhubj  )”}”(hŒÌ/* Before */
KUNIT_EXPECT_EQ(test, some_setup_function(), 0);

/* After: full control over the failure message. */
if (some_setup_function())
        KUNIT_FAIL(test, "Failed to setup thing for testing");”h]”hŒÌ/* Before */
KUNIT_EXPECT_EQ(test, some_setup_function(), 0);

/* After: full control over the failure message. */
if (some_setup_function())
        KUNIT_FAIL(test, "Failed to setup thing for testing");”…””}”hjþ  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²j"  ‰j#  j$  j%  }”uh1j  hŸh³h K—hjz  hžhubhµ)”}”(hhh]”(hº)”}”(hŒTest Suites”h]”hŒTest Suites”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj  hžhhŸh³h K¢ubhÛ)”}”(hXŸ  We need many test cases covering all the unit's behaviors. It is common to have
many similar tests. In order to reduce duplication in these closely related
tests, most unit testing frameworks (including KUnit) provide the concept of a
*test suite*. A test suite is a collection of test cases for a unit of code
with optional setup and teardown functions that run before/after the whole
suite and/or every test case.”h]”(hŒíWe need many test cases covering all the unitâ€™s behaviors. It is common to have
many similar tests. In order to reduce duplication in these closely related
tests, most unit testing frameworks (including KUnit) provide the concept of a
”…””}”(hj  hžhhŸNh Nubhù)”}”(hŒ*test suite*”h]”hŒ
test suite”…””}”(hj&  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1høhj  ubhŒ¨. A test suite is a collection of test cases for a unit of code
with optional setup and teardown functions that run before/after the whole
suite and/or every test case.”…””}”(hj  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K¤hj  hžhubjT  )”}”(hŒ@A test case will only run if it is associated with a test suite.”h]”hÛ)”}”(hj@  h]”hŒ@A test case will only run if it is associated with a test suite.”…””}”(hjB  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K¬hj>  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jS  hj  hžhhŸh³h NubhÛ)”}”(hŒFor example:”h]”hŒFor example:”…””}”(hjU  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K®hj  hžhubj  )”}”(hXë  static struct kunit_case example_test_cases[] = {
        KUNIT_CASE(example_test_foo),
        KUNIT_CASE(example_test_bar),
        KUNIT_CASE(example_test_baz),
        {}
};

static struct kunit_suite example_test_suite = {
        .name = "example",
        .init = example_test_init,
        .exit = example_test_exit,
        .suite_init = example_suite_init,
        .suite_exit = example_suite_exit,
        .test_cases = example_test_cases,
};
kunit_test_suite(example_test_suite);”h]”hXë  static struct kunit_case example_test_cases[] = {
        KUNIT_CASE(example_test_foo),
        KUNIT_CASE(example_test_bar),
        KUNIT_CASE(example_test_baz),
        {}
};

static struct kunit_suite example_test_suite = {
        .name = "example",
        .init = example_test_init,
        .exit = example_test_exit,
        .suite_init = example_suite_init,
        .suite_exit = example_suite_exit,
        .test_cases = example_test_cases,
};
kunit_test_suite(example_test_suite);”…””}”hjc  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²j"  ‰j#  j$  j%  }”uh1j  hŸh³h K°hj  hžhubhÛ)”}”(hXã  In the above example, the test suite ``example_test_suite`` would first run
``example_suite_init``, then run the test cases ``example_test_foo``,
``example_test_bar``, and ``example_test_baz``. Each would have
``example_test_init`` called immediately before it and ``example_test_exit``
called immediately after it. Finally, ``example_suite_exit`` would be called
after everything else. ``kunit_test_suite(example_test_suite)`` registers the
test suite with the KUnit test framework.”h]”(hŒ%In the above example, the test suite ”…””}”(hjr  hžhhŸNh Nubhå)”}”(hŒ``example_test_suite``”h]”hŒexample_test_suite”…””}”(hjz  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjr  ubhŒ would first run
”…””}”(hjr  hžhhŸNh Nubhå)”}”(hŒ``example_suite_init``”h]”hŒexample_suite_init”…””}”(hjŒ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjr  ubhŒ, then run the test cases ”…””}”(hjr  hžhhŸNh Nubhå)”}”(hŒ``example_test_foo``”h]”hŒexample_test_foo”…””}”(hjž  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjr  ubhŒ,
”…””}”(hjr  hžhhŸNh Nubhå)”}”(hŒ``example_test_bar``”h]”hŒexample_test_bar”…””}”(hj°  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjr  ubhŒ, and ”…””}”(hjr  hžhhŸNh Nubhå)”}”(hŒ``example_test_baz``”h]”hŒexample_test_baz”…””}”(hjÂ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjr  ubhŒ. Each would have
”…””}”(hjr  hžhhŸNh Nubhå)”}”(hŒ``example_test_init``”h]”hŒexample_test_init”…””}”(hjÔ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjr  ubhŒ" called immediately before it and ”…””}”(hjr  hžhhŸNh Nubhå)”}”(hŒ``example_test_exit``”h]”hŒexample_test_exit”…””}”(hjæ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjr  ubhŒ'
called immediately after it. Finally, ”…””}”(hjr  hžhhŸNh Nubhå)”}”(hŒ``example_suite_exit``”h]”hŒexample_suite_exit”…””}”(hjø  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjr  ubhŒ( would be called
after everything else. ”…””}”(hjr  hžhhŸNh Nubhå)”}”(hŒ(``kunit_test_suite(example_test_suite)``”h]”hŒ$kunit_test_suite(example_test_suite)”…””}”(hj
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjr  ubhŒ8 registers the
test suite with the KUnit test framework.”…””}”(hjr  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KÃhj  hžhubjT  )”}”(hŒèThe ``exit`` and ``suite_exit`` functions will run even if ``init`` or
``suite_init`` fail. Make sure that they can handle any inconsistent
state which may result from ``init`` or ``suite_init`` encountering errors
or exiting early.”h]”hÛ)”}”(hŒèThe ``exit`` and ``suite_exit`` functions will run even if ``init`` or
``suite_init`` fail. Make sure that they can handle any inconsistent
state which may result from ``init`` or ``suite_init`` encountering errors
or exiting early.”h]”(hŒThe ”…””}”(hj&  hžhhŸNh Nubhå)”}”(hŒ``exit``”h]”hŒexit”…””}”(hj.  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj&  ubhŒ and ”…””}”(hj&  hžhhŸNh Nubhå)”}”(hŒ``suite_exit``”h]”hŒ
suite_exit”…””}”(hj@  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj&  ubhŒ functions will run even if ”…””}”(hj&  hžhhŸNh Nubhå)”}”(hŒ``init``”h]”hŒinit”…””}”(hjR  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj&  ubhŒ or
”…””}”(hj&  hžhhŸNh Nubhå)”}”(hŒ``suite_init``”h]”hŒ
suite_init”…””}”(hjd  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj&  ubhŒS fail. Make sure that they can handle any inconsistent
state which may result from ”…””}”(hj&  hžhhŸNh Nubhå)”}”(hŒ``init``”h]”hŒinit”…””}”(hjv  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj&  ubhŒ or ”…””}”(hj&  hžhhŸNh Nubhå)”}”(hŒ``suite_init``”h]”hŒ
suite_init”…””}”(hjˆ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj&  ubhŒ& encountering errors
or exiting early.”…””}”(hj&  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KÌhj"  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jS  hj  hžhhŸh³h NubhÛ)”}”(hŒù``kunit_test_suite(...)`` is a macro which tells the linker to put the
specified test suite in a special linker section so that it can be run by KUnit
either after ``late_init``, or when the test module is loaded (if the test was
built as a module).”h]”(hå)”}”(hŒ``kunit_test_suite(...)``”h]”hŒkunit_test_suite(...)”…””}”(hjª  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj¦  ubhŒ‹ is a macro which tells the linker to put the
specified test suite in a special linker section so that it can be run by KUnit
either after ”…””}”(hj¦  hžhhŸNh Nubhå)”}”(hŒ``late_init``”h]”hŒ	late_init”…””}”(hj¼  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj¦  ubhŒH, or when the test module is loaded (if the test was
built as a module).”…””}”(hj¦  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KÑhj  hžhubhÛ)”}”(hŒEFor more information, see Documentation/dev-tools/kunit/api/test.rst.”h]”hŒEFor more information, see Documentation/dev-tools/kunit/api/test.rst.”…””}”(hjÔ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KÖhj  hžhubhŒtarget”“”)”}”(hŒ.. _kunit-on-non-uml:”h]”h}”(h]”h ]”h"]”h$]”h&]”Œrefid”Œkunit-on-non-uml”uh1jâ  h KØhj  hžhhŸh³ubeh}”(h]”Œtest-suites”ah ]”h"]”Œtest suites”ah$]”h&]”uh1h´hjz  hžhhŸh³h K¢ubeh}”(h]”Œcustomizing-error-messages”ah ]”h"]”Œcustomizing error messages”ah$]”h&]”uh1h´hh¶hžhhŸh³h Kƒubhµ)”}”(hhh]”(hº)”}”(hŒ%Writing Tests For Other Architectures”h]”hŒ%Writing Tests For Other Architectures”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj   hžhhŸh³h KÛubhÛ)”}”(hŒùIt is better to write tests that run on UML to tests that only run under a
particular architecture. It is better to write tests that run under QEMU or
another easy to obtain (and monetarily free) software environment to a specific
piece of hardware.”h]”hŒùIt is better to write tests that run on UML to tests that only run under a
particular architecture. It is better to write tests that run under QEMU or
another easy to obtain (and monetarily free) software environment to a specific
piece of hardware.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KÝhj   hžhubhÛ)”}”(hXÀ  Nevertheless, there are still valid reasons to write a test that is architecture
or hardware specific. For example, we might want to test code that really
belongs in ``arch/some-arch/*``. Even so, try to write the test so that it does
not depend on physical hardware. Some of our test cases may not need hardware,
only few tests actually require the hardware to test it. When hardware is not
available, instead of disabling tests, we can skip them.”h]”(hŒ¦Nevertheless, there are still valid reasons to write a test that is architecture
or hardware specific. For example, we might want to test code that really
belongs in ”…””}”(hj  hžhhŸNh Nubhå)”}”(hŒ``arch/some-arch/*``”h]”hŒarch/some-arch/*”…””}”(hj'  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj  ubhX  . Even so, try to write the test so that it does
not depend on physical hardware. Some of our test cases may not need hardware,
only few tests actually require the hardware to test it. When hardware is not
available, instead of disabling tests, we can skip them.”…””}”(hj  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Kâhj   hžhubhÛ)”}”(hŒ¥Now that we have narrowed down exactly what bits are hardware specific, the
actual procedure for writing and running the tests is same as writing normal
KUnit tests.”h]”hŒ¥Now that we have narrowed down exactly what bits are hardware specific, the
actual procedure for writing and running the tests is same as writing normal
KUnit tests.”…””}”(hj?  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Kéhj   hžhubhŒ	important”“”)”}”(hŒvWe may have to reset hardware state. If this is not possible, we may only
be able to run one test case per invocation.”h]”hÛ)”}”(hŒvWe may have to reset hardware state. If this is not possible, we may only
be able to run one test case per invocation.”h]”hŒvWe may have to reset hardware state. If this is not possible, we may only
be able to run one test case per invocation.”…””}”(hjS  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KîhjO  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jM  hj   hžhhŸh³h Nubh¢)”}”(hŒ`TODO(brendanhiggins@google.com): Add an actual example of an architecture-
dependent KUnit test.”h]”hŒ`TODO(brendanhiggins@google.com): Add an actual example of an architecture-
dependent KUnit test.”…””}”hjg  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1h¡hj   hžhhŸh³h Kóubeh}”(h]”(Œ%writing-tests-for-other-architectures”jï  eh ]”h"]”(Œ%writing tests for other architectures”Œkunit-on-non-uml”eh$]”h&]”uh1h´hh¶hžhhŸh³h KÛŒexpect_referenced_by_name”}”j{  jä  sŒexpect_referenced_by_id”}”jï  jä  subeh}”(h]”Œwriting-tests”ah ]”h"]”Œwriting tests”ah$]”h&]”uh1h´hhhžhhŸh³h Kubhµ)”}”(hhh]”(hº)”}”(hŒCommon Patterns”h]”hŒCommon Patterns”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjŠ  hžhhŸh³h Kõubhµ)”}”(hhh]”(hº)”}”(hŒIsolating Behavior”h]”hŒIsolating Behavior”…””}”(hjž  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj›  hžhhŸh³h KøubhÛ)”}”(hXý  Unit testing limits the amount of code under test to a single unit. It controls
what code gets run when the unit under test calls a function. Where a function
is exposed as part of an API such that the definition of that function can be
changed without affecting the rest of the code base. In the kernel, this comes
from two constructs: classes, which are structs that contain function pointers
provided by the implementer, and architecture-specific functions, which have
definitions selected at compile time.”h]”hXý  Unit testing limits the amount of code under test to a single unit. It controls
what code gets run when the unit under test calls a function. Where a function
is exposed as part of an API such that the definition of that function can be
changed without affecting the rest of the code base. In the kernel, this comes
from two constructs: classes, which are structs that contain function pointers
provided by the implementer, and architecture-specific functions, which have
definitions selected at compile time.”…””}”(hj¬  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Kúhj›  hžhubhµ)”}”(hhh]”(hº)”}”(hŒClasses”h]”hŒClasses”…””}”(hj½  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjº  hžhhŸh³h MubhÛ)”}”(hX[  Classes are not a construct that is built into the C programming language;
however, it is an easily derived concept. Accordingly, in most cases, every
project that does not use a standardized object oriented library (like GNOME's
GObject) has their own slightly different way of doing object oriented
programming; the Linux kernel is no exception.”h]”hX]  Classes are not a construct that is built into the C programming language;
however, it is an easily derived concept. Accordingly, in most cases, every
project that does not use a standardized object oriented library (like GNOMEâ€™s
GObject) has their own slightly different way of doing object oriented
programming; the Linux kernel is no exception.”…””}”(hjË  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mhjº  hžhubhÛ)”}”(hX^  The central concept in kernel object oriented programming is the class. In the
kernel, a *class* is a struct that contains function pointers. This creates a
contract between *implementers* and *users* since it forces them to use the
same function signature without having to call the function directly. To be a
class, the function pointers must specify that a pointer to the class, known as
a *class handle*, be one of the parameters. Thus the member functions (also
known as *methods*) have access to member variables (also known as *fields*)
allowing the same implementation to have multiple *instances*.”h]”(hŒYThe central concept in kernel object oriented programming is the class. In the
kernel, a ”…””}”(hjÙ  hžhhŸNh Nubhù)”}”(hŒ*class*”h]”hŒclass”…””}”(hjá  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1høhjÙ  ubhŒN is a struct that contains function pointers. This creates a
contract between ”…””}”(hjÙ  hžhhŸNh Nubhù)”}”(hŒ*implementers*”h]”hŒimplementers”…””}”(hjó  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1høhjÙ  ubhŒ and ”…””}”(hjÙ  hžhhŸNh Nubhù)”}”(hŒ*users*”h]”hŒusers”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1høhjÙ  ubhŒÁ since it forces them to use the
same function signature without having to call the function directly. To be a
class, the function pointers must specify that a pointer to the class, known as
a ”…””}”(hjÙ  hžhhŸNh Nubhù)”}”(hŒ*class handle*”h]”hŒclass handle”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1høhjÙ  ubhŒE, be one of the parameters. Thus the member functions (also
known as ”…””}”(hjÙ  hžhhŸNh Nubhù)”}”(hŒ	*methods*”h]”hŒmethods”…””}”(hj)  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1høhjÙ  ubhŒ1) have access to member variables (also known as ”…””}”(hjÙ  hžhhŸNh Nubhù)”}”(hŒ*fields*”h]”hŒfields”…””}”(hj;  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1høhjÙ  ubhŒ4)
allowing the same implementation to have multiple ”…””}”(hjÙ  hžhhŸNh Nubhù)”}”(hŒ*instances*”h]”hŒ	instances”…””}”(hjM  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1høhjÙ  ubhŒ.”…””}”(hjÙ  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mhjº  hžhubhÛ)”}”(hXØ  A class can be *overridden* by *child classes* by embedding the *parent class*
in the child class. Then when the child class *method* is called, the child
implementation knows that the pointer passed to it is of a parent contained
within the child. Thus, the child can compute the pointer to itself because the
pointer to the parent is always a fixed offset from the pointer to the child.
This offset is the offset of the parent contained in the child struct. For
example:”h]”(hŒA class can be ”…””}”(hje  hžhhŸNh Nubhù)”}”(hŒ*overridden*”h]”hŒ
overridden”…””}”(hjm  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1høhje  ubhŒ by ”…””}”(hje  hžhhŸNh Nubhù)”}”(hŒ*child classes*”h]”hŒchild classes”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1høhje  ubhŒ by embedding the ”…””}”(hje  hžhhŸNh Nubhù)”}”(hŒ*parent class*”h]”hŒparent class”…””}”(hj‘  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1høhje  ubhŒ/
in the child class. Then when the child class ”…””}”(hje  hžhhŸNh Nubhù)”}”(hŒ*method*”h]”hŒmethod”…””}”(hj£  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1høhje  ubhXS   is called, the child
implementation knows that the pointer passed to it is of a parent contained
within the child. Thus, the child can compute the pointer to itself because the
pointer to the parent is always a fixed offset from the pointer to the child.
This offset is the offset of the parent contained in the child struct. For
example:”…””}”(hje  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mhjº  hžhubj  )”}”(hXì  struct shape {
        int (*area)(struct shape *this);
};

struct rectangle {
        struct shape parent;
        int length;
        int width;
};

int rectangle_area(struct shape *this)
{
        struct rectangle *self = container_of(this, struct rectangle, parent);

        return self->length * self->width;
};

void rectangle_new(struct rectangle *self, int length, int width)
{
        self->parent.area = rectangle_area;
        self->length = length;
        self->width = width;
}”h]”hXì  struct shape {
        int (*area)(struct shape *this);
};

struct rectangle {
        struct shape parent;
        int length;
        int width;
};

int rectangle_area(struct shape *this)
{
        struct rectangle *self = container_of(this, struct rectangle, parent);

        return self->length * self->width;
};

void rectangle_new(struct rectangle *self, int length, int width)
{
        self->parent.area = rectangle_area;
        self->length = length;
        self->width = width;
}”…””}”hj»  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²j"  ‰j#  j$  j%  }”uh1j  hŸh³h Mhjº  hžhubhÛ)”}”(hŒoIn this example, computing the pointer to the child from the pointer to the
parent is done by ``container_of``.”h]”(hŒ^In this example, computing the pointer to the child from the pointer to the
parent is done by ”…””}”(hjÊ  hžhhŸNh Nubhå)”}”(hŒ``container_of``”h]”hŒcontainer_of”…””}”(hjÒ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjÊ  ubhŒ.”…””}”(hjÊ  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M6hjº  hžhubeh}”(h]”Œclasses”ah ]”h"]”Œclasses”ah$]”h&]”uh1h´hj›  hžhhŸh³h Mubhµ)”}”(hhh]”(hº)”}”(hŒFaking Classes”h]”hŒFaking Classes”…””}”(hjõ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjò  hžhhŸh³h M:ubhÛ)”}”(hŒÃIn order to unit test a piece of code that calls a method in a class, the
behavior of the method must be controllable, otherwise the test ceases to be a
unit test and becomes an integration test.”h]”hŒÃIn order to unit test a piece of code that calls a method in a class, the
behavior of the method must be controllable, otherwise the test ceases to be a
unit test and becomes an integration test.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M<hjò  hžhubhÛ)”}”(hXt  A fake class implements a piece of code that is different than what runs in a
production instance, but behaves identical from the standpoint of the callers.
This is done to replace a dependency that is hard to deal with, or is slow. For
example, implementing a fake EEPROM that stores the "contents" in an
internal buffer. Assume we have a class that represents an EEPROM:”h]”hXx  A fake class implements a piece of code that is different than what runs in a
production instance, but behaves identical from the standpoint of the callers.
This is done to replace a dependency that is hard to deal with, or is slow. For
example, implementing a fake EEPROM that stores the â€œcontentsâ€ in an
internal buffer. Assume we have a class that represents an EEPROM:”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M@hjò  hžhubj  )”}”(hŒËstruct eeprom {
        ssize_t (*read)(struct eeprom *this, size_t offset, char *buffer, size_t count);
        ssize_t (*write)(struct eeprom *this, size_t offset, const char *buffer, size_t count);
};”h]”hŒËstruct eeprom {
        ssize_t (*read)(struct eeprom *this, size_t offset, char *buffer, size_t count);
        ssize_t (*write)(struct eeprom *this, size_t offset, const char *buffer, size_t count);
};”…””}”hj  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²j"  ‰j#  j$  j%  }”uh1j  hŸh³h MFhjò  hžhubhÛ)”}”(hŒ;And we want to test code that buffers writes to the EEPROM:”h]”hŒ;And we want to test code that buffers writes to the EEPROM:”…””}”(hj.  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MMhjò  hžhubj  )”}”(hX_  struct eeprom_buffer {
        ssize_t (*write)(struct eeprom_buffer *this, const char *buffer, size_t count);
        int flush(struct eeprom_buffer *this);
        size_t flush_count; /* Flushes when buffer exceeds flush_count. */
};

struct eeprom_buffer *new_eeprom_buffer(struct eeprom *eeprom);
void destroy_eeprom_buffer(struct eeprom *eeprom);”h]”hX_  struct eeprom_buffer {
        ssize_t (*write)(struct eeprom_buffer *this, const char *buffer, size_t count);
        int flush(struct eeprom_buffer *this);
        size_t flush_count; /* Flushes when buffer exceeds flush_count. */
};

struct eeprom_buffer *new_eeprom_buffer(struct eeprom *eeprom);
void destroy_eeprom_buffer(struct eeprom *eeprom);”…””}”hj<  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²j"  ‰j#  j$  j%  }”uh1j  hŸh³h MOhjò  hžhubhÛ)”}”(hŒ<We can test this code by *faking out* the underlying EEPROM:”h]”(hŒWe can test this code by ”…””}”(hjK  hžhhŸNh Nubhù)”}”(hŒ*faking out*”h]”hŒ
faking out”…””}”(hjS  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1høhjK  ubhŒ the underlying EEPROM:”…””}”(hjK  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MZhjò  hžhubj  )”}”(hXÉ  struct fake_eeprom {
        struct eeprom parent;
        char contents[FAKE_EEPROM_CONTENTS_SIZE];
};

ssize_t fake_eeprom_read(struct eeprom *parent, size_t offset, char *buffer, size_t count)
{
        struct fake_eeprom *this = container_of(parent, struct fake_eeprom, parent);

        count = min(count, FAKE_EEPROM_CONTENTS_SIZE - offset);
        memcpy(buffer, this->contents + offset, count);

        return count;
}

ssize_t fake_eeprom_write(struct eeprom *parent, size_t offset, const char *buffer, size_t count)
{
        struct fake_eeprom *this = container_of(parent, struct fake_eeprom, parent);

        count = min(count, FAKE_EEPROM_CONTENTS_SIZE - offset);
        memcpy(this->contents + offset, buffer, count);

        return count;
}

void fake_eeprom_init(struct fake_eeprom *this)
{
        this->parent.read = fake_eeprom_read;
        this->parent.write = fake_eeprom_write;
        memset(this->contents, 0, FAKE_EEPROM_CONTENTS_SIZE);
}”h]”hXÉ  struct fake_eeprom {
        struct eeprom parent;
        char contents[FAKE_EEPROM_CONTENTS_SIZE];
};

ssize_t fake_eeprom_read(struct eeprom *parent, size_t offset, char *buffer, size_t count)
{
        struct fake_eeprom *this = container_of(parent, struct fake_eeprom, parent);

        count = min(count, FAKE_EEPROM_CONTENTS_SIZE - offset);
        memcpy(buffer, this->contents + offset, count);

        return count;
}

ssize_t fake_eeprom_write(struct eeprom *parent, size_t offset, const char *buffer, size_t count)
{
        struct fake_eeprom *this = container_of(parent, struct fake_eeprom, parent);

        count = min(count, FAKE_EEPROM_CONTENTS_SIZE - offset);
        memcpy(this->contents + offset, buffer, count);

        return count;
}

void fake_eeprom_init(struct fake_eeprom *this)
{
        this->parent.read = fake_eeprom_read;
        this->parent.write = fake_eeprom_write;
        memset(this->contents, 0, FAKE_EEPROM_CONTENTS_SIZE);
}”…””}”hjk  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²j"  ‰j#  j$  j%  }”uh1j  hŸh³h M\hjò  hžhubhÛ)”}”(hŒ3We can now use it to test ``struct eeprom_buffer``:”h]”(hŒWe can now use it to test ”…””}”(hjz  hžhhŸNh Nubhå)”}”(hŒ``struct eeprom_buffer``”h]”hŒstruct eeprom_buffer”…””}”(hj‚  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjz  ubhŒ:”…””}”(hjz  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M~hjò  hžhubj  )”}”(hXÓ  struct eeprom_buffer_test {
        struct fake_eeprom *fake_eeprom;
        struct eeprom_buffer *eeprom_buffer;
};

static void eeprom_buffer_test_does_not_write_until_flush(struct kunit *test)
{
        struct eeprom_buffer_test *ctx = test->priv;
        struct eeprom_buffer *eeprom_buffer = ctx->eeprom_buffer;
        struct fake_eeprom *fake_eeprom = ctx->fake_eeprom;
        char buffer[] = {0xff};

        eeprom_buffer->flush_count = SIZE_MAX;

        eeprom_buffer->write(eeprom_buffer, buffer, 1);
        KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0);

        eeprom_buffer->write(eeprom_buffer, buffer, 1);
        KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0);

        eeprom_buffer->flush(eeprom_buffer);
        KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0xff);
        KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0xff);
}

static void eeprom_buffer_test_flushes_after_flush_count_met(struct kunit *test)
{
        struct eeprom_buffer_test *ctx = test->priv;
        struct eeprom_buffer *eeprom_buffer = ctx->eeprom_buffer;
        struct fake_eeprom *fake_eeprom = ctx->fake_eeprom;
        char buffer[] = {0xff};

        eeprom_buffer->flush_count = 2;

        eeprom_buffer->write(eeprom_buffer, buffer, 1);
        KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0);

        eeprom_buffer->write(eeprom_buffer, buffer, 1);
        KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0xff);
        KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0xff);
}

static void eeprom_buffer_test_flushes_increments_of_flush_count(struct kunit *test)
{
        struct eeprom_buffer_test *ctx = test->priv;
        struct eeprom_buffer *eeprom_buffer = ctx->eeprom_buffer;
        struct fake_eeprom *fake_eeprom = ctx->fake_eeprom;
        char buffer[] = {0xff, 0xff};

        eeprom_buffer->flush_count = 2;

        eeprom_buffer->write(eeprom_buffer, buffer, 1);
        KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0);

        eeprom_buffer->write(eeprom_buffer, buffer, 2);
        KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0xff);
        KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0xff);
        /* Should have only flushed the first two bytes. */
        KUNIT_EXPECT_EQ(test, fake_eeprom->contents[2], 0);
}

static int eeprom_buffer_test_init(struct kunit *test)
{
        struct eeprom_buffer_test *ctx;

        ctx = kunit_kzalloc(test, sizeof(*ctx), GFP_KERNEL);
        KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ctx);

        ctx->fake_eeprom = kunit_kzalloc(test, sizeof(*ctx->fake_eeprom), GFP_KERNEL);
        KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ctx->fake_eeprom);
        fake_eeprom_init(ctx->fake_eeprom);

        ctx->eeprom_buffer = new_eeprom_buffer(&ctx->fake_eeprom->parent);
        KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ctx->eeprom_buffer);

        test->priv = ctx;

        return 0;
}

static void eeprom_buffer_test_exit(struct kunit *test)
{
        struct eeprom_buffer_test *ctx = test->priv;

        destroy_eeprom_buffer(ctx->eeprom_buffer);
}”h]”hXÓ  struct eeprom_buffer_test {
        struct fake_eeprom *fake_eeprom;
        struct eeprom_buffer *eeprom_buffer;
};

static void eeprom_buffer_test_does_not_write_until_flush(struct kunit *test)
{
        struct eeprom_buffer_test *ctx = test->priv;
        struct eeprom_buffer *eeprom_buffer = ctx->eeprom_buffer;
        struct fake_eeprom *fake_eeprom = ctx->fake_eeprom;
        char buffer[] = {0xff};

        eeprom_buffer->flush_count = SIZE_MAX;

        eeprom_buffer->write(eeprom_buffer, buffer, 1);
        KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0);

        eeprom_buffer->write(eeprom_buffer, buffer, 1);
        KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0);

        eeprom_buffer->flush(eeprom_buffer);
        KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0xff);
        KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0xff);
}

static void eeprom_buffer_test_flushes_after_flush_count_met(struct kunit *test)
{
        struct eeprom_buffer_test *ctx = test->priv;
        struct eeprom_buffer *eeprom_buffer = ctx->eeprom_buffer;
        struct fake_eeprom *fake_eeprom = ctx->fake_eeprom;
        char buffer[] = {0xff};

        eeprom_buffer->flush_count = 2;

        eeprom_buffer->write(eeprom_buffer, buffer, 1);
        KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0);

        eeprom_buffer->write(eeprom_buffer, buffer, 1);
        KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0xff);
        KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0xff);
}

static void eeprom_buffer_test_flushes_increments_of_flush_count(struct kunit *test)
{
        struct eeprom_buffer_test *ctx = test->priv;
        struct eeprom_buffer *eeprom_buffer = ctx->eeprom_buffer;
        struct fake_eeprom *fake_eeprom = ctx->fake_eeprom;
        char buffer[] = {0xff, 0xff};

        eeprom_buffer->flush_count = 2;

        eeprom_buffer->write(eeprom_buffer, buffer, 1);
        KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0);

        eeprom_buffer->write(eeprom_buffer, buffer, 2);
        KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0xff);
        KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0xff);
        /* Should have only flushed the first two bytes. */
        KUNIT_EXPECT_EQ(test, fake_eeprom->contents[2], 0);
}

static int eeprom_buffer_test_init(struct kunit *test)
{
        struct eeprom_buffer_test *ctx;

        ctx = kunit_kzalloc(test, sizeof(*ctx), GFP_KERNEL);
        KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ctx);

        ctx->fake_eeprom = kunit_kzalloc(test, sizeof(*ctx->fake_eeprom), GFP_KERNEL);
        KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ctx->fake_eeprom);
        fake_eeprom_init(ctx->fake_eeprom);

        ctx->eeprom_buffer = new_eeprom_buffer(&ctx->fake_eeprom->parent);
        KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ctx->eeprom_buffer);

        test->priv = ctx;

        return 0;
}

static void eeprom_buffer_test_exit(struct kunit *test)
{
        struct eeprom_buffer_test *ctx = test->priv;

        destroy_eeprom_buffer(ctx->eeprom_buffer);
}”…””}”hjš  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²j"  ‰j#  j$  j%  }”uh1j  hŸh³h M€hjò  hžhubeh}”(h]”Œfaking-classes”ah ]”h"]”Œfaking classes”ah$]”h&]”uh1h´hj›  hžhhŸh³h M:ubeh}”(h]”Œisolating-behavior”ah ]”h"]”Œisolating behavior”ah$]”h&]”uh1h´hjŠ  hžhhŸh³h Køubhµ)”}”(hhh]”(hº)”}”(hŒTesting Against Multiple Inputs”h]”hŒTesting Against Multiple Inputs”…””}”(hj¼  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj¹  hžhhŸh³h MÚubhÛ)”}”(hŒvTesting just a few inputs is not enough to ensure that the code works correctly,
for example: testing a hash function.”h]”hŒvTesting just a few inputs is not enough to ensure that the code works correctly,
for example: testing a hash function.”…””}”(hjÊ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MÜhj¹  hžhubhÛ)”}”(hŒ‚We can write a helper macro or function. The function is called for each input.
For example, to test ``sha1sum(1)``, we can write:”h]”(hŒeWe can write a helper macro or function. The function is called for each input.
For example, to test ”…””}”(hjØ  hžhhŸNh Nubhå)”}”(hŒ``sha1sum(1)``”h]”hŒ
sha1sum(1)”…””}”(hjà  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjØ  ubhŒ, we can write:”…””}”(hjØ  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mßhj¹  hžhubj  )”}”(hX  #define TEST_SHA1(in, want) \
        sha1sum(in, out); \
        KUNIT_EXPECT_STREQ_MSG(test, out, want, "sha1sum(%s)", in);

char out[40];
TEST_SHA1("hello world",  "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed");
TEST_SHA1("hello world!", "430ce34d020724ed75a196dfc2ad67c77772d169");”h]”hX  #define TEST_SHA1(in, want) \
        sha1sum(in, out); \
        KUNIT_EXPECT_STREQ_MSG(test, out, want, "sha1sum(%s)", in);

char out[40];
TEST_SHA1("hello world",  "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed");
TEST_SHA1("hello world!", "430ce34d020724ed75a196dfc2ad67c77772d169");”…””}”hjø  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²j"  ‰j#  j$  j%  }”uh1j  hŸh³h Mâhj¹  hžhubhÛ)”}”(hŒ—Note the use of the ``_MSG`` version of ``KUNIT_EXPECT_STREQ`` to print a more
detailed error and make the assertions clearer within the helper macros.”h]”(hŒNote the use of the ”…””}”(hj	  hžhhŸNh Nubhå)”}”(hŒ``_MSG``”h]”hŒ_MSG”…””}”(hj	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj	  ubhŒ version of ”…””}”(hj	  hžhhŸNh Nubhå)”}”(hŒ``KUNIT_EXPECT_STREQ``”h]”hŒKUNIT_EXPECT_STREQ”…””}”(hj!	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj	  ubhŒY to print a more
detailed error and make the assertions clearer within the helper macros.”…””}”(hj	  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mìhj¹  hžhubhÛ)”}”(hŒÂThe ``_MSG`` variants are useful when the same expectation is called multiple
times (in a loop or helper function) and thus the line number is not enough to
identify what failed, as shown below.”h]”(hŒThe ”…””}”(hj9	  hžhhŸNh Nubhå)”}”(hŒ``_MSG``”h]”hŒ_MSG”…””}”(hjA	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj9	  ubhŒ¶ variants are useful when the same expectation is called multiple
times (in a loop or helper function) and thus the line number is not enough to
identify what failed, as shown below.”…””}”(hj9	  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mïhj¹  hžhubhÛ)”}”(hŒsIn complicated cases, we recommend using a *table-driven test* compared to the
helper macro variation, for example:”h]”(hŒ+In complicated cases, we recommend using a ”…””}”(hjY	  hžhhŸNh Nubhù)”}”(hŒ*table-driven test*”h]”hŒtable-driven test”…””}”(hja	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1høhjY	  ubhŒ5 compared to the
helper macro variation, for example:”…””}”(hjY	  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Móhj¹  hžhubj  )”}”(hXM  int i;
char out[40];

struct sha1_test_case {
        const char *str;
        const char *sha1;
};

struct sha1_test_case cases[] = {
        {
                .str = "hello world",
                .sha1 = "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed",
        },
        {
                .str = "hello world!",
                .sha1 = "430ce34d020724ed75a196dfc2ad67c77772d169",
        },
};
for (i = 0; i < ARRAY_SIZE(cases); ++i) {
        sha1sum(cases[i].str, out);
        KUNIT_EXPECT_STREQ_MSG(test, out, cases[i].sha1,
                              "sha1sum(%s)", cases[i].str);
}”h]”hXM  int i;
char out[40];

struct sha1_test_case {
        const char *str;
        const char *sha1;
};

struct sha1_test_case cases[] = {
        {
                .str = "hello world",
                .sha1 = "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed",
        },
        {
                .str = "hello world!",
                .sha1 = "430ce34d020724ed75a196dfc2ad67c77772d169",
        },
};
for (i = 0; i < ARRAY_SIZE(cases); ++i) {
        sha1sum(cases[i].str, out);
        KUNIT_EXPECT_STREQ_MSG(test, out, cases[i].sha1,
                              "sha1sum(%s)", cases[i].str);
}”…””}”hjy	  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²j"  ‰j#  j$  j%  }”uh1j  hŸh³h Möhj¹  hžhubhÛ)”}”(hŒ4There is more boilerplate code involved, but it can:”h]”hŒ4There is more boilerplate code involved, but it can:”…””}”(hjˆ	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mhj¹  hžhubhŒbullet_list”“”)”}”(hhh]”(hŒ	list_item”“”)”}”(hŒ|be more readable when there are multiple inputs/outputs (due to field names).

* For example, see ``fs/ext4/inode-test.c``.
”h]”(hÛ)”}”(hŒMbe more readable when there are multiple inputs/outputs (due to field names).”h]”hŒMbe more readable when there are multiple inputs/outputs (due to field names).”…””}”(hj¡	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mhj	  ubj—	  )”}”(hhh]”jœ	  )”}”(hŒ+For example, see ``fs/ext4/inode-test.c``.
”h]”hÛ)”}”(hŒ*For example, see ``fs/ext4/inode-test.c``.”h]”(hŒFor example, see ”…””}”(hj¶	  hžhhŸNh Nubhå)”}”(hŒ``fs/ext4/inode-test.c``”h]”hŒfs/ext4/inode-test.c”…””}”(hj¾	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj¶	  ubhŒ.”…””}”(hj¶	  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mhj²	  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j›	  hj¯	  ubah}”(h]”h ]”h"]”h$]”h&]”Œbullet”Œ*”uh1j–	  hŸh³h Mhj	  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j›	  hj˜	  hžhhŸNh Nubjœ	  )”}”(hŒ¬reduce duplication if test cases are shared across multiple tests.

* For example: if we want to test ``sha256sum``, we could add a ``sha256``
  field and reuse ``cases``.
”h]”(hÛ)”}”(hŒBreduce duplication if test cases are shared across multiple tests.”h]”hŒBreduce duplication if test cases are shared across multiple tests.”…””}”(hjî	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mhjê	  ubj—	  )”}”(hhh]”jœ	  )”}”(hŒdFor example: if we want to test ``sha256sum``, we could add a ``sha256``
field and reuse ``cases``.
”h]”hÛ)”}”(hŒcFor example: if we want to test ``sha256sum``, we could add a ``sha256``
field and reuse ``cases``.”h]”(hŒ For example: if we want to test ”…””}”(hj
  hžhhŸNh Nubhå)”}”(hŒ``sha256sum``”h]”hŒ	sha256sum”…””}”(hj
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj
  ubhŒ, we could add a ”…””}”(hj
  hžhhŸNh Nubhå)”}”(hŒ
``sha256``”h]”hŒsha256”…””}”(hj
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj
  ubhŒ
field and reuse ”…””}”(hj
  hžhhŸNh Nubhå)”}”(hŒ	``cases``”h]”hŒcases”…””}”(hj/
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj
  ubhŒ.”…””}”(hj
  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mhjÿ	  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j›	  hjü	  ubah}”(h]”h ]”h"]”h$]”h&]”jâ	  jã	  uh1j–	  hŸh³h Mhjê	  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j›	  hj˜	  hžhhŸNh Nubjœ	  )”}”(hŒ(be converted to a "parameterized test".
”h]”hÛ)”}”(hŒ'be converted to a "parameterized test".”h]”hŒ+be converted to a â€œparameterized testâ€.”…””}”(hj]
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MhjY
  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j›	  hj˜	  hžhhŸh³h Nubeh}”(h]”h ]”h"]”h$]”h&]”jâ	  jã	  uh1j–	  hŸh³h Mhj¹  hžhubhµ)”}”(hhh]”(hº)”}”(hŒParameterized Testing”h]”hŒParameterized Testing”…””}”(hjz
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjw
  hžhhŸh³h MubhÛ)”}”(hŒ¹To run a test case against multiple inputs, KUnit provides a parameterized
testing framework. This feature formalizes and extends the concept of
table-driven tests discussed previously.”h]”hŒ¹To run a test case against multiple inputs, KUnit provides a parameterized
testing framework. This feature formalizes and extends the concept of
table-driven tests discussed previously.”…””}”(hjˆ
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M!hjw
  hžhubhÛ)”}”(hXa  A KUnit test is determined to be parameterized if a parameter generator function
is provided when registering the test case. A test user can either write their
own generator function or use one that is provided by KUnit. The generator
function is stored in  ``kunit_case->generate_params`` and can be set using the
macros described in the section below.”h]”(hX  A KUnit test is determined to be parameterized if a parameter generator function
is provided when registering the test case. A test user can either write their
own generator function or use one that is provided by KUnit. The generator
function is stored in  ”…””}”(hj–
  hžhhŸNh Nubhå)”}”(hŒ``kunit_case->generate_params``”h]”hŒkunit_case->generate_params”…””}”(hjž
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj–
  ubhŒ@ and can be set using the
macros described in the section below.”…””}”(hj–
  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M%hjw
  hžhubhÛ)”}”(hX7  To establish the terminology, a "parameterized test" is a test which is run
multiple times (once per "parameter" or "parameter run"). Each parameter run has
both its own independent ``struct kunit`` (the "parameter run context") and
access to a shared parent ``struct kunit`` (the "parameterized test context").”h]”(hŒÂTo establish the terminology, a â€œparameterized testâ€ is a test which is run
multiple times (once per â€œparameterâ€ or â€œparameter runâ€). Each parameter run has
both its own independent ”…””}”(hj¶
  hžhhŸNh Nubhå)”}”(hŒ``struct kunit``”h]”hŒstruct kunit”…””}”(hj¾
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj¶
  ubhŒA (the â€œparameter run contextâ€) and
access to a shared parent ”…””}”(hj¶
  hžhhŸNh Nubhå)”}”(hŒ``struct kunit``”h]”hŒstruct kunit”…””}”(hjÐ
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj¶
  ubhŒ( (the â€œparameterized test contextâ€).”…””}”(hj¶
  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M+hjw
  hžhubhµ)”}”(hhh]”(hº)”}”(hŒPassing Parameters to a Test”h]”hŒPassing Parameters to a Test”…””}”(hjë
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjè
  hžhhŸh³h M1ubhÛ)”}”(hŒ9There are three ways to provide the parameters to a test:”h]”hŒ9There are three ways to provide the parameters to a test:”…””}”(hjù
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M2hjè
  hžhubhÛ)”}”(hŒArray Parameter Macros:”h]”hŒArray Parameter Macros:”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M4hjè
  hžhubhŒblock_quote”“”)”}”(hŒøKUnit provides special support for the common table-driven testing pattern.
By applying either ``KUNIT_ARRAY_PARAM`` or ``KUNIT_ARRAY_PARAM_DESC`` to the
``cases`` array from the previous section, we can create a parameterized test
as shown below:
”h]”hÛ)”}”(hŒ÷KUnit provides special support for the common table-driven testing pattern.
By applying either ``KUNIT_ARRAY_PARAM`` or ``KUNIT_ARRAY_PARAM_DESC`` to the
``cases`` array from the previous section, we can create a parameterized test
as shown below:”h]”(hŒ_KUnit provides special support for the common table-driven testing pattern.
By applying either ”…””}”(hj  hžhhŸNh Nubhå)”}”(hŒ``KUNIT_ARRAY_PARAM``”h]”hŒKUNIT_ARRAY_PARAM”…””}”(hj#  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj  ubhŒ or ”…””}”(hj  hžhhŸNh Nubhå)”}”(hŒ``KUNIT_ARRAY_PARAM_DESC``”h]”hŒKUNIT_ARRAY_PARAM_DESC”…””}”(hj5  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj  ubhŒ to the
”…””}”(hj  hžhhŸNh Nubhå)”}”(hŒ	``cases``”h]”hŒcases”…””}”(hjG  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj  ubhŒT array from the previous section, we can create a parameterized test
as shown below:”…””}”(hj  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M6hj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h M6hjè
  hžhubj  )”}”(hX7  // This is copy-pasted from above.
struct sha1_test_case {
        const char *str;
        const char *sha1;
};
static const struct sha1_test_case cases[] = {
        {
                .str = "hello world",
                .sha1 = "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed",
        },
        {
                .str = "hello world!",
                .sha1 = "430ce34d020724ed75a196dfc2ad67c77772d169",
        },
};

// Creates `sha1_gen_params()` to iterate over `cases` while using
// the struct member `str` for the case description.
KUNIT_ARRAY_PARAM_DESC(sha1, cases, str);

// Looks no different from a normal test.
static void sha1_test(struct kunit *test)
{
        // This function can just contain the body of the for-loop.
        // The former `cases[i]` is accessible under test->param_value.
        char out[40];
        struct sha1_test_case *test_param = (struct sha1_test_case *)(test->param_value);

        sha1sum(test_param->str, out);
        KUNIT_EXPECT_STREQ_MSG(test, out, test_param->sha1,
                              "sha1sum(%s)", test_param->str);
}

// Instead of KUNIT_CASE, we use KUNIT_CASE_PARAM and pass in the
// function declared by KUNIT_ARRAY_PARAM or KUNIT_ARRAY_PARAM_DESC.
static struct kunit_case sha1_test_cases[] = {
        KUNIT_CASE_PARAM(sha1_test, sha1_gen_params),
        {}
};”h]”hX7  // This is copy-pasted from above.
struct sha1_test_case {
        const char *str;
        const char *sha1;
};
static const struct sha1_test_case cases[] = {
        {
                .str = "hello world",
                .sha1 = "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed",
        },
        {
                .str = "hello world!",
                .sha1 = "430ce34d020724ed75a196dfc2ad67c77772d169",
        },
};

// Creates `sha1_gen_params()` to iterate over `cases` while using
// the struct member `str` for the case description.
KUNIT_ARRAY_PARAM_DESC(sha1, cases, str);

// Looks no different from a normal test.
static void sha1_test(struct kunit *test)
{
        // This function can just contain the body of the for-loop.
        // The former `cases[i]` is accessible under test->param_value.
        char out[40];
        struct sha1_test_case *test_param = (struct sha1_test_case *)(test->param_value);

        sha1sum(test_param->str, out);
        KUNIT_EXPECT_STREQ_MSG(test, out, test_param->sha1,
                              "sha1sum(%s)", test_param->str);
}

// Instead of KUNIT_CASE, we use KUNIT_CASE_PARAM and pass in the
// function declared by KUNIT_ARRAY_PARAM or KUNIT_ARRAY_PARAM_DESC.
static struct kunit_case sha1_test_cases[] = {
        KUNIT_CASE_PARAM(sha1_test, sha1_gen_params),
        {}
};”…””}”hje  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²j"  ‰j#  j$  j%  }”uh1j  hŸh³h M;hjè
  hžhubhÛ)”}”(hŒ$Custom Parameter Generator Function:”h]”hŒ$Custom Parameter Generator Function:”…””}”(hjt  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mehjè
  hžhubj  )”}”(hX  The generator function is responsible for generating parameters one-by-one
and has the following signature:
``const void* (*)(struct kunit *test, const void *prev, char *desc)``.
You can pass the generator function to the ``KUNIT_CASE_PARAM``
or ``KUNIT_CASE_PARAM_WITH_INIT`` macros.

The function receives the previously generated parameter as the ``prev`` argument
(which is ``NULL`` on the first call) and can also access the parameterized
test context passed as the ``test`` argument. KUnit calls this function
repeatedly until it returns ``NULL``, which signifies that a parameterized
test ended.

Below is an example of how it works:
”•S      h]”(hÛ)”}”(hX  The generator function is responsible for generating parameters one-by-one
and has the following signature:
``const void* (*)(struct kunit *test, const void *prev, char *desc)``.
You can pass the generator function to the ``KUNIT_CASE_PARAM``
or ``KUNIT_CASE_PARAM_WITH_INIT`` macros.”h]”(hŒlThe generator function is responsible for generating parameters one-by-one
and has the following signature:
”…””}”(hj†  hžhhŸNh Nubhå)”}”(hŒE``const void* (*)(struct kunit *test, const void *prev, char *desc)``”h]”hŒAconst void* (*)(struct kunit *test, const void *prev, char *desc)”…””}”(hjŽ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj†  ubhŒ-.
You can pass the generator function to the ”…””}”(hj†  hžhhŸNh Nubhå)”}”(hŒ``KUNIT_CASE_PARAM``”h]”hŒKUNIT_CASE_PARAM”…””}”(hj   hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj†  ubhŒ
or ”…””}”(hj†  hžhhŸNh Nubhå)”}”(hŒ``KUNIT_CASE_PARAM_WITH_INIT``”h]”hŒKUNIT_CASE_PARAM_WITH_INIT”…””}”(hj²  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj†  ubhŒ macros.”…””}”(hj†  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mghj‚  ubhÛ)”}”(hX<  The function receives the previously generated parameter as the ``prev`` argument
(which is ``NULL`` on the first call) and can also access the parameterized
test context passed as the ``test`` argument. KUnit calls this function
repeatedly until it returns ``NULL``, which signifies that a parameterized
test ended.”h]”(hŒ@The function receives the previously generated parameter as the ”…””}”(hjÊ  hžhhŸNh Nubhå)”}”(hŒ``prev``”h]”hŒprev”…””}”(hjÒ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjÊ  ubhŒ argument
(which is ”…””}”(hjÊ  hžhhŸNh Nubhå)”}”(hŒ``NULL``”h]”hŒNULL”…””}”(hjä  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjÊ  ubhŒU on the first call) and can also access the parameterized
test context passed as the ”…””}”(hjÊ  hžhhŸNh Nubhå)”}”(hŒ``test``”h]”hŒtest”…””}”(hjö  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjÊ  ubhŒA argument. KUnit calls this function
repeatedly until it returns ”…””}”(hjÊ  hžhhŸNh Nubhå)”}”(hŒ``NULL``”h]”hŒNULL”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjÊ  ubhŒ2, which signifies that a parameterized
test ended.”…””}”(hjÊ  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mmhj‚  ubhÛ)”}”(hŒ$Below is an example of how it works:”h]”hŒ$Below is an example of how it works:”…””}”(hj   hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mshj‚  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h Mghjè
  hžhubj  )”}”(hX9  #define MAX_TEST_BUFFER_SIZE 8

// Example generator function. It produces a sequence of buffer sizes that
// are powers of two, starting at 1 (e.g., 1, 2, 4, 8).
static const void *buffer_size_gen_params(struct kunit *test, const void *prev, char *desc)
{
        long prev_buffer_size = (long)prev;
        long next_buffer_size = 1; // Start with an initial size of 1.

        // Stop generating parameters if the limit is reached or exceeded.
        if (prev_buffer_size >= MAX_TEST_BUFFER_SIZE)
                return NULL;

        // For subsequent calls, calculate the next size by doubling the previous one.
        if (prev)
                next_buffer_size = prev_buffer_size << 1;

        return (void *)next_buffer_size;
}

// Simple test to validate that kunit_kzalloc provides zeroed memory.
static void buffer_zero_test(struct kunit *test)
{
        long buffer_size = (long)test->param_value;
        // Use kunit_kzalloc to allocate a zero-initialized buffer. This makes the
        // memory "parameter run managed," meaning it's automatically cleaned up at
        // the end of each parameter run.
        int *buf = kunit_kzalloc(test, buffer_size * sizeof(int), GFP_KERNEL);

        // Ensure the allocation was successful.
        KUNIT_ASSERT_NOT_NULL(test, buf);

        // Loop through the buffer and confirm every element is zero.
        for (int i = 0; i < buffer_size; i++)
                KUNIT_EXPECT_EQ(test, buf[i], 0);
}

static struct kunit_case buffer_test_cases[] = {
        KUNIT_CASE_PARAM(buffer_zero_test, buffer_size_gen_params),
        {}
};”h]”hX9  #define MAX_TEST_BUFFER_SIZE 8

// Example generator function. It produces a sequence of buffer sizes that
// are powers of two, starting at 1 (e.g., 1, 2, 4, 8).
static const void *buffer_size_gen_params(struct kunit *test, const void *prev, char *desc)
{
        long prev_buffer_size = (long)prev;
        long next_buffer_size = 1; // Start with an initial size of 1.

        // Stop generating parameters if the limit is reached or exceeded.
        if (prev_buffer_size >= MAX_TEST_BUFFER_SIZE)
                return NULL;

        // For subsequent calls, calculate the next size by doubling the previous one.
        if (prev)
                next_buffer_size = prev_buffer_size << 1;

        return (void *)next_buffer_size;
}

// Simple test to validate that kunit_kzalloc provides zeroed memory.
static void buffer_zero_test(struct kunit *test)
{
        long buffer_size = (long)test->param_value;
        // Use kunit_kzalloc to allocate a zero-initialized buffer. This makes the
        // memory "parameter run managed," meaning it's automatically cleaned up at
        // the end of each parameter run.
        int *buf = kunit_kzalloc(test, buffer_size * sizeof(int), GFP_KERNEL);

        // Ensure the allocation was successful.
        KUNIT_ASSERT_NOT_NULL(test, buf);

        // Loop through the buffer and confirm every element is zero.
        for (int i = 0; i < buffer_size; i++)
                KUNIT_EXPECT_EQ(test, buf[i], 0);
}

static struct kunit_case buffer_test_cases[] = {
        KUNIT_CASE_PARAM(buffer_zero_test, buffer_size_gen_params),
        {}
};”…””}”hj4  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²j"  ‰j#  j$  j%  }”uh1j  hŸh³h Muhjè
  hžhubhÛ)”}”(hŒ:Runtime Parameter Array Registration in the Init Function:”h]”hŒ:Runtime Parameter Array Registration in the Init Function:”…””}”(hjC  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M¡hjè
  hžhubj  )”}”(hXÆ  For scenarios where you might need to initialize a parameterized test, you
can directly register a parameter array to the parameterized test context.

To do this, you must pass the parameterized test context, the array itself,
the array size, and a ``get_description()`` function to the
``kunit_register_params_array()`` macro. This macro populates
``struct kunit_params`` within the parameterized test context, effectively
storing a parameter array object. The ``get_description()`` function will
be used for populating parameter descriptions and has the following signature:
``void (*)(struct kunit *test, const void *param, char *desc)``. Note that it
also has access to the parameterized test context.

   .. important::
      When using this way to register a parameter array, you will need to
      manually pass ``kunit_array_gen_params()`` as the generator function to
      ``KUNIT_CASE_PARAM_WITH_INIT``. ``kunit_array_gen_params()`` is a KUnit
      helper that will use the registered array to generate the parameters.

      If needed, instead of passing the KUnit helper, you can also pass your
      own custom generator function that utilizes the parameter array. To
      access the parameter array from within the parameter generator
      function use ``test->params_array.params``.

The ``kunit_register_params_array()`` macro should be called within a
``param_init()`` function that initializes the parameterized test and has
the following signature ``int (*)(struct kunit *test)``. For a detailed
explanation of this mechanism please refer to the "Adding Shared Resources"
section that is after this one. This method supports registering both
dynamically built and static parameter arrays.

The code snippet below shows the ``example_param_init_dynamic_arr`` test that
utilizes ``make_fibonacci_params()`` to create a dynamic array, which is then
registered using ``kunit_register_params_array()``. To see the full code
please refer to lib/kunit/kunit-example-test.c.
”h]”(hÛ)”}”(hŒ•For scenarios where you might need to initialize a parameterized test, you
can directly register a parameter array to the parameterized test context.”h]”hŒ•For scenarios where you might need to initialize a parameterized test, you
can directly register a parameter array to the parameterized test context.”…””}”(hjU  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M£hjQ  ubhÛ)”}”(hX*  To do this, you must pass the parameterized test context, the array itself,
the array size, and a ``get_description()`` function to the
``kunit_register_params_array()`` macro. This macro populates
``struct kunit_params`` within the parameterized test context, effectively
storing a parameter array object. The ``get_description()`` function will
be used for populating parameter descriptions and has the following signature:
``void (*)(struct kunit *test, const void *param, char *desc)``. Note that it
also has access to the parameterized test context.”h]”(hŒbTo do this, you must pass the parameterized test context, the array itself,
the array size, and a ”…””}”(hjc  hžhhŸNh Nubhå)”}”(hŒ``get_description()``”h]”hŒget_description()”…””}”(hjk  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjc  ubhŒ function to the
”…””}”(hjc  hžhhŸNh Nubhå)”}”(hŒ!``kunit_register_params_array()``”h]”hŒkunit_register_params_array()”…””}”(hj}  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjc  ubhŒ macro. This macro populates
”…””}”(hjc  hžhhŸNh Nubhå)”}”(hŒ``struct kunit_params``”h]”hŒstruct kunit_params”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjc  ubhŒZ within the parameterized test context, effectively
storing a parameter array object. The ”…””}”(hjc  hžhhŸNh Nubhå)”}”(hŒ``get_description()``”h]”hŒget_description()”…””}”(hj¡  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjc  ubhŒ^ function will
be used for populating parameter descriptions and has the following signature:
”…””}”(hjc  hžhhŸNh Nubhå)”}”(hŒ?``void (*)(struct kunit *test, const void *param, char *desc)``”h]”hŒ;void (*)(struct kunit *test, const void *param, char *desc)”…””}”(hj³  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjc  ubhŒA. Note that it
also has access to the parameterized test context.”…””}”(hjc  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M¦hjQ  ubj  )”}”(hX8  .. important::
   When using this way to register a parameter array, you will need to
   manually pass ``kunit_array_gen_params()`` as the generator function to
   ``KUNIT_CASE_PARAM_WITH_INIT``. ``kunit_array_gen_params()`` is a KUnit
   helper that will use the registered array to generate the parameters.

   If needed, instead of passing the KUnit helper, you can also pass your
   own custom generator function that utilizes the parameter array. To
   access the parameter array from within the parameter generator
   function use ``test->params_array.params``.
”h]”jN  )”}”(hX  When using this way to register a parameter array, you will need to
manually pass ``kunit_array_gen_params()`` as the generator function to
``KUNIT_CASE_PARAM_WITH_INIT``. ``kunit_array_gen_params()`` is a KUnit
helper that will use the registered array to generate the parameters.

If needed, instead of passing the KUnit helper, you can also pass your
own custom generator function that utilizes the parameter array. To
access the parameter array from within the parameter generator
function use ``test->params_array.params``.”h]”(hÛ)”}”(hX  When using this way to register a parameter array, you will need to
manually pass ``kunit_array_gen_params()`` as the generator function to
``KUNIT_CASE_PARAM_WITH_INIT``. ``kunit_array_gen_params()`` is a KUnit
helper that will use the registered array to generate the parameters.”h]”(hŒRWhen using this way to register a parameter array, you will need to
manually pass ”…””}”(hjÓ  hžhhŸNh Nubhå)”}”(hŒ``kunit_array_gen_params()``”h]”hŒkunit_array_gen_params()”…””}”(hjÛ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjÓ  ubhŒ as the generator function to
”…””}”(hjÓ  hžhhŸNh Nubhå)”}”(hŒ``KUNIT_CASE_PARAM_WITH_INIT``”h]”hŒKUNIT_CASE_PARAM_WITH_INIT”…””}”(hjí  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjÓ  ubhŒ. ”…””}”(hjÓ  hžhhŸNh Nubhå)”}”(hŒ``kunit_array_gen_params()``”h]”hŒkunit_array_gen_params()”…””}”(hjÿ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjÓ  ubhŒQ is a KUnit
helper that will use the registered array to generate the parameters.”…””}”(hjÓ  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M°hjÏ  ubhÛ)”}”(hŒõIf needed, instead of passing the KUnit helper, you can also pass your
own custom generator function that utilizes the parameter array. To
access the parameter array from within the parameter generator
function use ``test->params_array.params``.”h]”(hŒ×If needed, instead of passing the KUnit helper, you can also pass your
own custom generator function that utilizes the parameter array. To
access the parameter array from within the parameter generator
function use ”…””}”(hj  hžhhŸNh Nubhå)”}”(hŒ``test->params_array.params``”h]”hŒtest->params_array.params”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj  ubhŒ.”…””}”(hj  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MµhjÏ  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1jM  hjË  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h M¯hjQ  ubhÛ)”}”(hX˜  The ``kunit_register_params_array()`` macro should be called within a
``param_init()`` function that initializes the parameterized test and has
the following signature ``int (*)(struct kunit *test)``. For a detailed
explanation of this mechanism please refer to the "Adding Shared Resources"
section that is after this one. This method supports registering both
dynamically built and static parameter arrays.”h]”(hŒThe ”…””}”(hjC  hžhhŸNh Nubhå)”}”(hŒ!``kunit_register_params_array()``”h]”hŒkunit_register_params_array()”…””}”(hjK  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjC  ubhŒ! macro should be called within a
”…””}”(hjC  hžhhŸNh Nubhå)”}”(hŒ``param_init()``”h]”hŒparam_init()”…””}”(hj]  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjC  ubhŒR function that initializes the parameterized test and has
the following signature ”…””}”(hjC  hžhhŸNh Nubhå)”}”(hŒ``int (*)(struct kunit *test)``”h]”hŒint (*)(struct kunit *test)”…””}”(hjo  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjC  ubhŒÕ. For a detailed
explanation of this mechanism please refer to the â€œAdding Shared Resourcesâ€
section that is after this one. This method supports registering both
dynamically built and static parameter arrays.”…””}”(hjC  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MºhjQ  ubhÛ)”}”(hX  The code snippet below shows the ``example_param_init_dynamic_arr`` test that
utilizes ``make_fibonacci_params()`` to create a dynamic array, which is then
registered using ``kunit_register_params_array()``. To see the full code
please refer to lib/kunit/kunit-example-test.c.”h]”(hŒ!The code snippet below shows the ”…””}”(hj‡  hžhhŸNh Nubhå)”}”(hŒ"``example_param_init_dynamic_arr``”h]”hŒexample_param_init_dynamic_arr”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj‡  ubhŒ test that
utilizes ”…””}”(hj‡  hžhhŸNh Nubhå)”}”(hŒ``make_fibonacci_params()``”h]”hŒmake_fibonacci_params()”…””}”(hj¡  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj‡  ubhŒ; to create a dynamic array, which is then
registered using ”…””}”(hj‡  hžhhŸNh Nubhå)”}”(hŒ!``kunit_register_params_array()``”h]”hŒkunit_register_params_array()”…””}”(hj³  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj‡  ubhŒF. To see the full code
please refer to lib/kunit/kunit-example-test.c.”…””}”(hj‡  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MÁhjQ  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h M£hjè
  hžhubj  )”}”(hXˆ  /*
* Example of a parameterized test param_init() function that registers a dynamic
* array of parameters.
*/
static int example_param_init_dynamic_arr(struct kunit *test)
{
        size_t seq_size;
        int *fibonacci_params;

        kunit_info(test, "initializing parameterized test\n");

        seq_size = 6;
        fibonacci_params = make_fibonacci_params(test, seq_size);
        if (!fibonacci_params)
                return -ENOMEM;
        /*
        * Passes the dynamic parameter array information to the parameterized test
        * context struct kunit. The array and its metadata will be stored in
        * test->parent->params_array. The array itself will be located in
        * params_data.params.
        */
        kunit_register_params_array(test, fibonacci_params, seq_size,
                                example_param_dynamic_arr_get_desc);
        return 0;
}

static struct kunit_case example_test_cases[] = {
        /*
         * Note how we pass kunit_array_gen_params() to use the array we
         * registered in example_param_init_dynamic_arr() to generate
         * parameters.
         */
        KUNIT_CASE_PARAM_WITH_INIT(example_params_test_with_init_dynamic_arr,
                                   kunit_array_gen_params,
                                   example_param_init_dynamic_arr,
                                   example_param_exit_dynamic_arr),
        {}
};”h]”hXˆ  /*
* Example of a parameterized test param_init() function that registers a dynamic
* array of parameters.
*/
static int example_param_init_dynamic_arr(struct kunit *test)
{
        size_t seq_size;
        int *fibonacci_params;

        kunit_info(test, "initializing parameterized test\n");

        seq_size = 6;
        fibonacci_params = make_fibonacci_params(test, seq_size);
        if (!fibonacci_params)
                return -ENOMEM;
        /*
        * Passes the dynamic parameter array information to the parameterized test
        * context struct kunit. The array and its metadata will be stored in
        * test->parent->params_array. The array itself will be located in
        * params_data.params.
        */
        kunit_register_params_array(test, fibonacci_params, seq_size,
                                example_param_dynamic_arr_get_desc);
        return 0;
}

static struct kunit_case example_test_cases[] = {
        /*
         * Note how we pass kunit_array_gen_params() to use the array we
         * registered in example_param_init_dynamic_arr() to generate
         * parameters.
         */
        KUNIT_CASE_PARAM_WITH_INIT(example_params_test_with_init_dynamic_arr,
                                   kunit_array_gen_params,
                                   example_param_init_dynamic_arr,
                                   example_param_exit_dynamic_arr),
        {}
};”…””}”hjÑ  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²j"  ‰j#  j$  j%  }”uh1j  hŸh³h MÆhjè
  hžhubeh}”(h]”Œpassing-parameters-to-a-test”ah ]”h"]”Œpassing parameters to a test”ah$]”h&]”uh1h´hjw
  hžhhŸh³h M1ubhµ)”}”(hhh]”(hº)”}”(hŒAdding Shared Resources”h]”hŒAdding Shared Resources”…””}”(hjë  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjè  hžhhŸh³h MðubhÛ)”}”(hX  All parameter runs in this framework hold a reference to the parameterized test
context, which can be accessed using the parent ``struct kunit`` pointer. The
parameterized test context is not used to execute any test logic itself; instead,
it serves as a container for shared resources.”h]”(hŒ€All parameter runs in this framework hold a reference to the parameterized test
context, which can be accessed using the parent ”…””}”(hjù  hžhhŸNh Nubhå)”}”(hŒ``struct kunit``”h]”hŒstruct kunit”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjù  ubhŒŽ pointer. The
parameterized test context is not used to execute any test logic itself; instead,
it serves as a container for shared resources.”…””}”(hjù  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mñhjè  hžhubhÛ)”}”(hX"  It's possible to add resources to share between parameter runs within a
parameterized test by using ``KUNIT_CASE_PARAM_WITH_INIT``, to which you pass
custom ``param_init()`` and ``param_exit()`` functions. These functions run once
before and once after the parameterized test, respectively.”h]”(hŒfItâ€™s possible to add resources to share between parameter runs within a
parameterized test by using ”…””}”(hj  hžhhŸNh Nubhå)”}”(hŒ``KUNIT_CASE_PARAM_WITH_INIT``”h]”hŒKUNIT_CASE_PARAM_WITH_INIT”…””}”(hj!  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj  ubhŒ, to which you pass
custom ”…””}”(hj  hžhhŸNh Nubhå)”}”(hŒ``param_init()``”h]”hŒparam_init()”…””}”(hj3  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj  ubhŒ and ”…””}”(hj  hžhhŸNh Nubhå)”}”(hŒ``param_exit()``”h]”hŒparam_exit()”…””}”(hjE  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj  ubhŒ` functions. These functions run once
before and once after the parameterized test, respectively.”…””}”(hj  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Möhjè  hžhubhÛ)”}”(hX  The ``param_init()`` function, with the signature ``int (*)(struct kunit *test)``,
can be used for adding resources to the ``resources`` or ``priv`` fields of
the parameterized test context, registering the parameter array, and any other
initialization logic.”h]”(hŒThe ”…””}”(hj]  hžhhŸNh Nubhå)”}”(hŒ``param_init()``”h]”hŒparam_init()”…””}”(hje  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj]  ubhŒ function, with the signature ”…””}”(hj]  hžhhŸNh Nubhå)”}”(hŒ``int (*)(struct kunit *test)``”h]”hŒint (*)(struct kunit *test)”…””}”(hjw  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj]  ubhŒ*,
can be used for adding resources to the ”…””}”(hj]  hžhhŸNh Nubhå)”}”(hŒ``resources``”h]”hŒ	resources”…””}”(hj‰  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj]  ubhŒ or ”…””}”(hj]  hžhhŸNh Nubhå)”}”(hŒ``priv``”h]”hŒpriv”…””}”(hj›  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj]  ubhŒo fields of
the parameterized test context, registering the parameter array, and any other
initialization logic.”…””}”(hj]  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mûhjè  hžhubhÛ)”}”(hX  The ``param_exit()`` function, with the signature ``void (*)(struct kunit *test)``,
can be used to release any resources that were not parameterized test managed (i.e.
not automatically cleaned up after the parameterized test ends) and for any other
exit logic.”h]”(hŒThe ”…””}”(hj³  hžhhŸNh Nubhå)”}”(hŒ``param_exit()``”h]”hŒparam_exit()”…””}”(hj»  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj³  ubhŒ function, with the signature ”…””}”(hj³  hžhhŸNh Nubhå)”}”(hŒ ``void (*)(struct kunit *test)``”h]”hŒvoid (*)(struct kunit *test)”…””}”(hjÍ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj³  ubhŒ³,
can be used to release any resources that were not parameterized test managed (i.e.
not automatically cleaned up after the parameterized test ends) and for any other
exit logic.”…””}”(hj³  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M hjè  hžhubhÛ)”}”(hX  Both ``param_init()`` and ``param_exit()`` are passed the parameterized test
context behind the scenes. However, the test case function receives the parameter
run context. Therefore, to manage and access shared resources from within a test
case function, you must use ``test->parent``.”h]”(hŒBoth ”…””}”(hjå  hžhhŸNh Nubhå)”}”(hŒ``param_init()``”h]”hŒparam_init()”…””}”(hjí  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjå  ubhŒ and ”…””}”(hjå  hžhhŸNh Nubhå)”}”(hŒ``param_exit()``”h]”hŒparam_exit()”…””}”(hjÿ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjå  ubhŒâ are passed the parameterized test
context behind the scenes. However, the test case function receives the parameter
run context. Therefore, to manage and access shared resources from within a test
case function, you must use ”…””}”(hjå  hžhhŸNh Nubhå)”}”(hŒ``test->parent``”h]”hŒtest->parent”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjå  ubhŒ.”…””}”(hjå  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mhjè  hžhubhÛ)”}”(hXŠ  For instance, finding a shared resource allocated by the Resource API requires
passing ``test->parent`` to ``kunit_find_resource()``. This principle extends to
all other APIs that might be used in the test case function, including
``kunit_kzalloc()``, ``kunit_kmalloc_array()``, and others (see
Documentation/dev-tools/kunit/api/test.rst and the
Documentation/dev-tools/kunit/api/resource.rst).”h]”(hŒWFor instance, finding a shared resource allocated by the Resource API requires
passing ”…””}”(hj)  hžhhŸNh Nubhå)”}”(hŒ``test->parent``”h]”hŒtest->parent”…””}”(hj1  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj)  ubhŒ to ”…””}”(hj)  hžhhŸNh Nubhå)”}”(hŒ``kunit_find_resource()``”h]”hŒkunit_find_resource()”…””}”(hjC  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj)  ubhŒc. This principle extends to
all other APIs that might be used in the test case function, including
”…””}”(hj)  hžhhŸNh Nubhå)”}”(hŒ``kunit_kzalloc()``”h]”hŒkunit_kzalloc()”…””}”(hjU  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj)  ubhŒ, ”…””}”(hj)  hžhhŸNh Nubhå)”}”(hŒ``kunit_kmalloc_array()``”h]”hŒkunit_kmalloc_array()”…””}”(hjg  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj)  ubhŒu, and others (see
Documentation/dev-tools/kunit/api/test.rst and the
Documentation/dev-tools/kunit/api/resource.rst).”…””}”(hj)  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M
hjè  hžhubjT  )”}”(hŒËThe ``suite->init()`` function, which executes before each parameter run,
receives the parameter run context. Therefore, any resources set up in
``suite->init()`` are cleaned up after each parameter run.”h]”hÛ)”}”(hŒËThe ``suite->init()`` function, which executes before each parameter run,
receives the parameter run context. Therefore, any resources set up in
``suite->init()`` are cleaned up after each parameter run.”h]”(hŒThe ”…””}”(hjƒ  hžhhŸNh Nubhå)”}”(hŒ``suite->init()``”h]”hŒsuite->init()”…””}”(hj‹  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjƒ  ubhŒ| function, which executes before each parameter run,
receives the parameter run context. Therefore, any resources set up in
”…””}”(hjƒ  hžhhŸNh Nubhå)”}”(hŒ``suite->init()``”h]”hŒsuite->init()”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjƒ  ubhŒ) are cleaned up after each parameter run.”…””}”(hjƒ  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mhj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jS  hjè  hžhhŸh³h NubhÛ)”}”(hX  The code below shows how you can add the shared resources. Note that this code
utilizes the Resource API, which you can read more about here:
Documentation/dev-tools/kunit/api/resource.rst. To see the full version of this
code please refer to lib/kunit/kunit-example-test.c.”h]”hX  The code below shows how you can add the shared resources. Note that this code
utilizes the Resource API, which you can read more about here:
Documentation/dev-tools/kunit/api/resource.rst. To see the full version of this
code please refer to lib/kunit/kunit-example-test.c.”…””}”(hj»  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mhjè  hžhubj  )”}”(hXþ  static int example_resource_init(struct kunit_resource *res, void *context)
{
        ... /* Code that allocates memory and stores context in res->data. */
}

/* This function deallocates memory for the kunit_resource->data field. */
static void example_resource_free(struct kunit_resource *res)
{
        kfree(res->data);
}

/* This match function locates a test resource based on defined criteria. */
static bool example_resource_alloc_match(struct kunit *test, struct kunit_resource *res,
                                         void *match_data)
{
        return res->data && res->free == example_resource_free;
}

/* Function to initialize the parameterized test. */
static int example_param_init(struct kunit *test)
{
        int ctx = 3; /* Data to be stored. */
        void *data = kunit_alloc_resource(test, example_resource_init,
                                          example_resource_free,
                                          GFP_KERNEL, &ctx);
        if (!data)
                return -ENOMEM;
        kunit_register_params_array(test, example_params_array,
                                    ARRAY_SIZE(example_params_array));
        return 0;
}

/* Example test that uses shared resources in test->resources. */
static void example_params_test_with_init(struct kunit *test)
{
        int threshold;
        const struct example_param *param = test->param_value;
        /*  Here we pass test->parent to access the parameterized test context. */
        struct kunit_resource *res = kunit_find_resource(test->parent,
                                                         example_resource_alloc_match,
                                                         NULL);

        threshold = *((int *)res->data);
        KUNIT_ASSERT_LE(test, param->value, threshold);
        kunit_put_resource(res);
}

static struct kunit_case example_test_cases[] = {
        KUNIT_CASE_PARAM_WITH_INIT(example_params_test_with_init, kunit_array_gen_params,
                                   example_param_init, NULL),
        {}
};”h]”hXþ  static int example_resource_init(struct kunit_resource *res, void *context)
{
        ... /* Code that allocates memory and stores context in res->data. */
}

/* This function deallocates memory for the kunit_resource->data field. */
static void example_resource_free(struct kunit_resource *res)
{
        kfree(res->data);
}

/* This match function locates a test resource based on defined criteria. */
static bool example_resource_alloc_match(struct kunit *test, struct kunit_resource *res,
                                         void *match_data)
{
        return res->data && res->free == example_resource_free;
}

/* Function to initialize the parameterized test. */
static int example_param_init(struct kunit *test)
{
        int ctx = 3; /* Data to be stored. */
        void *data = kunit_alloc_resource(test, example_resource_init,
                                          example_resource_free,
                                          GFP_KERNEL, &ctx);
        if (!data)
                return -ENOMEM;
        kunit_register_params_array(test, example_params_array,
                                    ARRAY_SIZE(example_params_array));
        return 0;
}

/* Example test that uses shared resources in test->resources. */
static void example_params_test_with_init(struct kunit *test)
{
        int threshold;
        const struct example_param *param = test->param_value;
        /*  Here we pass test->parent to access the parameterized test context. */
        struct kunit_resource *res = kunit_find_resource(test->parent,
                                                         example_resource_alloc_match,
                                                         NULL);

        threshold = *((int *)res->data);
        KUNIT_ASSERT_LE(test, param->value, threshold);
        kunit_put_resource(res);
}

static struct kunit_case example_test_cases[] = {
        KUNIT_CASE_PARAM_WITH_INIT(example_params_test_with_init, kunit_array_gen_params,
                                   example_param_init, NULL),
        {}
};”…””}”hjÉ  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²j"  ‰j#  j$  j%  }”uh1j  hŸh³h Mhjè  hžhubhÛ)”}”(hŒûAs an alternative to using the KUnit Resource API for sharing resources, you can
place them in ``test->parent->priv``. This serves as a more lightweight method
for resource storage, best for scenarios where complex resource management is
not required.”h]”(hŒ_As an alternative to using the KUnit Resource API for sharing resources, you can
place them in ”…””}”(hjØ  hžhhŸNh Nubhå)”}”(hŒ``test->parent->priv``”h]”hŒtest->parent->priv”…””}”(hjà  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjØ  ubhŒ†. This serves as a more lightweight method
for resource storage, best for scenarios where complex resource management is
not required.”…””}”(hjØ  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MRhjè  hžhubhÛ)”}”(hX•  As stated previously ``param_init()`` and ``param_exit()`` get the parameterized
test context. So, you can directly use ``test->priv`` within ``param_init/exit``
to manage shared resources. However, from within the test case function, you must
navigate up to the parent ``struct kunit`` i.e. the parameterized test context.
Therefore, you need to use ``test->parent->priv`` to access those same
resources.”h]”(hŒAs stated previously ”…””}”(hjø  hžhhŸNh Nubhå)”}”(hŒ``param_init()``”h]”hŒparam_init()”…””}”(hj   hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjø  ubhŒ and ”…””}”(hjø  hžhhŸNh Nubhå)”}”(hŒ``param_exit()``”h]”hŒparam_exit()”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjø  ubhŒ> get the parameterized
test context. So, you can directly use ”…””}”(hjø  hžhhŸNh Nubhå)”}”(hŒ``test->priv``”h]”hŒ
test->priv”…””}”(hj$  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjø  ubhŒ within ”…””}”(hjø  hžhhŸNh Nubhå)”}”(hŒ``param_init/exit``”h]”hŒparam_init/exit”…””}”(hj6  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjø  ubhŒm
to manage shared resources. However, from within the test case function, you must
navigate up to the parent ”…””}”(hjø  hžhhŸNh Nubhå)”}”(hŒ``struct kunit``”h]”hŒstruct kunit”…””}”(hjH  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjø  ubhŒA i.e. the parameterized test context.
Therefore, you need to use ”…””}”(hjø  hžhhŸNh Nubhå)”}”(hŒ``test->parent->priv``”h]”hŒtest->parent->priv”…””}”(hjZ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjø  ubhŒ  to access those same
resources.”…””}”(hjø  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MWhjè  hžhubhÛ)”}”(hX´  The resources placed in ``test->parent->priv`` will need to be allocated in
memory to persist across the parameter runs. If memory is allocated using the
KUnit memory allocation APIs (described more in the "Allocating Memory" section
below), you won't need to worry about deallocation. The APIs will make the memory
parameterized test 'managed', ensuring that it will automatically get cleaned up
after the parameterized test concludes.”h]”(hŒThe resources placed in ”…””}”(hjr  hžhhŸNh Nubhå)”}”(hŒ``test->parent->priv``”h]”hŒtest->parent->priv”…””}”(hjz  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjr  ubhX   will need to be allocated in
memory to persist across the parameter runs. If memory is allocated using the
KUnit memory allocation APIs (described more in the â€œAllocating Memoryâ€ section
below), you wonâ€™t need to worry about deallocation. The APIs will make the memory
parameterized test â€˜managedâ€™, ensuring that it will automatically get cleaned up
after the parameterized test concludes.”…””}”(hjr  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M^hjè  hžhubhÛ)”}”(hŒUThe code below demonstrates example usage of the ``priv`` field for shared
resources:”h]”(hŒ1The code below demonstrates example usage of the ”…””}”(hj’  hžhhŸNh Nubhå)”}”(hŒ``priv``”h]”hŒpriv”…””}”(hjš  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj’  ubhŒ field for shared
resources:”…””}”(hj’  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mehjè  hžhubj  )”}”(hXv  static const struct example_param {
        int value;
} example_params_array[] = {
        { .value = 3, },
        { .value = 2, },
        { .value = 1, },
        { .value = 0, },
};

/* Initialize the parameterized test context. */
static int example_param_init_priv(struct kunit *test)
{
        int ctx = 3; /* Data to be stored. */
        int arr_size = ARRAY_SIZE(example_params_array);

        /*
         * Allocate memory using kunit_kzalloc(). Since the `param_init`
         * function receives the parameterized test context, this memory
         * allocation will be scoped to the lifetime of the parameterized test.
         */
        test->priv = kunit_kzalloc(test, sizeof(int), GFP_KERNEL);

        /* Assign the context value to test->priv.*/
        *((int *)test->priv) = ctx;

        /* Register the parameter array. */
        kunit_register_params_array(test, example_params_array, arr_size, NULL);
        return 0;
}

static void example_params_test_with_init_priv(struct kunit *test)
{
        int threshold;
        const struct example_param *param = test->param_value;

        /* By design, test->parent will not be NULL. */
        KUNIT_ASSERT_NOT_NULL(test, test->parent);

        /* Here we use test->parent->priv to access the shared resource. */
        threshold = *(int *)test->parent->priv;

        KUNIT_ASSERT_LE(test, param->value, threshold);
}

static struct kunit_case example_tests[] = {
        KUNIT_CASE_PARAM_WITH_INIT(example_params_test_with_init_priv,
                                   kunit_array_gen_params,
                                   example_param_init_priv, NULL),
        {}
};”h]”hXv  static const struct example_param {
        int value;
} example_params_array[] = {
        { .value = 3, },
        { .value = 2, },
        { .value = 1, },
        { .value = 0, },
};

/* Initialize the parameterized test context. */
static int example_param_init_priv(struct kunit *test)
{
        int ctx = 3; /* Data to be stored. */
        int arr_size = ARRAY_SIZE(example_params_array);

        /*
         * Allocate memory using kunit_kzalloc(). Since the `param_init`
         * function receives the parameterized test context, this memory
         * allocation will be scoped to the lifetime of the parameterized test.
         */
        test->priv = kunit_kzalloc(test, sizeof(int), GFP_KERNEL);

        /* Assign the context value to test->priv.*/
        *((int *)test->priv) = ctx;

        /* Register the parameter array. */
        kunit_register_params_array(test, example_params_array, arr_size, NULL);
        return 0;
}

static void example_params_test_with_init_priv(struct kunit *test)
{
        int threshold;
        const struct example_param *param = test->param_value;

        /* By design, test->parent will not be NULL. */
        KUNIT_ASSERT_NOT_NULL(test, test->parent);

        /* Here we use test->parent->priv to access the shared resource. */
        threshold = *(int *)test->parent->priv;

        KUNIT_ASSERT_LE(test, param->value, threshold);
}

static struct kunit_case example_tests[] = {
        KUNIT_CASE_PARAM_WITH_INIT(example_params_test_with_init_priv,
                                   kunit_array_gen_params,
                                   example_param_init_priv, NULL),
        {}
};”…””}”hj²  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²j"  ‰j#  j$  j%  }”uh1j  hŸh³h Mhhjè  hžhubeh}”(h]”Œadding-shared-resources”ah ]”h"]”Œadding shared resources”ah$]”h&]”uh1h´hjw
  hžhhŸh³h Mðubeh}”(h]”Œparameterized-testing”ah ]”h"]”Œparameterized testing”ah$]”h&]”uh1h´hj¹  hžhhŸh³h Mubeh}”(h]”Œtesting-against-multiple-inputs”ah ]”h"]”Œtesting against multiple inputs”ah$]”h&]”uh1h´hjŠ  hžhhŸh³h MÚubhµ)”}”(hhh]”(hº)”}”(hŒAllocating Memory”h]”hŒAllocating Memory”…””}”(hjÜ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjÙ  hžhhŸh³h MžubhÛ)”}”(hŒ’Where you might use ``kzalloc``, you can instead use ``kunit_kzalloc`` as KUnit
will then ensure that the memory is freed once the test completes.”h]”(hŒWhere you might use ”…””}”(hjê  hžhhŸNh Nubhå)”}”(hŒ``kzalloc``”h]”hŒkzalloc”…””}”(hjò  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjê  ubhŒ, you can instead use ”…””}”(hjê  hžhhŸNh Nubhå)”}”(hŒ``kunit_kzalloc``”h]”hŒkunit_kzalloc”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjê  ubhŒL as KUnit
will then ensure that the memory is freed once the test completes.”…””}”(hjê  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M hjÙ  hžhubhÛ)”}”(hŒ¨This is useful because it lets us use the ``KUNIT_ASSERT_EQ`` macros to exit
early from a test without having to worry about remembering to call ``kfree``.
For example:”h]”(hŒ*This is useful because it lets us use the ”…””}”(hj  hžhhŸNh Nubhå)”}”(hŒ``KUNIT_ASSERT_EQ``”h]”hŒKUNIT_ASSERT_EQ”…””}”(hj$  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj  ubhŒT macros to exit
early from a test without having to worry about remembering to call ”…””}”(hj  hžhhŸNh Nubhå)”}”(hŒ	``kfree``”h]”hŒkfree”…””}”(hj6  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj  ubhŒ.
For example:”…””}”(hj  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M£hjÙ  hžhubj  )”}”(hŒþvoid example_test_allocation(struct kunit *test)
{
        char *buffer = kunit_kzalloc(test, 16, GFP_KERNEL);
        /* Ensure allocation succeeded. */
        KUNIT_ASSERT_NOT_ERR_OR_NULL(test, buffer);

        KUNIT_ASSERT_STREQ(test, buffer, "");
}”h]”hŒþvoid example_test_allocation(struct kunit *test)
{
        char *buffer = kunit_kzalloc(test, 16, GFP_KERNEL);
        /* Ensure allocation succeeded. */
        KUNIT_ASSERT_NOT_ERR_OR_NULL(test, buffer);

        KUNIT_ASSERT_STREQ(test, buffer, "");
}”…””}”hjN  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²j"  ‰j#  j$  j%  }”uh1j  hŸh³h M§hjÙ  hžhubeh}”(h]”Œallocating-memory”ah ]”h"]”Œallocating memory”ah$]”h&]”uh1h´hjŠ  hžhhŸh³h Mžubhµ)”}”(hhh]”(hº)”}”(hŒRegistering Cleanup Actions”h]”hŒRegistering Cleanup Actions”…””}”(hjh  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hje  hžhhŸh³h M³ubhÛ)”}”(hŒÚIf you need to perform some cleanup beyond simple use of ``kunit_kzalloc``,
you can register a custom "deferred action", which is a cleanup function
run when the test exits (whether cleanly, or via a failed assertion).”h]”(hŒ9If you need to perform some cleanup beyond simple use of ”…””}”(hjv  hžhhŸNh Nubhå)”}”(hŒ``kunit_kzalloc``”h]”hŒkunit_kzalloc”…””}”(hj~  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjv  ubhŒ”,
you can register a custom â€œdeferred actionâ€, which is a cleanup function
run when the test exits (whether cleanly, or via a failed assertion).”…””}”(hjv  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mµhje  hžhubhÛ)”}”(hX  Actions are simple functions with no return value, and a single ``void*``
context argument, and fulfill the same role as "cleanup" functions in Python
and Go tests, "defer" statements in languages which support them, and
(in some cases) destructors in RAII languages.”h]”(hŒ@Actions are simple functions with no return value, and a single ”…””}”(hj–  hžhhŸNh Nubhå)”}”(hŒ	``void*``”h]”hŒvoid*”…””}”(hjž  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj–  ubhŒÊ
context argument, and fulfill the same role as â€œcleanupâ€ functions in Python
and Go tests, â€œdeferâ€ statements in languages which support them, and
(in some cases) destructors in RAII languages.”…””}”(hj–  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M¹hje  hžhubhÛ)”}”(hŒyThese are very useful for unregistering things from global lists, closing
files or other resources, or freeing resources.”h]”hŒyThese are very useful for unregistering things from global lists, closing
files or other resources, or freeing resources.”…””}”(hj¶  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M¾hje  hžhubhÛ)”}”(hŒFor example:”h]”hŒFor example:”…””}”(hjÄ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MÁhje  hžhubj  )”}”(hX%  static void cleanup_device(void *ctx)
{
        struct device *dev = (struct device *)ctx;

        device_unregister(dev);
}

void example_device_test(struct kunit *test)
{
        struct my_device dev;

        device_register(&dev);

        kunit_add_action(test, &cleanup_device, &dev);
}”h]”hX%  static void cleanup_device(void *ctx)
{
        struct device *dev = (struct device *)ctx;

        device_unregister(dev);
}

void example_device_test(struct kunit *test)
{
        struct my_device dev;

        device_register(&dev);

        kunit_add_action(test, &cleanup_device, &dev);
}”…””}”hjÒ  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²j"  ‰j#  ŒC”j%  }”uh1j  hŸh³h MÃhje  hžhubhÛ)”}”(hŒÓNote that, for functions like device_unregister which only accept a single
pointer-sized argument, it's possible to automatically generate a wrapper
with the ``KUNIT_DEFINE_ACTION_WRAPPER()`` macro, for example:”h]”(hŒ Note that, for functions like device_unregister which only accept a single
pointer-sized argument, itâ€™s possible to automatically generate a wrapper
with the ”…””}”(hjâ  hžhhŸNh Nubhå)”}”(hŒ!``KUNIT_DEFINE_ACTION_WRAPPER()``”h]”hŒKUNIT_DEFINE_ACTION_WRAPPER()”…””}”(hjê  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjâ  ubhŒ macro, for example:”…””}”(hjâ  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MÕhje  hžhubj  )”}”(hŒ•KUNIT_DEFINE_ACTION_WRAPPER(device_unregister, device_unregister_wrapper, struct device *);
kunit_add_action(test, &device_unregister_wrapper, &dev);”h]”hŒ•KUNIT_DEFINE_ACTION_WRAPPER(device_unregister, device_unregister_wrapper, struct device *);
kunit_add_action(test, &device_unregister_wrapper, &dev);”…””}”hj  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²j"  ‰j#  jà  j%  }”uh1j  hŸh³h MÙhje  hžhubhÛ)”}”(hŒšYou should do this in preference to manually casting to the ``kunit_action_t`` type,
as casting function pointers will break Control Flow Integrity (CFI).”h]”(hŒ<You should do this in preference to manually casting to the ”…””}”(hj  hžhhŸNh Nubhå)”}”(hŒ``kunit_action_t``”h]”hŒkunit_action_t”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj  ubhŒL type,
as casting function pointers will break Control Flow Integrity (CFI).”…””}”(hj  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MÞhje  hžhubhÛ)”}”(hŒ¹``kunit_add_action`` can fail if, for example, the system is out of memory.
You can use ``kunit_add_action_or_reset`` instead which runs the action
immediately if it cannot be deferred.”h]”(hå)”}”(hŒ``kunit_add_action``”h]”hŒkunit_add_action”…””}”(hj5  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj1  ubhŒD can fail if, for example, the system is out of memory.
You can use ”…””}”(hj1  hžhhŸNh Nubhå)”}”(hŒ``kunit_add_action_or_reset``”h]”hŒkunit_add_action_or_reset”…””}”(hjG  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj1  ubhŒD instead which runs the action
immediately if it cannot be deferred.”…””}”(hj1  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Máhje  hžhubhÛ)”}”(hŒ¯If you need more control over when the cleanup function is called, you
can trigger it early using ``kunit_release_action``, or cancel it entirely
with ``kunit_remove_action``.”h]”(hŒbIf you need more control over when the cleanup function is called, you
can trigger it early using ”…””}”(hj_  hžhhŸNh Nubhå)”}”(hŒ``kunit_release_action``”h]”hŒkunit_release_action”…””}”(hjg  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj_  ubhŒ, or cancel it entirely
with ”…””}”(hj_  hžhhŸNh Nubhå)”}”(hŒ``kunit_remove_action``”h]”hŒkunit_remove_action”…””}”(hjy  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj_  ubhŒ.”…””}”(hj_  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Måhje  hžhubeh}”(h]”Œregistering-cleanup-actions”ah ]”h"]”Œregistering cleanup actions”ah$]”h&]”uh1h´hjŠ  hžhhŸh³h M³ubhµ)”}”(hhh]”(hº)”}”(hŒTesting Static Functions”h]”hŒTesting Static Functions”…””}”(hjœ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj™  hžhhŸh³h MëubhÛ)”}”(hX  If you want to test static functions without exposing those functions outside of
testing, one option is conditionally export the symbol. When KUnit is enabled,
the symbol is exposed but remains static otherwise. To use this method, follow
the template below.”h]”hX  If you want to test static functions without exposing those functions outside of
testing, one option is conditionally export the symbol. When KUnit is enabled,
the symbol is exposed but remains static otherwise. To use this method, follow
the template below.”…””}”(hjª  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Míhj™  hžhubj  )”}”(hX	  /* In the file containing functions to test "my_file.c" */

#include <kunit/visibility.h>
#include <my_file.h>
...
VISIBLE_IF_KUNIT int do_interesting_thing()
{
...
}
EXPORT_SYMBOL_IF_KUNIT(do_interesting_thing);

/* In the header file "my_file.h" */

#if IS_ENABLED(CONFIG_KUNIT)
        int do_interesting_thing(void);
#endif

/* In the KUnit test file "my_file_test.c" */

#include <kunit/visibility.h>
#include <my_file.h>
...
MODULE_IMPORT_NS("EXPORTED_FOR_KUNIT_TESTING");
...
// Use do_interesting_thing() in tests”h]”hX	  /* In the file containing functions to test "my_file.c" */

#include <kunit/visibility.h>
#include <my_file.h>
...
VISIBLE_IF_KUNIT int do_interesting_thing()
{
...
}
EXPORT_SYMBOL_IF_KUNIT(do_interesting_thing);

/* In the header file "my_file.h" */

#if IS_ENABLED(CONFIG_KUNIT)
        int do_interesting_thing(void);
#endif

/* In the KUnit test file "my_file_test.c" */

#include <kunit/visibility.h>
#include <my_file.h>
...
MODULE_IMPORT_NS("EXPORTED_FOR_KUNIT_TESTING");
...
// Use do_interesting_thing() in tests”…””}”hj¸  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²j"  ‰j#  j$  j%  }”uh1j  hŸh³h Mòhj™  hžhubhÛ)”}”(hŒÓFor a full example, see this `patch <https://lore.kernel.org/all/20221207014024.340230-3-rmoar@google.com/>`_
where a test is modified to conditionally expose static functions for testing
using the macros above.”h]”(hŒFor a full example, see this ”…””}”(hjÇ  hžhhŸNh NubhŒ	reference”“”)”}”(hŒP`patch <https://lore.kernel.org/all/20221207014024.340230-3-rmoar@google.com/>`_”h]”hŒpatch”…””}”(hjÑ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œname”Œpatch”Œrefuri”ŒEhttps://lore.kernel.org/all/20221207014024.340230-3-rmoar@google.com/”uh1jÏ  hjÇ  ubjã  )”}”(hŒH <https://lore.kernel.org/all/20221207014024.340230-3-rmoar@google.com/>”h]”h}”(h]”Œpatch”ah ]”h"]”Œpatch”ah$]”h&]”Œrefuri”jâ  uh1jâ  Œ
referenced”KhjÇ  ubhŒf
where a test is modified to conditionally expose static functions for testing
using the macros above.”…””}”(hjÇ  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mhj™  hžhubhÛ)”}”(hŒ³As an **alternative** to the method above, you could conditionally ``#include``
the test file at the end of your .c file. This is not recommended but works
if needed. For example:”h]”(hŒAs an ”…””}”(hjû  hžhhŸNh NubhŒstrong”“”)”}”(hŒ**alternative**”h]”hŒalternative”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hjû  ubhŒ. to the method above, you could conditionally ”…””}”(hjû  hžhhŸNh Nubhå)”}”(hŒ``#include``”h]”hŒ#include”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjû  ubhŒd
the test file at the end of your .c file. This is not recommended but works
if needed. For example:”…””}”(hjû  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mhj™  hžhubj  )”}”(hŒw/* In "my_file.c" */

static int do_interesting_thing();

#ifdef CONFIG_MY_KUNIT_TEST
#include "my_kunit_test.c"
#endif”h]”hŒw/* In "my_file.c" */

static int do_interesting_thing();

#ifdef CONFIG_MY_KUNIT_TEST
#include "my_kunit_test.c"
#endif”…””}”hj/  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²j"  ‰j#  j$  j%  }”uh1j  hŸh³h Mhj™  hžhubeh}”(h]”Œtesting-static-functions”ah ]”h"]”Œtesting static functions”ah$]”h&]”uh1h´hjŠ  hžhhŸh³h Mëubhµ)”}”(hhh]”(hº)”}”(hŒInjecting Test-Only Code”h]”hŒInjecting Test-Only Code”…””}”(hjI  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjF  hžhhŸh³h M!ubhÛ)”}”(hŒGSimilar to as shown above, we can add test-specific logic. For example:”h]”hŒGSimilar to as shown above, we can add test-specific logic. For example:”…””}”(hjW  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M#hjF  hžhubj  )”}”(hŒ–/* In my_file.h */

#ifdef CONFIG_MY_KUNIT_TEST
/* Defined in my_kunit_test.c */
void test_only_hook(void);
#else
void test_only_hook(void) { }
#endif”h]”hŒ–/* In my_file.h */

#ifdef CONFIG_MY_KUNIT_TEST
/* Defined in my_kunit_test.c */
void test_only_hook(void);
#else
void test_only_hook(void) { }
#endif”…””}”hje  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²j"  ‰j#  j$  j%  }”uh1j  hŸh³h M%hjF  hžhubhÛ)”}”(hŒ‹This test-only code can be made more useful by accessing the current ``kunit_test``
as shown in next section: *Accessing The Current Test*.”h]”(hŒEThis test-only code can be made more useful by accessing the current ”…””}”(hjt  hžhhŸNh Nubhå)”}”(hŒ``kunit_test``”h]”hŒ
kunit_test”…””}”(hj|  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjt  ubhŒ
as shown in next section: ”…””}”(hjt  hžhhŸNh Nubhù)”}”(hŒ*Accessing The Current Test*”h]”hŒAccessing The Current Test”…””}”(hjŽ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1høhjt  ubhŒ.”…””}”(hjt  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M0hjF  hžhubeh}”(h]”Œinjecting-test-only-code”ah ]”h"]”Œinjecting test-only code”ah$]”h&]”uh1h´hjŠ  hžhhŸh³h M!ubhµ)”}”(hhh]”(hº)”}”(hŒAccessing The Current Test”h]”hŒAccessing The Current Test”…””}”(hj±  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj®  hžhhŸh³h M4ubhÛ)”}”(hXs  In some cases, we need to call test-only code from outside the test file.  This
is helpful, for example, when providing a fake implementation of a function, or
to fail any current test from within an error handler.
We can do this via the ``kunit_test`` field in ``task_struct``, which we can
access using the ``kunit_get_current_test()`` function in ``kunit/test-bug.h``.”h]”(hŒîIn some cases, we need to call test-only code from outside the test file.  This
is helpful, for example, when providing a fake implementation of a function, or
to fail any current test from within an error handler.
We can do this via the ”…””}”(hj¿  hžhhŸNh Nubhå)”}”(hŒ``kunit_test``”h]”hŒ
kunit_test”…””}”(hjÇ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj¿  ubhŒ
 field in ”…””}”(hj¿  hžhhŸNh Nubhå)”}”(hŒ``task_struct``”h]”hŒtask_struct”…””}”(hjÙ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj¿  ubhŒ , which we can
access using the ”…””}”(hj¿  hžhhŸNh Nubhå)”}”(hŒ``kunit_get_current_test()``”h]”hŒkunit_get_current_test()”…””}”(hjë  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj¿  ubhŒ function in ”…””}”(hj¿  hžhhŸNh Nubhå)”}”(hŒ``kunit/test-bug.h``”h]”hŒkunit/test-bug.h”…””}”(hjý  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj¿  ubhŒ.”…””}”(hj¿  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M6hj®  hžhubhÛ)”}”(hX,  ``kunit_get_current_test()`` is safe to call even if KUnit is not enabled. If
KUnit is not enabled, or if no test is running in the current task, it will
return ``NULL``. This compiles down to either a no-op or a static key check,
so will have a negligible performance impact when no test is running.”h]”(hå)”}”(hŒ``kunit_get_current_test()``”h]”hŒkunit_get_current_test()”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj  ubhŒ… is safe to call even if KUnit is not enabled. If
KUnit is not enabled, or if no test is running in the current task, it will
return ”…””}”(hj  hžhhŸNh Nubhå)”}”(hŒ``NULL``”h]”hŒNULL”…””}”(hj+  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj  ubhŒƒ. This compiles down to either a no-op or a static key check,
so will have a negligible performance impact when no test is running.”…””}”(hj  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M<hj®  hžhubhÛ)”}”(hŒXThe example below uses this to implement a "mock" implementation of a function, ``foo``:”h]”(hŒTThe example below uses this to implement a â€œmockâ€ implementation of a function, ”…””}”(hjC  hžhhŸNh Nubhå)”}”(hŒ``foo``”h]”hŒfoo”…””}”(hjK  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjC  ubhŒ:”…””}”(hjC  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MAhj®  hžhubj  )”}”(hX  #include <kunit/test-bug.h> /* for kunit_get_current_test */

struct test_data {
        int foo_result;
        int want_foo_called_with;
};

static int fake_foo(int arg)
{
        struct kunit *test = kunit_get_current_test();
        struct test_data *test_data = test->priv;

        KUNIT_EXPECT_EQ(test, test_data->want_foo_called_with, arg);
        return test_data->foo_result;
}

static void example_simple_test(struct kunit *test)
{
        /* Assume priv (private, a member used to pass test data from
         * the init function) is allocated in the suite's .init */
        struct test_data *test_data = test->priv;

        test_data->foo_result = 42;
        test_data->want_foo_called_with = 1;

        /* In a real test, we'd probably pass a pointer to fake_foo somewhere
         * like an ops struct, etc. instead of calling it directly. */
        KUNIT_EXPECT_EQ(test, fake_foo(1), 42);
}”h]”hX  #include <kunit/test-bug.h> /* for kunit_get_current_test */

struct test_data {
        int foo_result;
        int want_foo_called_with;
};

static int fake_foo(int arg)
{
        struct kunit *test = kunit_get_current_test();
        struct test_data *test_data = test->priv;

        KUNIT_EXPECT_EQ(test, test_data->want_foo_called_with, arg);
        return test_data->foo_result;
}

static void example_simple_test(struct kunit *test)
{
        /* Assume priv (private, a member used to pass test data from
         * the init function) is allocated in the suite's .init */
        struct test_data *test_data = test->priv;

        test_data->foo_result = 42;
        test_data->want_foo_called_with = 1;

        /* In a real test, we'd probably pass a pointer to fake_foo somewhere
         * like an ops struct, etc. instead of calling it directly. */
        KUNIT_EXPECT_EQ(test, fake_foo(1), 42);
}”…””}”hjc  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²j"  ‰j#  j$  j%  }”uh1j  hŸh³h MChj®  hžhubhÛ)”}”(hX  In this example, we are using the ``priv`` member of ``struct kunit`` as a way
of passing data to the test from the init function. In general ``priv`` is
pointer that can be used for any user data. This is preferred over static
variables, as it avoids concurrency issues.”h]”(hŒ"In this example, we are using the ”…””}”(hjr  hžhhŸNh Nubhå)”}”(hŒ``priv``”h]”hŒpriv”…””}”(hjz  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjr  ubhŒ member of ”…””}”(hjr  hžhhŸNh Nubhå)”}”(hŒ``struct kunit``”h]”hŒstruct kunit”…””}”(hjŒ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjr  ubhŒI as a way
of passing data to the test from the init function. In general ”…””}”(hjr  hžhhŸNh Nubhå)”}”(hŒ``priv``”h]”hŒpriv”…””}”(hjž  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjr  ubhŒy is
pointer that can be used for any user data. This is preferred over static
variables, as it avoids concurrency issues.”…””}”(hjr  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mchj®  hžhubhÛ)”}”(hXé  Had we wanted something more flexible, we could have used a named ``kunit_resource``.
Each test can have multiple resources which have string names providing the same
flexibility as a ``priv`` member, but also, for example, allowing helper
functions to create resources without conflicting with each other. It is also
possible to define a clean up function for each resource, making it easy to
avoid resource leaks. For more information, see Documentation/dev-tools/kunit/api/resource.rst.”h]”(hŒBHad we wanted something more flexible, we could have used a named ”…””}”(hj¶  hžhhŸNh Nubhå)”}”(hŒ``kunit_resource``”h]”hŒkunit_resource”…””}”(hj¾  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj¶  ubhŒd.
Each test can have multiple resources which have string names providing the same
flexibility as a ”…””}”(hj¶  hžhhŸNh Nubhå)”}”(hŒ``priv``”h]”hŒpriv”…””}”(hjÐ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj¶  ubhX)   member, but also, for example, allowing helper
functions to create resources without conflicting with each other. It is also
possible to define a clean up function for each resource, making it easy to
avoid resource leaks. For more information, see Documentation/dev-tools/kunit/api/resource.rst.”…””}”(hj¶  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mhhj®  hžhubeh}”(h]”Œaccessing-the-current-test”ah ]”h"]”Œaccessing the current test”ah$]”h&]”uh1h´hjŠ  hžhhŸh³h M4ubhµ)”}”(hhh]”(hº)”}”(hŒFailing The Current Test”h]”hŒFailing The Current Test”…””}”(hjó  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjð  hžhhŸh³h MpubhÛ)”}”(hX!  If we want to fail the current test, we can use ``kunit_fail_current_test(fmt, args...)``
which is defined in ``<kunit/test-bug.h>`` and does not require pulling in ``<kunit/test.h>``.
For example, we have an option to enable some extra debug checks on some data
structures as shown below:”h]”(hŒ0If we want to fail the current test, we can use ”…””}”(hj  hžhhŸNh Nubhå)”}”(hŒ)``kunit_fail_current_test(fmt, args...)``”h]”hŒ%kunit_fail_current_test(fmt, args...)”…””}”(hj	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj  ubhŒ
which is defined in ”…””}”(hj  hžhhŸNh Nubhå)”}”(hŒ``<kunit/test-bug.h>``”h]”hŒ<kunit/test-bug.h>”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj  ubhŒ! and does not require pulling in ”…””}”(hj  hžhhŸNh Nubhå)”}”(hŒ``<kunit/test.h>``”h]”hŒ<kunit/test.h>”…””}”(hj-  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj  ubhŒj.
For example, we have an option to enable some extra debug checks on some data
structures as shown below:”…””}”(hj  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mrhjð  hžhubj  )”}”(hXU  #include <kunit/test-bug.h>

#ifdef CONFIG_EXTRA_DEBUG_CHECKS
static void validate_my_data(struct data *data)
{
        if (is_valid(data))
                return;

        kunit_fail_current_test("data %p is invalid", data);

        /* Normal, non-KUnit, error reporting code here. */
}
#else
static void my_debug_function(void) { }
#endif”h]”hXU  #include <kunit/test-bug.h>

#ifdef CONFIG_EXTRA_DEBUG_CHECKS
static void validate_my_data(struct data *data)
{
        if (is_valid(data))
                return;

        kunit_fail_current_test("data %p is invalid", data);

        /* Normal, non-KUnit, error reporting code here. */
}
#else
static void my_debug_function(void) { }
#endif”…””}”hjE  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²j"  ‰j#  j$  j%  }”uh1j  hŸh³h Mwhjð  hžhubhÛ)”}”(hX(  ``kunit_fail_current_test()`` is safe to call even if KUnit is not enabled. If
KUnit is not enabled, or if no test is running in the current task, it will do
nothing. This compiles down to either a no-op or a static key check, so will
have a negligible performance impact when no test is running.”h]”(hå)”}”(hŒ``kunit_fail_current_test()``”h]”hŒkunit_fail_current_test()”…””}”(hjX  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjT  ubhX   is safe to call even if KUnit is not enabled. If
KUnit is not enabled, or if no test is running in the current task, it will do
nothing. This compiles down to either a no-op or a static key check, so will
have a negligible performance impact when no test is running.”…””}”(hjT  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M‰hjð  hžhubeh}”(h]”Œfailing-the-current-test”ah ]”h"]”Œfailing the current test”ah$]”h&]”uh1h´hjŠ  hžhhŸh³h Mpubhµ)”}”(hhh]”(hº)”}”(hŒ!Managing Fake Devices and Drivers”h]”hŒ!Managing Fake Devices and Drivers”…””}”(hj{  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjx  hžhhŸh³h MubhÛ)”}”(hX  When testing drivers or code which interacts with drivers, many functions will
require a ``struct device`` or ``struct device_driver``. In many cases, setting
up a real device is not required to test any given function, so a fake device
can be used instead.”h]”(hŒYWhen testing drivers or code which interacts with drivers, many functions will
require a ”…””}”(hj‰  hžhhŸNh Nubhå)”}”(hŒ``struct device``”h]”hŒstruct device”…””}”(hj‘  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj‰  ubhŒ or ”…””}”(hj‰  hžhhŸNh Nubhå)”}”(hŒ``struct device_driver``”h]”hŒstruct device_driver”…””}”(hj£  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj‰  ubhŒ{. In many cases, setting
up a real device is not required to test any given function, so a fake device
can be used instead.”…””}”(hj‰  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M‘hjx  hžhubhÛ)”}”(hX%  KUnit provides helper functions to create and manage these fake devices, which
are internally of type ``struct kunit_device``, and are attached to a special
``kunit_bus``. These devices support managed device resources (devres), as
described in Documentation/driver-api/driver-model/devres.rst”h]”(hŒfKUnit provides helper functions to create and manage these fake devices, which
are internally of type ”…””}”(hj»  hžhhŸNh Nubhå)”}”(hŒ``struct kunit_device``”h]”hŒstruct kunit_device”…””}”(hjÃ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj»  ubhŒ , and are attached to a special
”…””}”(hj»  hžhhŸNh Nubhå)”}”(hŒ``kunit_bus``”h]”hŒ	kunit_bus”…””}”(hjÕ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj»  ubhŒ{. These devices support managed device resources (devres), as
described in Documentation/driver-api/driver-model/devres.rst”…””•3      }”(hj»  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M–hjx  hžhubhÛ)”}”(hX+  To create a KUnit-managed ``struct device_driver``, use ``kunit_driver_create()``,
which will create a driver with the given name, on the ``kunit_bus``. This driver
will automatically be destroyed when the corresponding test finishes, but can also
be manually destroyed with ``driver_unregister()``.”h]”(hŒTo create a KUnit-managed ”…””}”(hjí  hžhhŸNh Nubhå)”}”(hŒ``struct device_driver``”h]”hŒstruct device_driver”…””}”(hjõ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjí  ubhŒ, use ”…””}”(hjí  hžhhŸNh Nubhå)”}”(hŒ``kunit_driver_create()``”h]”hŒkunit_driver_create()”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjí  ubhŒ9,
which will create a driver with the given name, on the ”…””}”(hjí  hžhhŸNh Nubhå)”}”(hŒ``kunit_bus``”h]”hŒ	kunit_bus”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjí  ubhŒ|. This driver
will automatically be destroyed when the corresponding test finishes, but can also
be manually destroyed with ”…””}”(hjí  hžhhŸNh Nubhå)”}”(hŒ``driver_unregister()``”h]”hŒdriver_unregister()”…””}”(hj+  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjí  ubhŒ.”…””}”(hjí  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M›hjx  hžhubhÛ)”}”(hXÉ  To create a fake device, use the ``kunit_device_register()``, which will create
and register a device, using a new KUnit-managed driver created with ``kunit_driver_create()``.
To provide a specific, non-KUnit-managed driver, use ``kunit_device_register_with_driver()``
instead. Like with managed drivers, KUnit-managed fake devices are automatically
cleaned up when the test finishes, but can be manually cleaned up early with
``kunit_device_unregister()``.”h]”(hŒ!To create a fake device, use the ”…””}”(hjC  hžhhŸNh Nubhå)”}”(hŒ``kunit_device_register()``”h]”hŒkunit_device_register()”…””}”(hjK  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjC  ubhŒY, which will create
and register a device, using a new KUnit-managed driver created with ”…””}”(hjC  hžhhŸNh Nubhå)”}”(hŒ``kunit_driver_create()``”h]”hŒkunit_driver_create()”…””}”(hj]  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjC  ubhŒ7.
To provide a specific, non-KUnit-managed driver, use ”…””}”(hjC  hžhhŸNh Nubhå)”}”(hŒ'``kunit_device_register_with_driver()``”h]”hŒ#kunit_device_register_with_driver()”…””}”(hjo  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjC  ubhŒŸ
instead. Like with managed drivers, KUnit-managed fake devices are automatically
cleaned up when the test finishes, but can be manually cleaned up early with
”…””}”(hjC  hžhhŸNh Nubhå)”}”(hŒ``kunit_device_unregister()``”h]”hŒkunit_device_unregister()”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähjC  ubhŒ.”…””}”(hjC  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M hjx  hžhubhÛ)”}”(hŒ¹The KUnit devices should be used in preference to ``root_device_register()``, and
instead of ``platform_device_register()`` in cases where the device is not otherwise
a platform device.”h]”(hŒ2The KUnit devices should be used in preference to ”…””}”(hj™  hžhhŸNh Nubhå)”}”(hŒ``root_device_register()``”h]”hŒroot_device_register()”…””}”(hj¡  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj™  ubhŒ, and
instead of ”…””}”(hj™  hžhhŸNh Nubhå)”}”(hŒ``platform_device_register()``”h]”hŒplatform_device_register()”…””}”(hj³  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hähj™  ubhŒ> in cases where the device is not otherwise
a platform device.”…””}”(hj™  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M§hjx  hžhubhÛ)”}”(hŒFor example:”h]”hŒFor example:”…””}”(hjË  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M«hjx  hžhubj  )”}”(hXù  #include <kunit/device.h>

static void test_my_device(struct kunit *test)
{
        struct device *fake_device;
        const char *dev_managed_string;

        // Create a fake device.
        fake_device = kunit_device_register(test, "my_device");
        KUNIT_ASSERT_NOT_ERR_OR_NULL(test, fake_device)

        // Pass it to functions which need a device.
        dev_managed_string = devm_kstrdup(fake_device, "Hello, World!");

        // Everything is cleaned up automatically when the test ends.
}”h]”hXù  #include <kunit/device.h>

static void test_my_device(struct kunit *test)
{
        struct device *fake_device;
        const char *dev_managed_string;

        // Create a fake device.
        fake_device = kunit_device_register(test, "my_device");
        KUNIT_ASSERT_NOT_ERR_OR_NULL(test, fake_device)

        // Pass it to functions which need a device.
        dev_managed_string = devm_kstrdup(fake_device, "Hello, World!");

        // Everything is cleaned up automatically when the test ends.
}”…””}”hjÙ  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²j"  ‰j#  j$  j%  }”uh1j  hŸh³h M­hjx  hžhubeh}”(h]”Œ!managing-fake-devices-and-drivers”ah ]”h"]”Œ!managing fake devices and drivers”ah$]”h&]”uh1h´hjŠ  hžhhŸh³h Mubeh}”(h]”Œcommon-patterns”ah ]”h"]”Œcommon patterns”ah$]”h&]”uh1h´hhhžhhŸh³h Kõubeh}”(h]”h ]”h"]”h$]”h&]”Œsource”h³uh1hŒcurrent_source”NŒcurrent_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(h¹NŒ	generator”NŒ	datestamp”NŒsource_link”NŒ
source_url”NŒtoc_backlinks”Œentry”Œfootnote_backlinks”KŒsectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒstrip_classes”NŒreport_level”KŒ
halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ	traceback”ˆŒinput_encoding”Œ	utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”j  Œerror_encoding”Œutf-8”Œerror_encoding_error_handler”Œbackslashreplace”Œlanguage_code”Œen”Œrecord_dependencies”NŒconfig”NŒ	id_prefix”hŒauto_id_prefix”Œid”Œdump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”h³Œ_destination”NŒ_config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒfile_insertion_enabled”ˆŒraw_enabled”KŒline_length_limit”M'Œpep_references”NŒpep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒrfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ	tab_width”KŒtrim_footnote_reference_space”‰Œsyntax_highlight”Œlong”Œsmart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œdocinfo_xform”KŒsectsubtitle_xform”‰Œimage_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”Œrefids”}”jï  ]”jä  asŒnameids”}”(j‡  j„  jw  jt  j³  j°  jo  jl  jý  jú  jõ  jò  j{  jï  jz  jw  jõ  jò  j¶  j³  jï  jì  j®  j«  jÖ  jÓ  jÎ  jË  jå  jâ  jÆ  jÃ  jb  j_  j–  j“  jC  j@  jì  jé  j«  j¨  jí  jê  ju  jr  jí  jê  uŒ	nametypes”}”(j‡  ‰jw  ‰j³  ‰jo  ‰jý  ‰jõ  ‰j{  ˆjz  ‰jõ  ‰j¶  ‰jï  ‰j®  ‰jÖ  ‰jÎ  ‰jå  ‰jÆ  ‰jb  ‰j–  ‰jC  ‰jì  ˆj«  ‰jí  ‰ju  ‰jí  ‰uh}”(j„  h¶jt  hÉj°  jk  jl  j¶  jú  jz  jò  j  jï  j   jw  j   jò  jŠ  j³  j›  jì  jº  j«  jò  jÓ  j¹  jË  jw
  jâ  jè
  jÃ  jè  j_  jÙ  j“  je  j@  j™  jé  jã  j¨  jF  jê  j®  jr  jð  jê  jx  uŒfootnote_refs”}”Œcitation_refs”}”Œautofootnotes”]”Œautofootnote_refs”]”Œsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ	footnotes”]”Œ	citations”]”Œautofootnote_start”KŒsymbol_footnote_start”K Œ
id_counter”Œcollections”ŒCounter”“”}”…”R”Œparse_messages”]”Œtransform_messages”]”hŒsystem_message”“”)”}”(hhh]”hÛ)”}”(hhh]”hŒ6Hyperlink target "kunit-on-non-uml" is not referenced.”…””}”hj…  sbah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhj‚  ubah}”(h]”h ]”h"]”h$]”h&]”Œlevel”KŒtype”ŒINFO”Œsource”h³Œline”KØuh1j€  ubaŒtransformer”NŒinclude_log”]”Œ
decoration”Nhžhub.