[PATCH v4 9/9] KVM: selftests: Provide README.rst for KVM selftests runner

[Sean Christopherson]

On Tue, Mar 31, 2026, Vipin Sharma wrote:
> +Generate Default Tests
> +======================
> +
> +Generate the default test case files using the provided make target::
> +
> +  # make tests_install
> +
> +This creates the ``testcases_default_gen`` directory containing ``default.test``
> +files. Each KVM selftest has a directory with a ``default.test`` file. This file
> +contains the executable path relative to the KVM selftest root directory
> +(``/tools/testing/selftests/kvm``). For example, the ``dirty_log_perf_test``
> +entry looks like::
> +
> +  # cat testcases_default_gen/dirty_log_perf_test/default.test
> +  dirty_log_perf_test
> +
> +In above testcase, the runner executes ``dirty_log_perf_test``. Testcase files
> +can provide extra arguments to the test::
> +
> +  # cat tests/dirty_log_perf_test/2slot_5vcpu_10iter.test
> +  dirty_log_perf_test -x 2 -v 5 -i 10

This is obviously not about the default tests.

> +
> +In this case, the runner executes ``dirty_log_perf_test`` with the specified
> +options.
> +
> +Examples
> +========
> +
> +Display all options::
> +
> +  # python3 runner -h
> +
> +Run all default tests::
> +
> +  # python3 runner -d testcases_default_gen

s/testcases_default_gen/$(DEFAULT_TESTCASES), because the user (like me) might
change it.

Something like this, if we go testcases => install route?

Generate Default Tests
======================

Generate the default test case files using the provided make target::

  # make testcases

Create a ``$(INSTALL_PATH)/$(DEFAULT_TESTCASES)`` directory and a sub-directory
for each KVM selftest, and populate each selftest sub-directory with a
``default.test`` file, where ``default.test`` contains the unqualified
executable path.

For example, the ``dirty_log_perf_test`` entry looks like::

  # cat $(DEFAULT_TESTCASES)/dirty_log_perf_test/default.test
  dirty_log_perf_test

Note, the ``testcases`` target is dependent on the ``install`` target, i.e.
installing testcases will also run ``install``.

Testcase Syntax
===============

Testcase files can provide extra arguments to the test::

  # cat tests/dirty_log_perf_test/2slot_5vcpu_10iter.test
  dirty_log_perf_test -x 2 -v 5 -i 10

In this case, the runner executes ``dirty_log_perf_test`` with the specified
options. 

Examples 
========

Display all options::

  # python3 runner -h

Run all default tests::

  # python3 runner -d $(DEFAULT_TESTCASES)

Run tests in parallel::

  # python3 runner -d $(DEFAULT_TESTCASES) -j 40

Print only passed test status and failed test stderr::

  # python3 runner -d $(DEFAULT_TESTCASES) --print-passed status \
  --print-failed stderr

Run test binaries from a different directory (e.g., out-of-tree builds)::

  # python3 runner -d $(DEFAULT_TESTCASES) -p /path/to/binaries

Save all test outputs (stdout, stderr, status) to a directory::

  # python3 runner -d $(DEFAULT_TESTCASES) -o test_outputs

Run specific testcase files::

  # python3 runner -t tests/dirty_log_perf_test/2slot_5vcpu_10iter.test

> +
> +Run tests in parallel::
> +
> +  # python3 runner -d testcases_default_gen -j 40
> +
> +Print only passed test status and failed test stderr::
> +
> +  # python3 runner -d testcases_default_gen --print-passed status \
> +  --print-failed stderr
> +
> +Run test binaries from a different directory (e.g., out-of-tree builds)::
> +
> +  # python3 runner -d testcases_default_gen -p /path/to/binaries
> +
> +Save all test outputs (stdout, stderr, status) to a directory::
> +
> +  # python3 runner -d testcases_default_gen -o test_outputs
> +
> +Run specific testcase files::
> +
> +  # python3 runner -t tests/dirty_log_perf_test/2slot_5vcpu_10iter.test
> -- 
> 2.53.0.1118.gaef5881109-goog
>