unittests
*********

run_tests.sh is driven by the <arch>/unittests.cfg file. That file defines
test cases by specifying an executable (target image) under the <arch>/
directory, and how to run it. This way, for example, a single file can
provide multiple test cases by being run with different host configurations
and/or different parameters passed to it.

Detailed output from run_tests.sh unit tests are stored in files under
the logs/ directory.

unittests.cfg format
====================

# is the comment symbol, all following contents of the line is ignored.

Each unit test is defined with a [unit-test-name] line, followed by
a set of parameters that control how the test case is run. The name is
arbitrary and appears in the status reporting output.

Parameters appear on their own lines under the test name, and have a
param = value format.

Available parameters
====================
Note! Some parameters like smp and qemu_params/extra_params modify how a
test is run, while others like arch and accel restrict the configurations
in which the test is run.

file
----
file = <filename>

This parameter is mandatory and specifies which binary under the <arch>/
directory to run. Typically this is <name>.flat or <name>.elf, depending
on the arch. The directory name is not included, only the file name.

arch
----
For <arch>/ directories that support multiple architectures, this restricts
the test to the specified arch. By default, the test will run on any
architecture.

machine
-------
For those architectures that support multiple machine types, this restricts
the test to the specified machine. By default, the test will run on
any machine type. (Note, the machine can be specified with the MACHINE=
environment variable, and defaults to the architecture's default.)

smp
---
smp = <number>

Optional, the number of processors created in the machine to run the test.
Defaults to 1. $MAX_SMP can be used to specify the maximum supported.

test_args
---------
test_args = "..."

Optional, will be used to pass arguments into the test case argv. If multiple,
space separated, arguments need to be passed to a test, wrap them in quotes.
Backticks can be used to pass the result of shell commands, for example:

test_args = "10000000 `date +%s`"

qemu_params
------------
These are extra parameters supplied to the QEMU process. Multiple parameters
can be added, for example:

qemu_params = -m 256 -machine pit=off

extra_params
------------
Alias for 'qemu_params', supported for compatibility purposes. Use
'qemu_params' for new tests.

kvmtool_params
--------------
Extra parameters supplied to the kvmtool process. Works similarly to
'qemu_params', but uses kvmtool's syntax for command line arguments. The
example for 'qemu_params', applied to kvmtool, would be:

kvmtool_params = --mem 256

groups
------
groups = <group_name1> <group_name2> ...

Used to group the test cases for the `run_tests.sh -g ...` run group
option. The group name is arbitrary, except for these special groups:
- Tests in the "nodefault" group are not run by default (with no -g option).
- Tests in the "migration" group are run with the migration harness and
  are expected to make migrate_*() calls.
- Tests in the "panic" group expect QEMU to enter the GUEST_PANICKED state.

accel
-----
accel = kvm|tcg

This restricts the test to the specified accelerator. By default, the
test will run on either accelerator. (Note, the accelerator can be
specified with ACCEL= environment variable, and defaults to KVM if
available).

timeout
-------
timeout = <duration>

Optional timeout in seconds, after which the test will be killed and fail. Can
be overwritten with the TIMEOUT=<duration> environment variable.

check
-----
check = <path>=<value>

Check a file for a particular value before running a test. The check line
can contain multiple files to check separated by a space, but each check
parameter needs to be of the form <path>=<value>

The path and value cannot contain space, =, or shell wildcard characters.

Can be overwritten with the CHECK environment variable with the same syntax.

disabled_if
-----------
disabled_if = <condition>

Do not run the test if <condition> is met. <condition> will be fed unmodified
to a bash 'if' statement and follows the same syntax.

This can be used to prevent running a test when kvm-unit-tests is configured a
certain way. For example, it can be used to skip a qemu specific test when
using another VMM and using UEFI:

disabled_if = [[ "$TARGET" != qemu ]] && [[ "$CONFIG_EFI" = y ]]
