xsphinx.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]hPortuguese (Brazilian)}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget)/translations/pt_BR/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)}(hjh]hEPorting tests to KUnit which are already known with an existing name.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhhhhhhhNubj)}(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.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhhhhhhhNubeh}(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.}(hjMhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj<hhubh)}(hhh](h)}(h Subsystemsh]h Subsystems}(hj^hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj[hhhhhKubh)}(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 }(hjlhhhNhNubhliteral)}(h``MAINTAINERS``h]h MAINTAINERS}(hjvhhhNhNubah}(h]h ]h"]h$]h&]uh1jthjlubhG file. If unsure, follow the conventions set by tests in similar areas.}(hjlhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj[hhubh)}(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.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK&hj[hhubh)}(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*hj[hhubhdefinition_list)}(hhh](hdefinition_list_item)}(h0``ext4`` Matches the module and filesystem name.h](hterm)}(h``ext4``h]ju)}(hjh]hext4}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jthjubah}(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]ju)}(hjh]happarmor}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jthjubah}(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.}(hjhhhNhNubah}(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]ju)}(hj?h]hkasan}(hjAhhhNhNubah}(h]h ]h"]h$]h&]uh1jthj=ubah}(h]h ]h"]h$]h&]uh1jhhhK3hj9ubj)}(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 }(hjWhhhNhNubju)}(h ``mm/kasan``h]hmm/kasan}(hj_hhhNhNubah}(h]h ]h"]h$]h&]uh1jthjWubeh}(h]h ]h"]h$]h&]uh1hhhhK4hjTubah}(h]h ]h"]h$]h&]uh1jhj9ubeh}(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]ju)}(hjh]hsnd_hda_codec_hdmi}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jthjubah}(h]h ]h"]h$]h&]uh1jhhhK7hjubj)}(hhh]h)}(hqHas several components (``snd``, ``hda``, ``codec``, ``hdmi``) separated by underscores. Matches the module name.h](hHas several components (}(hjhhhNhNubju)}(h``snd``h]hsnd}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jthjubh, }(hjhhhNhNubju)}(h``hda``h]hhda}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jthjubh, }hjsbju)}(h ``codec``h]hcodec}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jthjubh, }hjsbju)}(h``hdmi``h]hhdmi}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jthjubh4) separated by underscores. Matches the module name.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK6hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhK7hjhhubeh}(h]h ]h"]h$]h&]uh1jhj[hhhhhNubh)}(h'Avoid names as shown in examples below:h]h'Avoid names as shown in examples below:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK9hj[hhubj)}(hhh](j)}(hh``linear-ranges`` Names should use underscores, not dashes, to separate words. Prefer ``linear_ranges``.h](j)}(h``linear-ranges``h]ju)}(hjh]h linear-ranges}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jthjubah}(h]h ]h"]h$]h&]uh1jhhhK_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 }(hjhhhNhNubju)}(h``CONFIG__KUNIT_TEST``h]hCONFIG__KUNIT_TEST}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jthjubh-: where is the name of the test suite.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(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]}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hdepend on ``CONFIG_KUNIT``.h]h)}(hj' h](h depend on }(hj) hhhNhNubju)}(h``CONFIG_KUNIT``h]h CONFIG_KUNIT}(hj0 hhhNhNubah}(h]h ]h"]h$]h&]uh1jthj) ubh.}(hj) hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj% ubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h=be visible only if ``CONFIG_KUNIT_ALL_TESTS`` is not enabled.h]h)}(hjP h](hbe visible only if }(hjR hhhNhNubju)}(h``CONFIG_KUNIT_ALL_TESTS``h]hCONFIG_KUNIT_ALL_TESTS}(hjY hhhNhNubah}(h]h ]h"]h$]h&]uh1jthjR ubh is not enabled.}(hjR hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjN ubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h3have a default value of ``CONFIG_KUNIT_ALL_TESTS``.h]h)}(hjy h](hhave a default value of }(hj{ hhhNhNubju)}(h``CONFIG_KUNIT_ALL_TESTS``h]hCONFIG_KUNIT_ALL_TESTS}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jthj{ ubh.}(hj{ hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjw ubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h3have a brief description of KUnit in the help text.h]h)}(hj 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&]uh1jhjhhhhhNubj)}(hdepend on the feature being tested, rather than selecting it (so that enabling ``CONFIG_KUNIT_ALL_TESTS`` does not enable unrelated functionality).h]h)}(hdepend on the feature being tested, rather than selecting it (so that enabling ``CONFIG_KUNIT_ALL_TESTS`` does not enable unrelated functionality).h](hOdepend on the feature being tested, rather than selecting it (so that enabling }(hj hhhNhNubju)}(h``CONFIG_KUNIT_ALL_TESTS``h]hCONFIG_KUNIT_ALL_TESTS}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jthj ubh* does not enable unrelated functionality).}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h^be ``tristate``, unless there is a specific reason that the test cannot be built as a module. h]h)}(h]be ``tristate``, unless there is a specific reason that the test cannot be built as a module.h](hbe }(hj hhhNhNubju)}(h ``tristate``h]htristate}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jthj ubhN, unless there is a specific reason that the test cannot be built as a module.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubeh}(h]h ]h"]h$]h&]bullet*uh1jhhhKhjhhubh)}(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&]hhƌforcelanguagenonehighlight_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}(hjA 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 }(hjO hhhNhNubju)}(h ``_kunit``h]h_kunit}(hjW hhhNhNubah}(h]h ]h"]h$]h&]uh1jthjO ubh] (e.g. if “foobar” is the core module, then “foobar_kunit” is the KUnit test module).}(hjO 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 }(hjo hhhNhNubju)}(h ``#include``h]h#include}(hjw hhhNhNubah}(h]h ]h"]h$]h&]uh1jthjo ubh, in another source file, are best kept in a }(hjo hhhNhNubju)}(h ``tests/``h]htests/}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jthjo ubhP subdirectory to not conflict with other source files (e.g. for tab-completion).}(hjo 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 }(hj hhhNhNubju)}(h ``_test``h]h_test}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jthj ubh7 suffix has also been used in some existing tests. The }(hj hhhNhNubju)}(h ``_kunit``h]h_kunit}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jthj ubh\ suffix is preferred, as it makes the distinction between KUnit and non-KUnit tests clearer.}(hj 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 }(hj hhhNhNubju)}(h``tests/_kunit.c``h]htests/_kunit.c}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jthj ubh. The }(hj hhhNhNubju)}(h ``tests``h]htests}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jthj ubh] directory should be placed at the same level as the code under test. For example, tests for }(hj hhhNhNubju)}(h``lib/string.c``h]h lib/string.c}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jthj ubh live in }(hj hhhNhNubju)}(h``lib/tests/string_kunit.c``h]hlib/tests/string_kunit.c}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jthj ubh.}(hj 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) hhhNhNubju)}(h``foo_firmware``h]h foo_firmware}(hj1 hhhNhNubah}(h]h ]h"]h$]h&]uh1jthj) ubh suite could be in the }(hj) hhhNhNubju)}(h``foo/tests/firmware_kunit.c``h]hfoo/tests/firmware_kunit.c}(hjC hhhNhNubah}(h]h ]h"]h$]h&]uh1jthj) 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_handlerj error_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourcehnj _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}(jh je jjjOjLjVjSjjj; j8 j` j] u nametypes}(jh jjOjVjj; j` uh}(je hjj<jLj[jSjRjjYj8 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.