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 qemu_params/extra_params modify how a 28test is run, while others like arch and accel restrict the configurations 29in which the test 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 59test_args 60--------- 61test_args = "..." 62 63Optional, will be used to pass arguments into the test case argv. If multiple, 64space separated, arguments need to be passed to a test, wrap them in quotes. 65Backticks can be used to pass the result of shell commands, for example: 66 67test_args = "10000000 `date +%s`" 68 69qemu_params 70------------ 71These are extra parameters supplied to the QEMU process. Multiple parameters 72can be added, for example: 73 74qemu_params = -m 256 -machine pit=off 75 76extra_params 77------------ 78Alias for 'qemu_params', supported for compatibility purposes. Use 79'qemu_params' for new tests. 80 81kvmtool_params 82-------------- 83Extra parameters supplied to the kvmtool process. Works similarly to 84'qemu_params', but uses kvmtool's syntax for command line arguments. The 85example for 'qemu_params', applied to kvmtool, would be: 86 87kvmtool_params = --mem 256 88 89groups 90------ 91groups = <group_name1> <group_name2> ... 92 93Used to group the test cases for the `run_tests.sh -g ...` run group 94option. The group name is arbitrary, except for these special groups: 95- Tests in the "nodefault" group are not run by default (with no -g option). 96- Tests in the "migration" group are run with the migration harness and 97 are expected to make migrate_*() calls. 98- Tests in the "panic" group expect QEMU to enter the GUEST_PANICKED state. 99 100accel 101----- 102accel = kvm|tcg 103 104This restricts the test to the specified accelerator. By default, the 105test will run on either accelerator. (Note, the accelerator can be 106specified with ACCEL= environment variable, and defaults to KVM if 107available). 108 109timeout 110------- 111timeout = <duration> 112 113Optional timeout in seconds, after which the test will be killed and fail. Can 114be overwritten with the TIMEOUT=<duration> environment variable. 115 116check 117----- 118check = <path>=<value> 119 120Check a file for a particular value before running a test. The check line 121can contain multiple files to check separated by a space, but each check 122parameter needs to be of the form <path>=<value> 123 124The path and value cannot contain space, =, or shell wildcard characters. 125 126Can be overwritten with the CHECK environment variable with the same syntax. 127 128disabled_if 129----------- 130disabled_if = <condition> 131 132Do not run the test if <condition> is met. <condition> will be fed unmodified 133to a bash 'if' statement and follows the same syntax. 134 135This can be used to prevent running a test when kvm-unit-tests is configured a 136certain way. For example, it can be used to skip a qemu specific test when 137using another VMM and using UEFI: 138 139disabled_if = [[ "$TARGET" != qemu ]] && [[ "$CONFIG_EFI" = y ]] 140