sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget)/translations/zh_CN/dev-tools/kunit/stylemodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget)/translations/zh_TW/dev-tools/kunit/stylemodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget)/translations/it_IT/dev-tools/kunit/stylemodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget)/translations/ja_JP/dev-tools/kunit/stylemodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget)/translations/ko_KR/dev-tools/kunit/stylemodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget)/translations/sp_SP/dev-tools/kunit/stylemodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhcomment)}(h SPDX-License-Identifier: GPL-2.0h]h SPDX-License-Identifier: GPL-2.0}hhsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1hhhhhhC/var/lib/git/docbuild/linux/Documentation/dev-tools/kunit/style.rsthKubhsection)}(hhh](htitle)}(hTest Style and Nomenclatureh]hTest Style and Nomenclature}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh paragraph)}(hX_To make finding, writing, and using KUnit tests as simple as possible, it is strongly encouraged that they are named and written according to the guidelines below. While it is possible to write KUnit tests which do not follow these rules, they may break some tooling, may conflict with other tests, and may not be run automatically by testing systems.h]hX_To make finding, writing, and using KUnit tests as simple as possible, it is strongly encouraged that they are named and written according to the guidelines below. While it is possible to write KUnit tests which do not follow these rules, they may break some tooling, may conflict with other tests, and may not be run automatically by testing systems.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hCIt is recommended that you only deviate from these guidelines when:h]hCIt is recommended that you only deviate from these guidelines when:}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hhhhubhenumerated_list)}(hhh](h list_item)}(hEPorting tests to KUnit which are already known with an existing name.h]h)}(hhh]hEPorting tests to KUnit which are already known with an existing name.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhubah}(h]h ]h"]h$]h&]uh1hhhhhhhhNubh)}(hWriting tests which would cause serious problems if automatically run. For example, non-deterministically producing false positives or negatives, or taking a long time to run. h]h)}(hWriting tests which would cause serious problems if automatically run. For example, non-deterministically producing false positives or negatives, or taking a long time to run.h]hWriting tests which would cause serious problems if automatically run. For example, non-deterministically producing false positives or negatives, or taking a long time to run.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1hhhhhhhhNubeh}(h]h ]h"]h$]h&]enumtypearabicprefixhsuffix.uh1hhhhhhhhKubh)}(hhh](h)}(hSubsystems, Suites, and Testsh]hSubsystems, Suites, and Tests}(hj+hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj(hhhhhKubh)}(hTo make tests easy to find, they are grouped into suites and subsystems. A test suite is a group of tests which test a related area of the kernel. A subsystem is a set of test suites which test different parts of a kernel subsystem or a driver.h]hTo make tests easy to find, they are grouped into suites and subsystems. A test suite is a group of tests which test a related area of the kernel. A subsystem is a set of test suites which test different parts of a kernel subsystem or a driver.}(hj9hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj(hhubh)}(hhh](h)}(h Subsystemsh]h Subsystems}(hjJhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjGhhhhhKubh)}(hXEvery test suite must belong to a subsystem. A subsystem is a collection of one or more KUnit test suites which test the same driver or part of the kernel. A test subsystem should match a single kernel module. If the code being tested cannot be compiled as a module, in many cases the subsystem should correspond to a directory in the source tree or an entry in the ``MAINTAINERS`` file. If unsure, follow the conventions set by tests in similar areas.h](hXnEvery test suite must belong to a subsystem. A subsystem is a collection of one or more KUnit test suites which test the same driver or part of the kernel. A test subsystem should match a single kernel module. If the code being tested cannot be compiled as a module, in many cases the subsystem should correspond to a directory in the source tree or an entry in the }(hjXhhhNhNubhliteral)}(h``MAINTAINERS``h]h MAINTAINERS}(hjbhhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjXubhG file. If unsure, follow the conventions set by tests in similar areas.}(hjXhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjGhhubh)}(hTest subsystems should be named after the code being tested, either after the module (wherever possible), or after the directory or files being tested. Test subsystems should be named to avoid ambiguity where necessary.h]hTest subsystems should be named after the code being tested, either after the module (wherever possible), or after the directory or files being tested. Test subsystems should be named to avoid ambiguity where necessary.}(hjzhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK&hjGhhubh)}(hXIf a test subsystem name has multiple components, they should be separated by underscores. *Do not* include "test" or "kunit" directly in the subsystem name unless we are actually testing other tests or the kunit framework itself. For example, subsystems could be called:h](h[If a test subsystem name has multiple components, they should be separated by underscores. }(hjhhhNhNubhemphasis)}(h*Do not*h]hDo not}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh include “test” or “kunit” directly in the subsystem name unless we are actually testing other tests or the kunit framework itself. For example, subsystems could be called:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK*hjGhhubhdefinition_list)}(hhh](hdefinition_list_item)}(h0``ext4`` Matches the module and filesystem name.h](hterm)}(h``ext4``h]ja)}(hjh]hext4}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjubah}(h]h ]h"]h$]h&]uh1jhhhK/hjubh definition)}(hhh]h)}(h'Matches the module and filesystem name.h]h'Matches the module and filesystem name.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK0hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhK/hjubj)}(h2``apparmor`` Matches the module name and LSM name.h](j)}(h ``apparmor``h]ja)}(hjh]happarmor}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjubah}(h]h ]h"]h$]h&]uh1jhhhK1hjubj)}(hhh]h)}(h%Matches the module name and LSM name.h]h%Matches the module name and LSM name.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK2hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhK1hjhhubj)}(hK``kasan`` Common name for the tool, prominent part of the path ``mm/kasan``h](j)}(h ``kasan``h]ja)}(hj+h]hkasan}(hj-hhhNhNubah}(h]h ]h"]h$]h&]uh1j`hj)ubah}(h]h ]h"]h$]h&]uh1jhhhK3hj%ubj)}(hhh]h)}(hACommon name for the tool, prominent part of the path ``mm/kasan``h](h5Common name for the tool, prominent part of the path }(hjChhhNhNubja)}(h ``mm/kasan``h]hmm/kasan}(hjKhhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjCubeh}(h]h ]h"]h$]h&]uh1hhhhK4hj@ubah}(h]h ]h"]h$]h&]uh1jhj%ubeh}(h]h ]h"]h$]h&]uh1jhhhK3hjhhubj)}(h``snd_hda_codec_hdmi`` Has several components (``snd``, ``hda``, ``codec``, ``hdmi``) separated by underscores. Matches the module name. h](j)}(h``snd_hda_codec_hdmi``h]ja)}(hjqh]hsnd_hda_codec_hdmi}(hjshhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjoubah}(h]h ]h"]h$]h&]uh1jhhhK7hjkubj)}(hhh]h)}(hqHas several components (``snd``, ``hda``, ``codec``, ``hdmi``) separated by underscores. Matches the module name.h](hHas several components (}(hjhhhNhNubja)}(h``snd``h]hsnd}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjubh, }(hjhhhNhNubja)}(h``hda``h]hhda}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjubh, }hjsbja)}(h ``codec``h]hcodec}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjubh, }hjsbja)}(h``hdmi``h]hhdmi}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjubh4) separated by underscores. Matches the module name.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK6hjubah}(h]h ]h"]h$]h&]uh1jhjkubeh}(h]h ]h"]h$]h&]uh1jhhhK7hjhhubeh}(h]h ]h"]h$]h&]uh1jhjGhhhhhNubh)}(h'Avoid names as shown in examples below:h]h'Avoid names as shown in examples below:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK9hjGhhubj)}(hhh](j)}(hh``linear-ranges`` Names should use underscores, not dashes, to separate words. Prefer ``linear_ranges``.h](j)}(h``linear-ranges``h]ja)}(hjh]h linear-ranges}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjubah}(h]h ]h"]h$]h&]uh1jhhhKhhhhhKMubh)}(hX'KUnit tests are grouped into test suites, which cover a specific area of functionality being tested. Test suites can have shared initialization and shutdown code which is run for all tests in the suite. Not all subsystems need to be split into multiple test suites (for example, simple drivers).h]hX'KUnit tests are grouped into test suites, which cover a specific area of functionality being tested. Test suites can have shared initialization and shutdown code which is run for all tests in the suite. Not all subsystems need to be split into multiple test suites (for example, simple drivers).}(hjOhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKOhj>hhubh)}(hTest suites are named after the subsystem they are part of. If a subsystem contains several suites, the specific area under test should be appended to the subsystem name, separated by an underscore.h]hTest suites are named after the subsystem they are part of. If a subsystem contains several suites, the specific area under test should be appended to the subsystem name, separated by an underscore.}(hj]hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKThj>hhubh)}(hXYIn the event that there are multiple types of test using KUnit within a subsystem (for example, both unit tests and integration tests), they should be put into separate suites, with the type of test as the last element in the suite name. Unless these tests are actually present, avoid using ``_test``, ``_unittest`` or similar in the suite name.h](hX#In the event that there are multiple types of test using KUnit within a subsystem (for example, both unit tests and integration tests), they should be put into separate suites, with the type of test as the last element in the suite name. Unless these tests are actually present, avoid using }(hjkhhhNhNubja)}(h ``_test``h]h_test}(hjshhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjkubh, }(hjkhhhNhNubja)}(h ``_unittest``h]h _unittest}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjkubh or similar in the suite name.}(hjkhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKXhj>hhubh)}(hThe full test suite name (including the subsystem name) should be specified as the ``.name`` member of the ``kunit_suite`` struct, and forms the base for the module name. For example, test suites could include:h](hSThe full test suite name (including the subsystem name) should be specified as the }(hjhhhNhNubja)}(h ``.name``h]h.name}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjubh member of the }(hjhhhNhNubja)}(h``kunit_suite``h]h kunit_suite}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjubhX struct, and forms the base for the module name. For example, test suites could include:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK^hj>hhubj)}(hhh](j)}(hJ``ext4_inode`` Part of the ``ext4`` subsystem, testing the ``inode`` area.h](j)}(h``ext4_inode``h]ja)}(hjh]h ext4_inode}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjubah}(h]h ]h"]h$]h&]uh1jhhhKbhjubj)}(hhh]h)}(h;Part of the ``ext4`` subsystem, testing the ``inode`` area.h](h Part of the }(hjhhhNhNubja)}(h``ext4``h]hext4}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjubh subsystem, testing the }(hjhhhNhNubja)}(h ``inode``h]hinode}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjubh area.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKchjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhKbhjubj)}(h```kunit_try_catch`` Part of the ``kunit`` implementation itself, testing the ``try_catch`` area.h](j)}(h``kunit_try_catch``h]ja)}(hj4h]hkunit_try_catch}(hj6hhhNhNubah}(h]h ]h"]h$]h&]uh1j`hj2ubah}(h]h ]h"]h$]h&]uh1jhhhKdhj.ubj)}(hhh]h)}(hLPart of the ``kunit`` implementation itself, testing the ``try_catch`` area.h](h Part of the }(hjLhhhNhNubja)}(h ``kunit``h]hkunit}(hjThhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjLubh$ implementation itself, testing the }(hjLhhhNhNubja)}(h ``try_catch``h]h try_catch}(hjfhhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjLubh area.}(hjLhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKehjIubah}(h]h ]h"]h$]h&]uh1jhj.ubeh}(h]h ]h"]h$]h&]uh1jhhhKdhjhhubj)}(hd``apparmor_property_entry`` Part of the ``apparmor`` subsystem, testing the ``property_entry`` area.h](j)}(h``apparmor_property_entry``h]ja)}(hjh]happarmor_property_entry}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjubah}(h]h ]h"]h$]h&]uh1jhhhKfhjubj)}(hhh]h)}(hHPart of the ``apparmor`` subsystem, testing the ``property_entry`` area.h](h Part of the }(hjhhhNhNubja)}(h ``apparmor``h]happarmor}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjubh subsystem, testing the }(hjhhhNhNubja)}(h``property_entry``h]hproperty_entry}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjubh area.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKghjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhKfhjhhubj)}(hk``kasan`` The ``kasan`` subsystem has only one suite, so the suite name is the same as the subsystem name. h](j)}(h ``kasan``h]ja)}(hjh]hkasan}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjubah}(h]h ]h"]h$]h&]uh1jhhhKjhjubj)}(hhh]h)}(h`The ``kasan`` subsystem has only one suite, so the suite name is the same as the subsystem name.h](hThe }(hjhhhNhNubja)}(h ``kasan``h]hkasan}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjubhS subsystem has only one suite, so the suite name is the same as the subsystem name.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKihjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhKjhjhhubeh}(h]h ]h"]h$]h&]uh1jhj>hhhhhNubh)}(hAvoid names, for example:h]hAvoid names, for example:}(hj6hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKlhj>hhubj)}(hhh](j)}(hD``ext4_ext4_inode`` There is no reason to state the subsystem twice.h](j)}(h``ext4_ext4_inode``h]ja)}(hjMh]hext4_ext4_inode}(hjOhhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjKubah}(h]h ]h"]h$]h&]uh1jhhhKnhjGubj)}(hhh]h)}(h0There is no reason to state the subsystem twice.h]h0There is no reason to state the subsystem twice.}(hjehhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKohjbubah}(h]h ]h"]h$]h&]uh1jhjGubeh}(h]h ]h"]h$]h&]uh1jhhhKnhjDubj)}(hJ``property_entry`` The suite name is ambiguous without the subsystem name.h](j)}(h``property_entry``h]ja)}(hjh]hproperty_entry}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjubah}(h]h ]h"]h$]h&]uh1jhhhKphjubj)}(hhh]h)}(h7The suite name is ambiguous without the subsystem name.h]h7The suite name is ambiguous without the subsystem name.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKqhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhKphjDhhubj)}(hXA``kasan_integration_test`` Because there is only one suite in the ``kasan`` subsystem, the suite should just be called as ``kasan``. Do not redundantly add ``integration_test``. It should be a separate test suite. For example, if the unit tests are added, then that suite could be named as ``kasan_unittest`` or similar. h](j)}(h``kasan_integration_test``h]ja)}(hjh]hkasan_integration_test}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjubah}(h]h ]h"]h$]h&]uh1jhhhKwhjubj)}(hhh]h)}(hX%Because there is only one suite in the ``kasan`` subsystem, the suite should just be called as ``kasan``. Do not redundantly add ``integration_test``. It should be a separate test suite. For example, if the unit tests are added, then that suite could be named as ``kasan_unittest`` or similar.h](h'Because there is only one suite in the }(hjhhhNhNubja)}(h ``kasan``h]hkasan}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjubh/ subsystem, the suite should just be called as }(hjhhhNhNubja)}(h ``kasan``h]hkasan}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjubh. Do not redundantly add }(hjhhhNhNubja)}(h``integration_test``h]hintegration_test}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjubhr. It should be a separate test suite. For example, if the unit tests are added, then that suite could be named as }(hjhhhNhNubja)}(h``kasan_unittest``h]hkasan_unittest}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjubh or similar.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKshjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhKwhjDhhubeh}(h]h ]h"]h$]h&]uh1jhj>hhhhhNubeh}(h]suitesah ]h"]suitesah$]h&]uh1hhj(hhhhhKMubh)}(hhh](h)}(h Test Casesh]h Test Cases}(hjHhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjEhhhhhKzubh)}(hIndividual tests consist of a single function which tests a constrained codepath, property, or function. In the test output, an individual test's results will show up as subtests of the suite's results.h]hIndividual tests consist of a single function which tests a constrained codepath, property, or function. In the test output, an individual test’s results will show up as subtests of the suite’s results.}(hjVhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK|hjEhhubh)}(hXTests should be named after what they are testing. This is often the name of the function being tested, with a description of the input or codepath being tested. As tests are C functions, they should be named and written in accordance with the kernel coding style.h]hXTests should be named after what they are testing. This is often the name of the function being tested, with a description of the input or codepath being tested. As tests are C functions, they should be named and written in accordance with the kernel coding style.}(hjdhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjEhhubj)}(hAs tests are themselves functions, their names cannot conflict with other C identifiers in the kernel. This may require some creative naming. It is a good idea to make your test functions `static` to avoid polluting the global namespace.h]h)}(hAs tests are themselves functions, their names cannot conflict with other C identifiers in the kernel. This may require some creative naming. It is a good idea to make your test functions `static` to avoid polluting the global namespace.h](hAs tests are themselves functions, their names cannot conflict with other C identifiers in the kernel. This may require some creative naming. It is a good idea to make your test functions }(hjvhhhNhNubhtitle_reference)}(h`static`h]hstatic}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j~hjvubh) to avoid polluting the global namespace.}(hjvhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjrubah}(h]h ]h"]h$]h&]uh1jhjEhhhhhNubh)}(hExample test names include:h]hExample test names include:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjEhhubj)}(hhh](j)}(h^``unpack_u32_with_null_name`` Tests the ``unpack_u32`` function when a NULL name is passed in.h](j)}(h``unpack_u32_with_null_name``h]ja)}(hjh]hunpack_u32_with_null_name}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjubah}(h]h ]h"]h$]h&]uh1jhhhKhjubj)}(hhh]h)}(h@Tests the ``unpack_u32`` function when a NULL name is passed in.h](h Tests the }(hjhhhNhNubja)}(h``unpack_u32``h]h unpack_u32}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjubh( function when a NULL name is passed in.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhKhjubj)}(h``test_list_splice`` Tests the ``list_splice`` macro. It has the prefix ``test_`` to avoid a name conflict with the macro itself. h](j)}(h``test_list_splice``h]ja)}(hjh]htest_list_splice}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjubah}(h]h ]h"]h$]h&]uh1jhhhKhjubj)}(hhh]h)}(hlTests the ``list_splice`` macro. It has the prefix ``test_`` to avoid a name conflict with the macro itself.h](h Tests the }(hjhhhNhNubja)}(h``list_splice``h]h list_splice}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjubh macro. It has the prefix }(hjhhhNhNubja)}(h ``test_``h]htest_}(hj1hhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjubh0 to avoid a name conflict with the macro itself.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhKhjhhubeh}(h]h ]h"]h$]h&]uh1jhjEhhhhhNubh)}(hShould it be necessary to refer to a test outside the context of its test suite, the *fully-qualified* name of a test should be the suite name followed by the test name, separated by a colon (i.e. ``suite:test``).h](hUShould it be necessary to refer to a test outside the context of its test suite, the }(hj[hhhNhNubj)}(h*fully-qualified*h]hfully-qualified}(hjchhhNhNubah}(h]h ]h"]h$]h&]uh1jhj[ubh_ name of a test should be the suite name followed by the test name, separated by a colon (i.e. }(hj[hhhNhNubja)}(h``suite:test``h]h suite:test}(hjuhhhNhNubah}(h]h ]h"]h$]h&]uh1j`hj[ubh).}(hj[hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjEhhubeh}(h] test-casesah ]h"] test casesah$]h&]uh1hhj(hhhhhKzubeh}(h]subsystems-suites-and-testsah ]h"]subsystems, suites, and testsah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hTest Kconfig Entriesh]hTest Kconfig Entries}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(h3Every test suite should be tied to a Kconfig entry.h]h3Every test suite should be tied to a Kconfig entry.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hThis Kconfig entry must:h]hThis Kconfig entry must:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh bullet_list)}(hhh](h)}(hRbe named ``CONFIG__KUNIT_TEST``: where is the name of the test suite.h]h)}(hRbe named ``CONFIG__KUNIT_TEST``: where is the name of the test suite.h](h be named }(hjhhhNhNubja)}(h``CONFIG__KUNIT_TEST``h]hCONFIG__KUNIT_TEST}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjubh-: where is the name of the test suite.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(hbe listed either alongside the config entries for the driver/subsystem being tested, or be under [Kernel Hacking]->[Kernel Testing and Coverage]h]h)}(hbe listed either alongside the config entries for the driver/subsystem being tested, or be under [Kernel Hacking]->[Kernel Testing and Coverage]h]hbe listed either alongside the config entries for the driver/subsystem being tested, or be under [Kernel Hacking]->[Kernel Testing and Coverage]}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(hdepend on ``CONFIG_KUNIT``.h]h)}(hj h](h depend on }(hj hhhNhNubja)}(h``CONFIG_KUNIT``h]h CONFIG_KUNIT}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j`hj ubh.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(h=be visible only if ``CONFIG_KUNIT_ALL_TESTS`` is not enabled.h]h)}(hj< h](hbe visible only if }(hj> hhhNhNubja)}(h``CONFIG_KUNIT_ALL_TESTS``h]hCONFIG_KUNIT_ALL_TESTS}(hjE hhhNhNubah}(h]h ]h"]h$]h&]uh1j`hj> ubh is not enabled.}(hj> hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj: ubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(h3have a default value of ``CONFIG_KUNIT_ALL_TESTS``.h]h)}(hje h](hhave a default value of }(hjg hhhNhNubja)}(h``CONFIG_KUNIT_ALL_TESTS``h]hCONFIG_KUNIT_ALL_TESTS}(hjn hhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjg ubh.}(hjg hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjc ubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(h4have a brief description of KUnit in the help text. h]h)}(h3have a brief description of KUnit in the help text.h]h3have a brief description of KUnit in the help text.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubeh}(h]h ]h"]h$]h&]bullet*uh1jhhhKhjhhubh)}(hIf we are not able to meet above conditions (for example, the test is unable to be built as a module), Kconfig entries for tests should be tristate.h]hIf we are not able to meet above conditions (for example, the test is unable to be built as a module), Kconfig entries for tests should be tristate.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(h-For example, a Kconfig entry might look like:h]h-For example, a Kconfig entry might look like:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh literal_block)}(hXuconfig FOO_KUNIT_TEST tristate "KUnit test for foo" if !KUNIT_ALL_TESTS depends on KUNIT default KUNIT_ALL_TESTS help This builds unit tests for foo. For more information on KUnit and unit tests in general, please refer to the KUnit documentation in Documentation/dev-tools/kunit/. If unsure, say N.h]hXuconfig FOO_KUNIT_TEST tristate "KUnit test for foo" if !KUNIT_ALL_TESTS depends on KUNIT default KUNIT_ALL_TESTS help This builds unit tests for foo. For more information on KUnit and unit tests in general, please refer to the KUnit documentation in Documentation/dev-tools/kunit/. If unsure, say N.}hj sbah}(h]h ]h"]h$]h&]hhforcelanguagenonehighlight_args}uh1j hhhKhjhhubeh}(h]test-kconfig-entriesah ]h"]test kconfig entriesah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hTest File and Module Namesh]hTest File and Module Names}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhKubh)}(hKUnit tests are often compiled as a separate module. To avoid conflicting with regular modules, KUnit modules should be named after the test suite, followed by ``_kunit`` (e.g. if "foobar" is the core module, then "foobar_kunit" is the KUnit test module).h](hKUnit tests are often compiled as a separate module. To avoid conflicting with regular modules, KUnit modules should be named after the test suite, followed by }(hj hhhNhNubja)}(h ``_kunit``h]h_kunit}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j`hj ubh] (e.g. if “foobar” is the core module, then “foobar_kunit” is the KUnit test module).}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj hhubh)}(hTest source files, whether compiled as a separate module or an ``#include`` in another source file, are best kept in a ``tests/`` subdirectory to not conflict with other source files (e.g. for tab-completion).h](h?Test source files, whether compiled as a separate module or an }(hj hhhNhNubja)}(h ``#include``h]h#include}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j`hj ubh, in another source file, are best kept in a }(hj hhhNhNubja)}(h ``tests/``h]htests/}(hj0 hhhNhNubah}(h]h ]h"]h$]h&]uh1j`hj ubhP subdirectory to not conflict with other source files (e.g. for tab-completion).}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj hhubh)}(hNote that the ``_test`` suffix has also been used in some existing tests. The ``_kunit`` suffix is preferred, as it makes the distinction between KUnit and non-KUnit tests clearer.h](hNote that the }(hjH hhhNhNubja)}(h ``_test``h]h_test}(hjP hhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjH ubh7 suffix has also been used in some existing tests. The }(hjH hhhNhNubja)}(h ``_kunit``h]h_kunit}(hjb hhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjH ubh\ suffix is preferred, as it makes the distinction between KUnit and non-KUnit tests clearer.}(hjH hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj hhubh)}(hSo for the common case, name the file containing the test suite ``tests/_kunit.c``. The ``tests`` directory should be placed at the same level as the code under test. For example, tests for ``lib/string.c`` live in ``lib/tests/string_kunit.c``.h](h@So for the common case, name the file containing the test suite }(hjz hhhNhNubja)}(h``tests/_kunit.c``h]htests/_kunit.c}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjz ubh. The }(hjz hhhNhNubja)}(h ``tests``h]htests}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjz ubh] directory should be placed at the same level as the code under test. For example, tests for }(hjz hhhNhNubja)}(h``lib/string.c``h]h lib/string.c}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjz ubh live in }(hjz hhhNhNubja)}(h``lib/tests/string_kunit.c``h]hlib/tests/string_kunit.c}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j`hjz ubh.}(hjz hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj hhubh)}(hIf the suite name contains some or all of the name of the test's parent directory, it may make sense to modify the source filename to reduce redundancy. For example, a ``foo_firmware`` suite could be in the ``foo/tests/firmware_kunit.c`` file.h](hIf the suite name contains some or all of the name of the test’s parent directory, it may make sense to modify the source filename to reduce redundancy. For example, a }(hj hhhNhNubja)}(h``foo_firmware``h]h foo_firmware}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j`hj ubh suite could be in the }(hj hhhNhNubja)}(h``foo/tests/firmware_kunit.c``h]hfoo/tests/firmware_kunit.c}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j`hj ubh file.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj hhubeh}(h]test-file-and-module-namesah ]h"]test file and module namesah$]h&]uh1hhhhhhhhKubeh}(h]test-style-and-nomenclatureah ]h"]test style and nomenclatureah$]h&]uh1hhhhhhhhKubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerj5 error_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourceh _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}nameids}(j j jjj;j8jBj?jjj j j j u nametypes}(j jj;jBjj j uh}(j hjj(j8jGj?j>jjEj jj j u footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}Rparse_messages]transform_messages] transformerN include_log] decorationNhhub.