spice: move auth functions to QemuSpiceOps.
[qemu.git] / docs / devel / testing.rst
1 ===============
2 Testing in QEMU
3 ===============
4
5 This document describes the testing infrastructure in QEMU.
6
7 Testing with "make check"
8 =========================
9
10 The "make check" testing family includes most of the C based tests in QEMU. For
11 a quick help, run ``make check-help`` from the source tree.
12
13 The usual way to run these tests is:
14
15 .. code::
16
17   make check
18
19 which includes QAPI schema tests, unit tests, QTests and some iotests.
20 Different sub-types of "make check" tests will be explained below.
21
22 Before running tests, it is best to build QEMU programs first. Some tests
23 expect the executables to exist and will fail with obscure messages if they
24 cannot find them.
25
26 Unit tests
27 ----------
28
29 Unit tests, which can be invoked with ``make check-unit``, are simple C tests
30 that typically link to individual QEMU object files and exercise them by
31 calling exported functions.
32
33 If you are writing new code in QEMU, consider adding a unit test, especially
34 for utility modules that are relatively stateless or have few dependencies. To
35 add a new unit test:
36
37 1. Create a new source file. For example, ``tests/foo-test.c``.
38
39 2. Write the test. Normally you would include the header file which exports
40    the module API, then verify the interface behaves as expected from your
41    test. The test code should be organized with the glib testing framework.
42    Copying and modifying an existing test is usually a good idea.
43
44 3. Add the test to ``tests/meson.build``. The unit tests are listed in a
45    dictionary called ``tests``.  The values are any additional sources and
46    dependencies to be linked with the test.  For a simple test whose source
47    is in ``tests/foo-test.c``, it is enough to add an entry like::
48
49      {
50        ...
51        'foo-test': [],
52        ...
53      }
54
55 Since unit tests don't require environment variables, the simplest way to debug
56 a unit test failure is often directly invoking it or even running it under
57 ``gdb``. However there can still be differences in behavior between ``make``
58 invocations and your manual run, due to ``$MALLOC_PERTURB_`` environment
59 variable (which affects memory reclamation and catches invalid pointers better)
60 and gtester options. If necessary, you can run
61
62 .. code::
63
64   make check-unit V=1
65
66 and copy the actual command line which executes the unit test, then run
67 it from the command line.
68
69 QTest
70 -----
71
72 QTest is a device emulation testing framework.  It can be very useful to test
73 device models; it could also control certain aspects of QEMU (such as virtual
74 clock stepping), with a special purpose "qtest" protocol.  Refer to
75 :doc:`qtest` for more details.
76
77 QTest cases can be executed with
78
79 .. code::
80
81    make check-qtest
82
83 QAPI schema tests
84 -----------------
85
86 The QAPI schema tests validate the QAPI parser used by QMP, by feeding
87 predefined input to the parser and comparing the result with the reference
88 output.
89
90 The input/output data is managed under the ``tests/qapi-schema`` directory.
91 Each test case includes four files that have a common base name:
92
93   * ``${casename}.json`` - the file contains the JSON input for feeding the
94     parser
95   * ``${casename}.out`` - the file contains the expected stdout from the parser
96   * ``${casename}.err`` - the file contains the expected stderr from the parser
97   * ``${casename}.exit`` - the expected error code
98
99 Consider adding a new QAPI schema test when you are making a change on the QAPI
100 parser (either fixing a bug or extending/modifying the syntax). To do this:
101
102 1. Add four files for the new case as explained above. For example:
103
104   ``$EDITOR tests/qapi-schema/foo.{json,out,err,exit}``.
105
106 2. Add the new test in ``tests/Makefile.include``. For example:
107
108   ``qapi-schema += foo.json``
109
110 check-block
111 -----------
112
113 ``make check-block`` runs a subset of the block layer iotests (the tests that
114 are in the "auto" group in ``tests/qemu-iotests/group``).
115 See the "QEMU iotests" section below for more information.
116
117 GCC gcov support
118 ----------------
119
120 ``gcov`` is a GCC tool to analyze the testing coverage by
121 instrumenting the tested code. To use it, configure QEMU with
122 ``--enable-gcov`` option and build. Then run ``make check`` as usual.
123
124 If you want to gather coverage information on a single test the ``make
125 clean-gcda`` target can be used to delete any existing coverage
126 information before running a single test.
127
128 You can generate a HTML coverage report by executing ``make
129 coverage-html`` which will create
130 ``meson-logs/coveragereport/index.html``.
131
132 Further analysis can be conducted by running the ``gcov`` command
133 directly on the various .gcda output files. Please read the ``gcov``
134 documentation for more information.
135
136 QEMU iotests
137 ============
138
139 QEMU iotests, under the directory ``tests/qemu-iotests``, is the testing
140 framework widely used to test block layer related features. It is higher level
141 than "make check" tests and 99% of the code is written in bash or Python
142 scripts.  The testing success criteria is golden output comparison, and the
143 test files are named with numbers.
144
145 To run iotests, make sure QEMU is built successfully, then switch to the
146 ``tests/qemu-iotests`` directory under the build directory, and run ``./check``
147 with desired arguments from there.
148
149 By default, "raw" format and "file" protocol is used; all tests will be
150 executed, except the unsupported ones. You can override the format and protocol
151 with arguments:
152
153 .. code::
154
155   # test with qcow2 format
156   ./check -qcow2
157   # or test a different protocol
158   ./check -nbd
159
160 It's also possible to list test numbers explicitly:
161
162 .. code::
163
164   # run selected cases with qcow2 format
165   ./check -qcow2 001 030 153
166
167 Cache mode can be selected with the "-c" option, which may help reveal bugs
168 that are specific to certain cache mode.
169
170 More options are supported by the ``./check`` script, run ``./check -h`` for
171 help.
172
173 Writing a new test case
174 -----------------------
175
176 Consider writing a tests case when you are making any changes to the block
177 layer. An iotest case is usually the choice for that. There are already many
178 test cases, so it is possible that extending one of them may achieve the goal
179 and save the boilerplate to create one.  (Unfortunately, there isn't a 100%
180 reliable way to find a related one out of hundreds of tests.  One approach is
181 using ``git grep``.)
182
183 Usually an iotest case consists of two files. One is an executable that
184 produces output to stdout and stderr, the other is the expected reference
185 output. They are given the same number in file names. E.g. Test script ``055``
186 and reference output ``055.out``.
187
188 In rare cases, when outputs differ between cache mode ``none`` and others, a
189 ``.out.nocache`` file is added. In other cases, when outputs differ between
190 image formats, more than one ``.out`` files are created ending with the
191 respective format names, e.g. ``178.out.qcow2`` and ``178.out.raw``.
192
193 There isn't a hard rule about how to write a test script, but a new test is
194 usually a (copy and) modification of an existing case.  There are a few
195 commonly used ways to create a test:
196
197 * A Bash script. It will make use of several environmental variables related
198   to the testing procedure, and could source a group of ``common.*`` libraries
199   for some common helper routines.
200
201 * A Python unittest script. Import ``iotests`` and create a subclass of
202   ``iotests.QMPTestCase``, then call ``iotests.main`` method. The downside of
203   this approach is that the output is too scarce, and the script is considered
204   harder to debug.
205
206 * A simple Python script without using unittest module. This could also import
207   ``iotests`` for launching QEMU and utilities etc, but it doesn't inherit
208   from ``iotests.QMPTestCase`` therefore doesn't use the Python unittest
209   execution. This is a combination of 1 and 2.
210
211 Pick the language per your preference since both Bash and Python have
212 comparable library support for invoking and interacting with QEMU programs. If
213 you opt for Python, it is strongly recommended to write Python 3 compatible
214 code.
215
216 Both Python and Bash frameworks in iotests provide helpers to manage test
217 images. They can be used to create and clean up images under the test
218 directory. If no I/O or any protocol specific feature is needed, it is often
219 more convenient to use the pseudo block driver, ``null-co://``, as the test
220 image, which doesn't require image creation or cleaning up. Avoid system-wide
221 devices or files whenever possible, such as ``/dev/null`` or ``/dev/zero``.
222 Otherwise, image locking implications have to be considered.  For example,
223 another application on the host may have locked the file, possibly leading to a
224 test failure.  If using such devices are explicitly desired, consider adding
225 ``locking=off`` option to disable image locking.
226
227 .. _docker-ref:
228
229 Docker based tests
230 ==================
231
232 Introduction
233 ------------
234
235 The Docker testing framework in QEMU utilizes public Docker images to build and
236 test QEMU in predefined and widely accessible Linux environments.  This makes
237 it possible to expand the test coverage across distros, toolchain flavors and
238 library versions.
239
240 Prerequisites
241 -------------
242
243 Install "docker" with the system package manager and start the Docker service
244 on your development machine, then make sure you have the privilege to run
245 Docker commands. Typically it means setting up passwordless ``sudo docker``
246 command or login as root. For example:
247
248 .. code::
249
250   $ sudo yum install docker
251   $ # or `apt-get install docker` for Ubuntu, etc.
252   $ sudo systemctl start docker
253   $ sudo docker ps
254
255 The last command should print an empty table, to verify the system is ready.
256
257 An alternative method to set up permissions is by adding the current user to
258 "docker" group and making the docker daemon socket file (by default
259 ``/var/run/docker.sock``) accessible to the group:
260
261 .. code::
262
263   $ sudo groupadd docker
264   $ sudo usermod $USER -a -G docker
265   $ sudo chown :docker /var/run/docker.sock
266
267 Note that any one of above configurations makes it possible for the user to
268 exploit the whole host with Docker bind mounting or other privileged
269 operations.  So only do it on development machines.
270
271 Quickstart
272 ----------
273
274 From source tree, type ``make docker`` to see the help. Testing can be started
275 without configuring or building QEMU (``configure`` and ``make`` are done in
276 the container, with parameters defined by the make target):
277
278 .. code::
279
280   make docker-test-build@min-glib
281
282 This will create a container instance using the ``min-glib`` image (the image
283 is downloaded and initialized automatically), in which the ``test-build`` job
284 is executed.
285
286 Images
287 ------
288
289 Along with many other images, the ``min-glib`` image is defined in a Dockerfile
290 in ``tests/docker/dockerfiles/``, called ``min-glib.docker``. ``make docker``
291 command will list all the available images.
292
293 To add a new image, simply create a new ``.docker`` file under the
294 ``tests/docker/dockerfiles/`` directory.
295
296 A ``.pre`` script can be added beside the ``.docker`` file, which will be
297 executed before building the image under the build context directory. This is
298 mainly used to do necessary host side setup. One such setup is ``binfmt_misc``,
299 for example, to make qemu-user powered cross build containers work.
300
301 Tests
302 -----
303
304 Different tests are added to cover various configurations to build and test
305 QEMU.  Docker tests are the executables under ``tests/docker`` named
306 ``test-*``. They are typically shell scripts and are built on top of a shell
307 library, ``tests/docker/common.rc``, which provides helpers to find the QEMU
308 source and build it.
309
310 The full list of tests is printed in the ``make docker`` help.
311
312 Tools
313 -----
314
315 There are executables that are created to run in a specific Docker environment.
316 This makes it easy to write scripts that have heavy or special dependencies,
317 but are still very easy to use.
318
319 Currently the only tool is ``travis``, which mimics the Travis-CI tests in a
320 container. It runs in the ``travis`` image:
321
322 .. code::
323
324   make docker-travis@travis
325
326 Debugging a Docker test failure
327 -------------------------------
328
329 When CI tasks, maintainers or yourself report a Docker test failure, follow the
330 below steps to debug it:
331
332 1. Locally reproduce the failure with the reported command line. E.g. run
333    ``make docker-test-mingw@fedora J=8``.
334 2. Add "V=1" to the command line, try again, to see the verbose output.
335 3. Further add "DEBUG=1" to the command line. This will pause in a shell prompt
336    in the container right before testing starts. You could either manually
337    build QEMU and run tests from there, or press Ctrl-D to let the Docker
338    testing continue.
339 4. If you press Ctrl-D, the same building and testing procedure will begin, and
340    will hopefully run into the error again. After that, you will be dropped to
341    the prompt for debug.
342
343 Options
344 -------
345
346 Various options can be used to affect how Docker tests are done. The full
347 list is in the ``make docker`` help text. The frequently used ones are:
348
349 * ``V=1``: the same as in top level ``make``. It will be propagated to the
350   container and enable verbose output.
351 * ``J=$N``: the number of parallel tasks in make commands in the container,
352   similar to the ``-j $N`` option in top level ``make``. (The ``-j`` option in
353   top level ``make`` will not be propagated into the container.)
354 * ``DEBUG=1``: enables debug. See the previous "Debugging a Docker test
355   failure" section.
356
357 Thread Sanitizer
358 ================
359
360 Thread Sanitizer (TSan) is a tool which can detect data races.  QEMU supports
361 building and testing with this tool.
362
363 For more information on TSan:
364
365 https://github.com/google/sanitizers/wiki/ThreadSanitizerCppManual
366
367 Thread Sanitizer in Docker
368 ---------------------------
369 TSan is currently supported in the ubuntu2004 docker.
370
371 The test-tsan test will build using TSan and then run make check.
372
373 .. code::
374
375   make docker-test-tsan@ubuntu2004
376
377 TSan warnings under docker are placed in files located at build/tsan/.
378
379 We recommend using DEBUG=1 to allow launching the test from inside the docker,
380 and to allow review of the warnings generated by TSan.
381
382 Building and Testing with TSan
383 ------------------------------
384
385 It is possible to build and test with TSan, with a few additional steps.
386 These steps are normally done automatically in the docker.
387
388 There is a one time patch needed in clang-9 or clang-10 at this time:
389
390 .. code::
391
392   sed -i 's/^const/static const/g' \
393       /usr/lib/llvm-10/lib/clang/10.0.0/include/sanitizer/tsan_interface.h
394
395 To configure the build for TSan:
396
397 .. code::
398
399   ../configure --enable-tsan --cc=clang-10 --cxx=clang++-10 \
400                --disable-werror --extra-cflags="-O0"
401
402 The runtime behavior of TSAN is controlled by the TSAN_OPTIONS environment
403 variable.
404
405 More information on the TSAN_OPTIONS can be found here:
406
407 https://github.com/google/sanitizers/wiki/ThreadSanitizerFlags
408
409 For example:
410
411 .. code::
412
413   export TSAN_OPTIONS=suppressions=<path to qemu>/tests/tsan/suppressions.tsan \
414                       detect_deadlocks=false history_size=7 exitcode=0 \
415                       log_path=<build path>/tsan/tsan_warning
416
417 The above exitcode=0 has TSan continue without error if any warnings are found.
418 This allows for running the test and then checking the warnings afterwards.
419 If you want TSan to stop and exit with error on warnings, use exitcode=66.
420
421 TSan Suppressions
422 -----------------
423 Keep in mind that for any data race warning, although there might be a data race
424 detected by TSan, there might be no actual bug here.  TSan provides several
425 different mechanisms for suppressing warnings.  In general it is recommended
426 to fix the code if possible to eliminate the data race rather than suppress
427 the warning.
428
429 A few important files for suppressing warnings are:
430
431 tests/tsan/suppressions.tsan - Has TSan warnings we wish to suppress at runtime.
432 The comment on each suppression will typically indicate why we are
433 suppressing it.  More information on the file format can be found here:
434
435 https://github.com/google/sanitizers/wiki/ThreadSanitizerSuppressions
436
437 tests/tsan/blacklist.tsan - Has TSan warnings we wish to disable
438 at compile time for test or debug.
439 Add flags to configure to enable:
440
441 "--extra-cflags=-fsanitize-blacklist=<src path>/tests/tsan/blacklist.tsan"
442
443 More information on the file format can be found here under "Blacklist Format":
444
445 https://github.com/google/sanitizers/wiki/ThreadSanitizerFlags
446
447 TSan Annotations
448 ----------------
449 include/qemu/tsan.h defines annotations.  See this file for more descriptions
450 of the annotations themselves.  Annotations can be used to suppress
451 TSan warnings or give TSan more information so that it can detect proper
452 relationships between accesses of data.
453
454 Annotation examples can be found here:
455
456 https://github.com/llvm/llvm-project/tree/master/compiler-rt/test/tsan/
457
458 Good files to start with are: annotate_happens_before.cpp and ignore_race.cpp
459
460 The full set of annotations can be found here:
461
462 https://github.com/llvm/llvm-project/blob/master/compiler-rt/lib/tsan/rtl/tsan_interface_ann.cpp
463
464 VM testing
465 ==========
466
467 This test suite contains scripts that bootstrap various guest images that have
468 necessary packages to build QEMU. The basic usage is documented in ``Makefile``
469 help which is displayed with ``make vm-help``.
470
471 Quickstart
472 ----------
473
474 Run ``make vm-help`` to list available make targets. Invoke a specific make
475 command to run build test in an image. For example, ``make vm-build-freebsd``
476 will build the source tree in the FreeBSD image. The command can be executed
477 from either the source tree or the build dir; if the former, ``./configure`` is
478 not needed. The command will then generate the test image in ``./tests/vm/``
479 under the working directory.
480
481 Note: images created by the scripts accept a well-known RSA key pair for SSH
482 access, so they SHOULD NOT be exposed to external interfaces if you are
483 concerned about attackers taking control of the guest and potentially
484 exploiting a QEMU security bug to compromise the host.
485
486 QEMU binaries
487 -------------
488
489 By default, qemu-system-x86_64 is searched in $PATH to run the guest. If there
490 isn't one, or if it is older than 2.10, the test won't work. In this case,
491 provide the QEMU binary in env var: ``QEMU=/path/to/qemu-2.10+``.
492
493 Likewise the path to qemu-img can be set in QEMU_IMG environment variable.
494
495 Make jobs
496 ---------
497
498 The ``-j$X`` option in the make command line is not propagated into the VM,
499 specify ``J=$X`` to control the make jobs in the guest.
500
501 Debugging
502 ---------
503
504 Add ``DEBUG=1`` and/or ``V=1`` to the make command to allow interactive
505 debugging and verbose output. If this is not enough, see the next section.
506 ``V=1`` will be propagated down into the make jobs in the guest.
507
508 Manual invocation
509 -----------------
510
511 Each guest script is an executable script with the same command line options.
512 For example to work with the netbsd guest, use ``$QEMU_SRC/tests/vm/netbsd``:
513
514 .. code::
515
516     $ cd $QEMU_SRC/tests/vm
517
518     # To bootstrap the image
519     $ ./netbsd --build-image --image /var/tmp/netbsd.img
520     <...>
521
522     # To run an arbitrary command in guest (the output will not be echoed unless
523     # --debug is added)
524     $ ./netbsd --debug --image /var/tmp/netbsd.img uname -a
525
526     # To build QEMU in guest
527     $ ./netbsd --debug --image /var/tmp/netbsd.img --build-qemu $QEMU_SRC
528
529     # To get to an interactive shell
530     $ ./netbsd --interactive --image /var/tmp/netbsd.img sh
531
532 Adding new guests
533 -----------------
534
535 Please look at existing guest scripts for how to add new guests.
536
537 Most importantly, create a subclass of BaseVM and implement ``build_image()``
538 method and define ``BUILD_SCRIPT``, then finally call ``basevm.main()`` from
539 the script's ``main()``.
540
541 * Usually in ``build_image()``, a template image is downloaded from a
542   predefined URL. ``BaseVM._download_with_cache()`` takes care of the cache and
543   the checksum, so consider using it.
544
545 * Once the image is downloaded, users, SSH server and QEMU build deps should
546   be set up:
547
548   - Root password set to ``BaseVM.ROOT_PASS``
549   - User ``BaseVM.GUEST_USER`` is created, and password set to
550     ``BaseVM.GUEST_PASS``
551   - SSH service is enabled and started on boot,
552     ``$QEMU_SRC/tests/keys/id_rsa.pub`` is added to ssh's ``authorized_keys``
553     file of both root and the normal user
554   - DHCP client service is enabled and started on boot, so that it can
555     automatically configure the virtio-net-pci NIC and communicate with QEMU
556     user net (10.0.2.2)
557   - Necessary packages are installed to untar the source tarball and build
558     QEMU
559
560 * Write a proper ``BUILD_SCRIPT`` template, which should be a shell script that
561   untars a raw virtio-blk block device, which is the tarball data blob of the
562   QEMU source tree, then configure/build it. Running "make check" is also
563   recommended.
564
565 Image fuzzer testing
566 ====================
567
568 An image fuzzer was added to exercise format drivers. Currently only qcow2 is
569 supported. To start the fuzzer, run
570
571 .. code::
572
573   tests/image-fuzzer/runner.py -c '[["qemu-img", "info", "$test_img"]]' /tmp/test qcow2
574
575 Alternatively, some command different from "qemu-img info" can be tested, by
576 changing the ``-c`` option.
577
578 Acceptance tests using the Avocado Framework
579 ============================================
580
581 The ``tests/acceptance`` directory hosts functional tests, also known
582 as acceptance level tests.  They're usually higher level tests, and
583 may interact with external resources and with various guest operating
584 systems.
585
586 These tests are written using the Avocado Testing Framework (which must
587 be installed separately) in conjunction with a the ``avocado_qemu.Test``
588 class, implemented at ``tests/acceptance/avocado_qemu``.
589
590 Tests based on ``avocado_qemu.Test`` can easily:
591
592  * Customize the command line arguments given to the convenience
593    ``self.vm`` attribute (a QEMUMachine instance)
594
595  * Interact with the QEMU monitor, send QMP commands and check
596    their results
597
598  * Interact with the guest OS, using the convenience console device
599    (which may be useful to assert the effectiveness and correctness of
600    command line arguments or QMP commands)
601
602  * Interact with external data files that accompany the test itself
603    (see ``self.get_data()``)
604
605  * Download (and cache) remote data files, such as firmware and kernel
606    images
607
608  * Have access to a library of guest OS images (by means of the
609    ``avocado.utils.vmimage`` library)
610
611  * Make use of various other test related utilities available at the
612    test class itself and at the utility library:
613
614    - http://avocado-framework.readthedocs.io/en/latest/api/test/avocado.html#avocado.Test
615    - http://avocado-framework.readthedocs.io/en/latest/api/utils/avocado.utils.html
616
617 Running tests
618 -------------
619
620 You can run the acceptance tests simply by executing:
621
622 .. code::
623
624   make check-acceptance
625
626 This involves the automatic creation of Python virtual environment
627 within the build tree (at ``tests/venv``) which will have all the
628 right dependencies, and will save tests results also within the
629 build tree (at ``tests/results``).
630
631 Note: the build environment must be using a Python 3 stack, and have
632 the ``venv`` and ``pip`` packages installed.  If necessary, make sure
633 ``configure`` is called with ``--python=`` and that those modules are
634 available.  On Debian and Ubuntu based systems, depending on the
635 specific version, they may be on packages named ``python3-venv`` and
636 ``python3-pip``.
637
638 The scripts installed inside the virtual environment may be used
639 without an "activation".  For instance, the Avocado test runner
640 may be invoked by running:
641
642  .. code::
643
644   tests/venv/bin/avocado run $OPTION1 $OPTION2 tests/acceptance/
645
646 Manual Installation
647 -------------------
648
649 To manually install Avocado and its dependencies, run:
650
651 .. code::
652
653   pip install --user avocado-framework
654
655 Alternatively, follow the instructions on this link:
656
657   http://avocado-framework.readthedocs.io/en/latest/GetStartedGuide.html#installing-avocado
658
659 Overview
660 --------
661
662 The ``tests/acceptance/avocado_qemu`` directory provides the
663 ``avocado_qemu`` Python module, containing the ``avocado_qemu.Test``
664 class.  Here's a simple usage example:
665
666 .. code::
667
668   from avocado_qemu import Test
669
670
671   class Version(Test):
672       """
673       :avocado: tags=quick
674       """
675       def test_qmp_human_info_version(self):
676           self.vm.launch()
677           res = self.vm.command('human-monitor-command',
678                                 command_line='info version')
679           self.assertRegexpMatches(res, r'^(\d+\.\d+\.\d)')
680
681 To execute your test, run:
682
683 .. code::
684
685   avocado run version.py
686
687 Tests may be classified according to a convention by using docstring
688 directives such as ``:avocado: tags=TAG1,TAG2``.  To run all tests
689 in the current directory, tagged as "quick", run:
690
691 .. code::
692
693   avocado run -t quick .
694
695 The ``avocado_qemu.Test`` base test class
696 -----------------------------------------
697
698 The ``avocado_qemu.Test`` class has a number of characteristics that
699 are worth being mentioned right away.
700
701 First of all, it attempts to give each test a ready to use QEMUMachine
702 instance, available at ``self.vm``.  Because many tests will tweak the
703 QEMU command line, launching the QEMUMachine (by using ``self.vm.launch()``)
704 is left to the test writer.
705
706 The base test class has also support for tests with more than one
707 QEMUMachine. The way to get machines is through the ``self.get_vm()``
708 method which will return a QEMUMachine instance. The ``self.get_vm()``
709 method accepts arguments that will be passed to the QEMUMachine creation
710 and also an optional `name` attribute so you can identify a specific
711 machine and get it more than once through the tests methods. A simple
712 and hypothetical example follows:
713
714 .. code::
715
716   from avocado_qemu import Test
717
718
719   class MultipleMachines(Test):
720       """
721       :avocado: enable
722       """
723       def test_multiple_machines(self):
724           first_machine = self.get_vm()
725           second_machine = self.get_vm()
726           self.get_vm(name='third_machine').launch()
727
728           first_machine.launch()
729           second_machine.launch()
730
731           first_res = first_machine.command(
732               'human-monitor-command',
733               command_line='info version')
734
735           second_res = second_machine.command(
736               'human-monitor-command',
737               command_line='info version')
738
739           third_res = self.get_vm(name='third_machine').command(
740               'human-monitor-command',
741               command_line='info version')
742
743           self.assertEquals(first_res, second_res, third_res)
744
745 At test "tear down", ``avocado_qemu.Test`` handles all the QEMUMachines
746 shutdown.
747
748 QEMUMachine
749 ~~~~~~~~~~~
750
751 The QEMUMachine API is already widely used in the Python iotests,
752 device-crash-test and other Python scripts.  It's a wrapper around the
753 execution of a QEMU binary, giving its users:
754
755  * the ability to set command line arguments to be given to the QEMU
756    binary
757
758  * a ready to use QMP connection and interface, which can be used to
759    send commands and inspect its results, as well as asynchronous
760    events
761
762  * convenience methods to set commonly used command line arguments in
763    a more succinct and intuitive way
764
765 QEMU binary selection
766 ~~~~~~~~~~~~~~~~~~~~~
767
768 The QEMU binary used for the ``self.vm`` QEMUMachine instance will
769 primarily depend on the value of the ``qemu_bin`` parameter.  If it's
770 not explicitly set, its default value will be the result of a dynamic
771 probe in the same source tree.  A suitable binary will be one that
772 targets the architecture matching host machine.
773
774 Based on this description, test writers will usually rely on one of
775 the following approaches:
776
777 1) Set ``qemu_bin``, and use the given binary
778
779 2) Do not set ``qemu_bin``, and use a QEMU binary named like
780    "qemu-system-${arch}", either in the current
781    working directory, or in the current source tree.
782
783 The resulting ``qemu_bin`` value will be preserved in the
784 ``avocado_qemu.Test`` as an attribute with the same name.
785
786 Attribute reference
787 -------------------
788
789 Besides the attributes and methods that are part of the base
790 ``avocado.Test`` class, the following attributes are available on any
791 ``avocado_qemu.Test`` instance.
792
793 vm
794 ~~
795
796 A QEMUMachine instance, initially configured according to the given
797 ``qemu_bin`` parameter.
798
799 arch
800 ~~~~
801
802 The architecture can be used on different levels of the stack, e.g. by
803 the framework or by the test itself.  At the framework level, it will
804 currently influence the selection of a QEMU binary (when one is not
805 explicitly given).
806
807 Tests are also free to use this attribute value, for their own needs.
808 A test may, for instance, use the same value when selecting the
809 architecture of a kernel or disk image to boot a VM with.
810
811 The ``arch`` attribute will be set to the test parameter of the same
812 name.  If one is not given explicitly, it will either be set to
813 ``None``, or, if the test is tagged with one (and only one)
814 ``:avocado: tags=arch:VALUE`` tag, it will be set to ``VALUE``.
815
816 machine
817 ~~~~~~~
818
819 The machine type that will be set to all QEMUMachine instances created
820 by the test.
821
822 The ``machine`` attribute will be set to the test parameter of the same
823 name.  If one is not given explicitly, it will either be set to
824 ``None``, or, if the test is tagged with one (and only one)
825 ``:avocado: tags=machine:VALUE`` tag, it will be set to ``VALUE``.
826
827 qemu_bin
828 ~~~~~~~~
829
830 The preserved value of the ``qemu_bin`` parameter or the result of the
831 dynamic probe for a QEMU binary in the current working directory or
832 source tree.
833
834 Parameter reference
835 -------------------
836
837 To understand how Avocado parameters are accessed by tests, and how
838 they can be passed to tests, please refer to::
839
840   http://avocado-framework.readthedocs.io/en/latest/WritingTests.html#accessing-test-parameters
841
842 Parameter values can be easily seen in the log files, and will look
843 like the following:
844
845 .. code::
846
847   PARAMS (key=qemu_bin, path=*, default=./qemu-system-x86_64) => './qemu-system-x86_64
848
849 arch
850 ~~~~
851
852 The architecture that will influence the selection of a QEMU binary
853 (when one is not explicitly given).
854
855 Tests are also free to use this parameter value, for their own needs.
856 A test may, for instance, use the same value when selecting the
857 architecture of a kernel or disk image to boot a VM with.
858
859 This parameter has a direct relation with the ``arch`` attribute.  If
860 not given, it will default to None.
861
862 machine
863 ~~~~~~~
864
865 The machine type that will be set to all QEMUMachine instances created
866 by the test.
867
868
869 qemu_bin
870 ~~~~~~~~
871
872 The exact QEMU binary to be used on QEMUMachine.
873
874 Uninstalling Avocado
875 --------------------
876
877 If you've followed the manual installation instructions above, you can
878 easily uninstall Avocado.  Start by listing the packages you have
879 installed::
880
881   pip list --user
882
883 And remove any package you want with::
884
885   pip uninstall <package_name>
886
887 If you've used ``make check-acceptance``, the Python virtual environment where
888 Avocado is installed will be cleaned up as part of ``make check-clean``.
889
890 Testing with "make check-tcg"
891 =============================
892
893 The check-tcg tests are intended for simple smoke tests of both
894 linux-user and softmmu TCG functionality. However to build test
895 programs for guest targets you need to have cross compilers available.
896 If your distribution supports cross compilers you can do something as
897 simple as::
898
899   apt install gcc-aarch64-linux-gnu
900
901 The configure script will automatically pick up their presence.
902 Sometimes compilers have slightly odd names so the availability of
903 them can be prompted by passing in the appropriate configure option
904 for the architecture in question, for example::
905
906   $(configure) --cross-cc-aarch64=aarch64-cc
907
908 There is also a ``--cross-cc-flags-ARCH`` flag in case additional
909 compiler flags are needed to build for a given target.
910
911 If you have the ability to run containers as the user you can also
912 take advantage of the build systems "Docker" support. It will then use
913 containers to build any test case for an enabled guest where there is
914 no system compiler available. See :ref:`docker-ref` for details.
915
916 Running subset of tests
917 -----------------------
918
919 You can build the tests for one architecture::
920
921   make build-tcg-tests-$TARGET
922
923 And run with::
924
925   make run-tcg-tests-$TARGET
926
927 Adding ``V=1`` to the invocation will show the details of how to
928 invoke QEMU for the test which is useful for debugging tests.
929
930 TCG test dependencies
931 ---------------------
932
933 The TCG tests are deliberately very light on dependencies and are
934 either totally bare with minimal gcc lib support (for softmmu tests)
935 or just glibc (for linux-user tests). This is because getting a cross
936 compiler to work with additional libraries can be challenging.
937
938 Other TCG Tests
939 ---------------
940
941 There are a number of out-of-tree test suites that are used for more
942 extensive testing of processor features.
943
944 KVM Unit Tests
945 ~~~~~~~~~~~~~~
946
947 The KVM unit tests are designed to run as a Guest OS under KVM but
948 there is no reason why they can't exercise the TCG as well. It
949 provides a minimal OS kernel with hooks for enabling the MMU as well
950 as reporting test results via a special device::
951
952   https://git.kernel.org/pub/scm/virt/kvm/kvm-unit-tests.git
953
954 Linux Test Project
955 ~~~~~~~~~~~~~~~~~~
956
957 The LTP is focused on exercising the syscall interface of a Linux
958 kernel. It checks that syscalls behave as documented and strives to
959 exercise as many corner cases as possible. It is a useful test suite
960 to run to exercise QEMU's linux-user code::
961
962   https://linux-test-project.github.io/