요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. SPDX-License-Identifier: GPL-2.0
===========================
Test Style and Nomenclature
===========================
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.
It is recommended that you only deviate from these guidelines when:
1. Porting tests to KUnit which are already known with an existing name.
2. Writing 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.
Subsystems, Suites, and Tests
=============================
To 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.
Subsystems
----------
Every 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.
Test 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.
If 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:
``ext4``
Matches the module and filesystem name.
``apparmor``
Matches the module name and LSM name.
``kasan``
Common name for the tool, prominent part of the path ``mm/kasan``
``snd_hda_codec_hdmi``
Has several components (``snd``, ``hda``, ``codec``, ``hdmi``) separated by
underscores. Matches the module name.
Avoid names as shown in examples below:
``linear-ranges``
Names should use underscores, not dashes, to separate words. Prefer
``linear_ranges``.
``qos-kunit-test``
This name should use underscores, and not have "kunit-test" as a
suffix. ``qos`` is also ambiguous as a subsystem name, because several parts
of the kernel have a ``qos`` subsystem. ``power_qos`` would be a better name.
``pc_parallel_port``
The corresponding module name is ``parport_pc``, so this subsystem should also
be named ``parport_pc``.
.. note::
The KUnit API and tools do not explicitly know about subsystems. They are
a way of categorizing test suites and naming modules which provides a
simple, consistent way for humans to find and run tests. This may change
in the future.
Suites
------
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).
Test 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.
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 ``_test``, ``_unittest``
or similar in the suite name.
The 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:
``ext4_inode``
Part of the ``ext4`` subsystem, testing the ``inode`` area.
``kunit_try_catch``
Part of the ``kunit`` implementation itself, testing the ``try_catch`` area.
``apparmor_property_entry``
Part of the ``apparmor`` subsystem, testing the ``property_entry`` area.
``kasan``
The ``kasan`` subsystem has only one suite, so the suite name is the same as
the subsystem name.
Avoid names, for example:
``ext4_ext4_inode``
There is no reason to state the subsystem twice.
``property_entry``
The suite name is ambiguous without the subsystem name.
``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.
Test Cases
----------
Individual 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.
Tests 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.
.. note::
As 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.
Example test names include:
``unpack_u32_with_null_name``
Tests the ``unpack_u32`` function when a NULL name is passed in.
``test_list_splice``
Tests the ``list_splice`` macro. It has the prefix ``test_`` to avoid a
name conflict with the macro itself.
Should 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``).
Test Kconfig Entries
====================
Every test suite should be tied to a Kconfig entry.
This Kconfig entry must:
* be named ``CONFIG_<name>_KUNIT_TEST``: where <name> is the name of the test
suite.
* be listed either alongside the config entries for the driver/subsystem being
tested, or be under [Kernel Hacking]->[Kernel Testing and Coverage]
* depend on ``CONFIG_KUNIT``.
* be visible only if ``CONFIG_KUNIT_ALL_TESTS`` is not enabled.
* have a default value of ``CONFIG_KUNIT_ALL_TESTS``.
* have a brief description of KUnit in the help text.
If 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.
For example, a Kconfig entry might look like:
.. code-block:: none
config 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.
Test File and Module Names
==========================
KUnit 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).
Test 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).
Note 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.
So for the common case, name the file containing the test suite
``tests/<suite>_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``.
If 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.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
Test style과 명명 지침
1-19SPDX 라이선스 식별자: GPL-2.0
Test style과 nomenclature
KUnit test를 최대한 쉽게 찾고 작성하고 사용할 수 있도록 아래 지침에 따라 이름을 짓고 작성할 것을 강하게 권장합니다. 이 규칙을 따르지 않는 KUnit test도 작성할 수는 있지만 일부 tooling이 깨지거나 다른 테스트와 충돌하거나 testing system이 자동 실행하지 못할 수 있습니다.
다음 경우에만 이 지침에서 벗어나는 것이 좋습니다.
1. 이미 기존 이름으로 알려진 테스트를 KUnit으로 port하는 경우입니다.
2. 자동 실행했을 때 심각한 문제를 일으킬 테스트를 작성하는 경우입니다. 예를 들어 비결정적으로 false positive 또는 false negative를 만들거나 실행 시간이 매우 긴 테스트입니다.
Subsystem 정의와 이름
20-75Subsystem, suite와 test
테스트를 쉽게 찾을 수 있도록 suite와 subsystem으로 묶습니다. Test suite는 kernel의 서로 관련된 영역을 검사하는 test group입니다. Subsystem은 kernel subsystem 또는 driver의 서로 다른 부분을 검사하는 test suite 집합입니다.
Subsystem
모든 test suite는 subsystem에 속해야 합니다. Subsystem은 같은 driver 또는 kernel 부분을 검사하는 하나 이상의 KUnit test suite 모음입니다.
Test subsystem은 하나의 kernel module과 대응해야 합니다. 검사할 code를 module로 compile할 수 없다면 많은 경우 source tree directory 또는 `MAINTAINERS` file의 entry와 대응해야 합니다. 확실하지 않으면 비슷한 영역의 test가 세운 convention을 따릅니다.
Test subsystem은 가능한 경우 module 이름을 따르고, 그렇지 않으면 검사할 directory 또는 file 이름을 따라야 합니다. 필요한 경우 모호하지 않도록 이름을 정합니다.
Subsystem 이름에 여러 component가 있으면 underscore로 구분합니다. 다른 test 자체나 KUnit framework를 검사하는 경우가 아니라면 subsystem 이름에 `test` 또는 `kunit`을 직접 포함하지 마십시오.
`ext4`는 module과 filesystem 이름에 대응합니다. `apparmor`는 module과 LSM 이름에 대응합니다. `kasan`은 tool의 일반적인 이름이며 `mm/kasan` path의 핵심 부분입니다.
`snd_hda_codec_hdmi`는 `snd`, `hda`, `codec`, `hdmi` component를 underscore로 구분하며 module 이름과 일치합니다.
다음과 같은 이름은 피해야 합니다.
`linear-ranges`는 단어 구분에 dash를 사용하므로 잘못되었습니다. `linear_ranges`가 좋습니다.
`qos-kunit-test`는 underscore를 사용해야 하고 `kunit-test` suffix를 붙이지 않아야 합니다. 또한 kernel 여러 부분에 `qos` subsystem이 있어 이름도 모호합니다. `power_qos`가 더 나은 이름입니다.
`pc_parallel_port`에 대응하는 module 이름은 `parport_pc`이므로 subsystem도 `parport_pc`로 이름 지어야 합니다.
참고: KUnit API와 tool은 subsystem을 명시적으로 알지 못합니다. Subsystem은 test suite를 분류하고 module 이름을 정해 사람이 테스트를 찾고 실행할 수 있게 하는 단순하고 일관된 방법입니다. 이는 향후 바뀔 수 있습니다.
Subsystem, suite와 case가 담당하는 범위와 이름 기준을 정리했습니다.
권장 이름과 피해야 할 이름의 차이를 보여 줍니다.
Test suite 구성과 이름
76-120Suite
KUnit test는 검사할 특정 기능 영역을 다루는 test suite로 묶입니다. Suite에는 그 안의 모든 테스트에 대해 실행되는 공통 initialization과 shutdown code를 둘 수 있습니다. 단순한 driver처럼 모든 subsystem을 여러 suite로 나눌 필요는 없습니다.
Test suite 이름은 자신이 속한 subsystem 이름을 따릅니다. Subsystem에 여러 suite가 있다면 검사할 세부 영역을 underscore로 구분해 subsystem 이름 뒤에 붙입니다.
한 subsystem 안에서 KUnit을 사용하는 test type이 여러 개라면, 예를 들어 unit test와 integration test가 모두 있다면 서로 다른 suite에 넣고 test type을 suite 이름의 마지막 component로 둡니다. 실제로 여러 type이 존재하지 않는다면 suite 이름에 `_test`, `_unittest` 같은 suffix를 사용하지 마십시오.
Subsystem 이름을 포함한 전체 test suite 이름은 `kunit_suite` struct의 `.name` member로 지정하며 module 이름의 base가 됩니다.
`ext4_inode`는 `ext4` subsystem의 `inode` 영역을 검사합니다. `kunit_try_catch`는 KUnit 구현 자체의 `try_catch` 영역을 검사합니다. `apparmor_property_entry`는 `apparmor` subsystem의 `property_entry` 영역을 검사합니다.
`kasan` subsystem에는 suite가 하나뿐이므로 subsystem과 suite 이름이 같습니다.
다음 이름은 피해야 합니다.
`ext4_ext4_inode`는 subsystem 이름을 불필요하게 두 번 반복합니다.
`property_entry`는 subsystem 이름이 없어 어느 영역의 suite인지 모호합니다.
`kasan_integration_test`는 `kasan` subsystem에 suite가 하나뿐인 상황에서 `integration_test`를 불필요하게 덧붙였습니다. 이때 suite 이름은 단순히 `kasan`이어야 합니다.
나중에 unit test가 추가되어 별도의 test suite가 실제로 필요해지면 그 suite는 `kasan_unittest` 또는 비슷한 이름으로 정할 수 있습니다.
개별 test case 이름
121-151Test case
개별 테스트는 제한된 codepath, property 또는 function을 검사하는 하나의 function으로 구성됩니다. Test output에서 개별 test 결과는 suite 결과의 subtest로 나타납니다.
Test 이름은 검사 대상을 따라야 합니다. 흔히 검사할 function 이름에 검사할 input 또는 codepath 설명을 붙입니다. Test는 C function이므로 kernel coding style에 맞게 이름을 짓고 작성해야 합니다.
참고: Test 자체가 function이므로 이름이 kernel의 다른 C identifier와 충돌할 수 없습니다. 이를 피하려면 이름을 창의적으로 정해야 할 수 있습니다. Global namespace를 오염시키지 않도록 test function을 `static`으로 만드는 것이 좋습니다.
`unpack_u32_with_null_name`은 NULL name을 전달했을 때의 `unpack_u32` function을 검사합니다.
`test_list_splice`는 `list_splice` macro를 검사합니다. Macro 자체와 이름이 충돌하지 않도록 `test_` prefix를 붙였습니다.
Test suite context 밖에서 test를 지칭해야 한다면 fully-qualified name은 suite 이름과 test 이름을 colon으로 구분한 `suite:test` 형식이어야 합니다.
Test Kconfig entry
152-187Test Kconfig entry
모든 test suite는 Kconfig entry와 연결되어야 합니다.
Kconfig entry는 다음 조건을 충족해야 합니다.
이름은 `CONFIG_<name>_KUNIT_TEST`여야 하며 `<name>`은 test suite 이름입니다.
검사할 driver 또는 subsystem의 config entry와 나란히 두거나 `[Kernel Hacking] -> [Kernel Testing and Coverage]` 아래에 둡니다.
`CONFIG_KUNIT`에 dependency를 둡니다.
`CONFIG_KUNIT_ALL_TESTS`가 활성화되지 않았을 때만 사용자에게 보이도록 합니다.
Default value를 `CONFIG_KUNIT_ALL_TESTS`로 설정합니다.
Help text에 KUnit에 대한 짧은 설명을 넣습니다.
위 조건을 충족할 수 없는 경우, 예를 들어 테스트를 module로 build할 수 없는 경우에도 원문 지침은 test Kconfig entry가 tristate여야 한다고 설명합니다.
Kconfig entry 예는 다음과 같습니다.
config 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.Test file과 module 이름
188-213Test file과 module 이름
KUnit test는 흔히 별도 module로 compile됩니다. 일반 module과 충돌하지 않도록 KUnit module은 test suite 이름 뒤에 `_kunit`을 붙여야 합니다. 예를 들어 core module이 `foobar`라면 KUnit test module은 `foobar_kunit`입니다.
Test source file은 별도 module로 compile하든 다른 source file에서 `#include`하든, 다른 source file과 충돌하지 않도록 `tests/` subdirectory에 두는 것이 좋습니다. Tab completion에서 이름이 섞이는 문제도 줄어듭니다.
기존 test 일부는 `_test` suffix도 사용해 왔습니다. KUnit test와 non-KUnit test를 더 명확히 구분하는 `_kunit` suffix를 권장합니다.
일반적인 경우 test suite를 포함하는 file 이름은 `tests/<suite>_kunit.c`로 정합니다. `tests` directory는 검사할 code와 같은 level에 둡니다. 예를 들어 `lib/string.c` 테스트는 `lib/tests/string_kunit.c`에 둡니다.
Suite 이름에 parent directory 이름 일부 또는 전부가 들어 있다면 중복을 줄이도록 source filename을 조정할 수 있습니다. 예를 들어 `foo_firmware` suite는 `foo/tests/firmware_kunit.c` file에 둘 수 있습니다.
Suite 이름에서 Kconfig, module과 source file 이름을 만드는 convention을 정리했습니다.
요약과 해설
style.rst:1-213KUnit 명명 규칙은 사람이 테스트를 쉽게 찾도록 할 뿐 아니라 tooling과 자동 testing system이 suite를 안정적으로 발견하고 실행하게 합니다. Subsystem은 module이나 kernel 영역, suite는 그 안의 세부 기능, case는 구체적인 codepath나 input을 나타냅니다.
Kconfig는 `CONFIG_<name>_KUNIT_TEST`, module은 `<suite>_kunit`, source는 `tests/<suite>_kunit.c` 형식을 기본으로 합니다. 이름의 중복과 모호함을 피하고 underscore를 일관되게 사용하는 것이 핵심입니다.