Commit e5885866 authored by Rae Moar's avatar Rae Moar Committed by Shuah Khan

kunit: Add documentation of KUnit test attributes

Add documentation on the use of test attributes under the section "Tips for
Running KUnit Tests" in the KUnit docs.

Documentation includes three sections on how to mark tests with attributes,
how attributes are reported, and how the user can filter tests using test
attributes.

Add descriptions of new flags to list of command-line arguments.
Reviewed-by: default avatarDavid Gow <davidgow@google.com>
Signed-off-by: default avatarRae Moar <rmoar@google.com>
Signed-off-by: default avatarShuah Khan <skhan@linuxfoundation.org>
parent 76066f93
...@@ -321,3 +321,15 @@ command line arguments: ...@@ -321,3 +321,15 @@ command line arguments:
- ``--json``: If set, stores the test results in a JSON format and prints to `stdout` or - ``--json``: If set, stores the test results in a JSON format and prints to `stdout` or
saves to a file if a filename is specified. saves to a file if a filename is specified.
- ``--filter``: Specifies filters on test attributes, for example, ``speed!=slow``.
Multiple filters can be used by wrapping input in quotes and separating filters
by commas. Example: ``--filter "speed>slow, module=example"``.
- ``--filter_action``: If set to ``skip``, filtered tests will be shown as skipped
in the output rather than showing no output.
- ``--list_tests``: If set, lists all tests that will be run.
- ``--list_tests_attr``: If set, lists all tests that will be run and all of their
attributes.
...@@ -262,3 +262,169 @@ other code executed during boot, e.g. ...@@ -262,3 +262,169 @@ other code executed during boot, e.g.
# Reset coverage counters before running the test. # Reset coverage counters before running the test.
$ echo 0 > /sys/kernel/debug/gcov/reset $ echo 0 > /sys/kernel/debug/gcov/reset
$ modprobe kunit-example-test $ modprobe kunit-example-test
Test Attributes and Filtering
=============================
Test suites and cases can be marked with test attributes, such as speed of
test. These attributes will later be printed in test output and can be used to
filter test execution.
Marking Test Attributes
-----------------------
Tests are marked with an attribute by including a ``kunit_attributes`` object
in the test definition.
Test cases can be marked using the ``KUNIT_CASE_ATTR(test_name, attributes)``
macro to define the test case instead of ``KUNIT_CASE(test_name)``.
.. code-block:: c
static const struct kunit_attributes example_attr = {
.speed = KUNIT_VERY_SLOW,
};
static struct kunit_case example_test_cases[] = {
KUNIT_CASE_ATTR(example_test, example_attr),
};
.. note::
To mark a test case as slow, you can also use ``KUNIT_CASE_SLOW(test_name)``.
This is a helpful macro as the slow attribute is the most commonly used.
Test suites can be marked with an attribute by setting the "attr" field in the
suite definition.
.. code-block:: c
static const struct kunit_attributes example_attr = {
.speed = KUNIT_VERY_SLOW,
};
static struct kunit_suite example_test_suite = {
...,
.attr = example_attr,
};
.. note::
Not all attributes need to be set in a ``kunit_attributes`` object. Unset
attributes will remain uninitialized and act as though the attribute is set
to 0 or NULL. Thus, if an attribute is set to 0, it is treated as unset.
These unset attributes will not be reported and may act as a default value
for filtering purposes.
Reporting Attributes
--------------------
When a user runs tests, attributes will be present in the raw kernel output (in
KTAP format). Note that attributes will be hidden by default in kunit.py output
for all passing tests but the raw kernel output can be accessed using the
``--raw_output`` flag. This is an example of how test attributes for test cases
will be formatted in kernel output:
.. code-block:: none
# example_test.speed: slow
ok 1 example_test
This is an example of how test attributes for test suites will be formatted in
kernel output:
.. code-block:: none
KTAP version 2
# Subtest: example_suite
# module: kunit_example_test
1..3
...
ok 1 example_suite
Additionally, users can output a full attribute report of tests with their
attributes, using the command line flag ``--list_tests_attr``:
.. code-block:: bash
kunit.py run "example" --list_tests_attr
.. note::
This report can be accessed when running KUnit manually by passing in the
module_param ``kunit.action=list_attr``.
Filtering
---------
Users can filter tests using the ``--filter`` command line flag when running
tests. As an example:
.. code-block:: bash
kunit.py run --filter speed=slow
You can also use the following operations on filters: "<", ">", "<=", ">=",
"!=", and "=". Example:
.. code-block:: bash
kunit.py run --filter "speed>slow"
This example will run all tests with speeds faster than slow. Note that the
characters < and > are often interpreted by the shell, so they may need to be
quoted or escaped, as above.
Additionally, you can use multiple filters at once. Simply separate filters
using commas. Example:
.. code-block:: bash
kunit.py run --filter "speed>slow, module=kunit_example_test"
.. note::
You can use this filtering feature when running KUnit manually by passing
the filter as a module param: ``kunit.filter="speed>slow, speed<=normal"``.
Filtered tests will not run or show up in the test output. You can use the
``--filter_action=skip`` flag to skip filtered tests instead. These tests will be
shown in the test output in the test but will not run. To use this feature when
running KUnit manually, use the module param ``kunit.filter_action=skip``.
Rules of Filtering Procedure
----------------------------
Since both suites and test cases can have attributes, there may be conflicts
between attributes during filtering. The process of filtering follows these
rules:
- Filtering always operates at a per-test level.
- If a test has an attribute set, then the test's value is filtered on.
- Otherwise, the value falls back to the suite's value.
- If neither are set, the attribute has a global "default" value, which is used.
List of Current Attributes
--------------------------
``speed``
This attribute indicates the speed of a test's execution (how slow or fast the
test is).
This attribute is saved as an enum with the following categories: "normal",
"slow", or "very_slow". The assumed default speed for tests is "normal". This
indicates that the test takes a relatively trivial amount of time (less than
1 second), regardless of the machine it is running on. Any test slower than
this could be marked as "slow" or "very_slow".
The macro ``KUNIT_CASE_SLOW(test_name)`` can be easily used to set the speed
of a test case to "slow".
``module``
This attribute indicates the name of the module associated with the test.
This attribute is automatically saved as a string and is printed for each suite.
Tests can also be filtered using this attribute.
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment