xref: /kvm-unit-tests/docs/unittests.txt (revision 20665945290a0b2fb9a8cda75efbda612da9cf83)
1unittests
2*********
3
4run_tests.sh is driven by the <arch>/unittests.cfg file. That file defines
5test cases by specifying an executable (target image) under the <arch>/
6directory, and how to run it. This way, for example, a single file can
7provide multiple test cases by being run with different host configurations
8and/or different parameters passed to it.
9
10Detailed output from run_tests.sh unit tests are stored in files under
11the logs/ directory.
12
13unittests.cfg format
14====================
15
16# is the comment symbol, all following contents of the line is ignored.
17
18Each unit test is defined with a [unit-test-name] line, followed by
19a set of parameters that control how the test case is run. The name is
20arbitrary and appears in the status reporting output.
21
22Parameters appear on their own lines under the test name, and have a
23param = value format.
24
25Available parameters
26====================
27Note! Some parameters like smp and extra_params modify how a test is run,
28while others like arch and accel restrict the configurations in which the
29test is run.
30
31file
32----
33file = <filename>
34
35This parameter is mandatory and specifies which binary under the <arch>/
36directory to run. Typically this is <name>.flat or <name>.elf, depending
37on the arch. The directory name is not included, only the file name.
38
39arch
40----
41For <arch>/ directories that support multiple architectures, this restricts
42the test to the specified arch. By default, the test will run on any
43architecture.
44
45machine
46-------
47For those architectures that support multiple machine types, this restricts
48the test to the specified machine. By default, the test will run on
49any machine type. (Note, the machine can be specified with the MACHINE=
50environment variable, and defaults to the architecture's default.)
51
52smp
53---
54smp = <number>
55
56Optional, the number of processors created in the machine to run the test.
57Defaults to 1. $MAX_SMP can be used to specify the maximum supported.
58
59extra_params
60------------
61These are extra parameters supplied to the QEMU process. -append '...' can
62be used to pass arguments into the test case argv. Multiple parameters can
63be added, for example:
64
65extra_params = -m 256 -append 'smp=2'
66
67groups
68------
69groups = <group_name1> <group_name2> ...
70
71Used to group the test cases for the `run_tests.sh -g ...` run group
72option. The group name is arbitrary, except for these special groups:
73- Tests in the "nodefault" group are not run by default (with no -g option).
74- Tests in the "migration" group are run with the migration harness and
75  are expected to make migrate_*() calls.
76- Tests in the "panic" group expect QEMU to enter the GUEST_PANICKED state.
77
78accel
79-----
80accel = kvm|tcg
81
82This restricts the test to the specified accelerator. By default, the
83test will run on either accelerator. (Note, the accelerator can be
84specified with ACCEL= environment variable, and defaults to KVM if
85available).
86
87timeout
88-------
89timeout = <duration>
90
91Optional timeout in seconds, after which the test will be killed and fail.
92
93check
94-----
95check = <path>=<value>
96
97Check a file for a particular value before running a test. The check line
98can contain multiple files to check separated by a space, but each check
99parameter needs to be of the form <path>=<value>
100
101The path and value cannot contain space, =, or shell wildcard characters.
102