monitor: Fix tracepoint crash on JSON syntax error
[qemu/armbru.git] / docs / devel / testing.rst
blob5e19cd50da8d1291520795f50570258df3912eee
1 ===============
2 Testing in QEMU
3 ===============
5 This document describes the testing infrastructure in QEMU.
7 Testing with "make check"
8 =========================
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.
13 The usual way to run these tests is:
15 .. code::
17   make check
19 which includes QAPI schema tests, unit tests, and QTests. Different sub-types
20 of "make check" tests will be explained below.
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.
26 Unit tests
27 ----------
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.
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:
37 1. Create a new source file. For example, ``tests/foo-test.c``.
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.
44 3. Add the test to ``tests/Makefile.include``. First, name the unit test
45    program and add it to ``$(check-unit-y)``; then add a rule to build the
46    executable. Optionally, you can add a magical variable to support ``gcov``.
47    For example:
49 .. code::
51   check-unit-y += tests/foo-test$(EXESUF)
52   tests/foo-test$(EXESUF): tests/foo-test.o $(test-util-obj-y)
53   ...
54   gcov-files-foo-test-y = util/foo.c
56 Since unit tests don't require environment variables, the simplest way to debug
57 a unit test failure is often directly invoking it or even running it under
58 ``gdb``. However there can still be differences in behavior between ``make``
59 invocations and your manual run, due to ``$MALLOC_PERTURB_`` environment
60 variable (which affects memory reclamation and catches invalid pointers better)
61 and gtester options. If necessary, you can run
63 .. code::
64   make check-unit V=1
66 and copy the actual command line which executes the unit test, then run
67 it from the command line.
69 QTest
70 -----
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 the
75 documentation in ``qtest.c`` for more details of the protocol.
77 QTest cases can be executed with
79 .. code::
81    make check-qtest
83 The QTest library is implemented by ``tests/libqtest.c`` and the API is defined
84 in ``tests/libqtest.h``.
86 Consider adding a new QTest case when you are introducing a new virtual
87 hardware, or extending one if you are adding functionalities to an existing
88 virtual device.
90 On top of libqtest, a higher level library, ``libqos``, was created to
91 encapsulate common tasks of device drivers, such as memory management and
92 communicating with system buses or devices. Many virtual device tests use
93 libqos instead of directly calling into libqtest.
95 Steps to add a new QTest case are:
97 1. Create a new source file for the test. (More than one file can be added as
98    necessary.) For example, ``tests/test-foo-device.c``.
100 2. Write the test code with the glib and libqtest/libqos API. See also existing
101    tests and the library headers for reference.
103 3. Register the new test in ``tests/Makefile.include``. Add the test executable
104    name to an appropriate ``check-qtest-*-y`` variable. For example:
106    ``check-qtest-generic-y = tests/test-foo-device$(EXESUF)``
108 4. Add object dependencies of the executable in the Makefile, including the
109    test source file(s) and other interesting objects. For example:
111    ``tests/test-foo-device$(EXESUF): tests/test-foo-device.o $(libqos-obj-y)``
113 Debugging a QTest failure is slightly harder than the unit test because the
114 tests look up QEMU program names in the environment variables, such as
115 ``QTEST_QEMU_BINARY`` and ``QTEST_QEMU_IMG``, and also because it is not easy
116 to attach gdb to the QEMU process spawned from the test. But manual invoking
117 and using gdb on the test is still simple to do: find out the actual command
118 from the output of
120 .. code::
121   make check-qtest V=1
123 which you can run manually.
125 QAPI schema tests
126 -----------------
128 The QAPI schema tests validate the QAPI parser used by QMP, by feeding
129 predefined input to the parser and comparing the result with the reference
130 output.
132 The input/output data is managed under the ``tests/qapi-schema`` directory.
133 Each test case includes four files that have a common base name:
135   * ``${casename}.json`` - the file contains the JSON input for feeding the
136     parser
137   * ``${casename}.out`` - the file contains the expected stdout from the parser
138   * ``${casename}.err`` - the file contains the expected stderr from the parser
139   * ``${casename}.exit`` - the expected error code
141 Consider adding a new QAPI schema test when you are making a change on the QAPI
142 parser (either fixing a bug or extending/modifying the syntax). To do this:
144 1. Add four files for the new case as explained above. For example:
146   ``$EDITOR tests/qapi-schema/foo.{json,out,err,exit}``.
148 2. Add the new test in ``tests/Makefile.include``. For example:
150   ``qapi-schema += foo.json``
152 check-block
153 -----------
155 ``make check-block`` is a legacy command to invoke block layer iotests and is
156 rarely used. See "QEMU iotests" section below for more information.
158 GCC gcov support
159 ----------------
161 ``gcov`` is a GCC tool to analyze the testing coverage by
162 instrumenting the tested code. To use it, configure QEMU with
163 ``--enable-gcov`` option and build. Then run ``make check`` as usual.
165 If you want to gather coverage information on a single test the ``make
166 clean-coverage`` target can be used to delete any existing coverage
167 information before running a single test.
169 You can generate a HTML coverage report by executing ``make
170 coverage-report`` which will create
171 ./reports/coverage/coverage-report.html. If you want to create it
172 elsewhere simply execute ``make /foo/bar/baz/coverage-report.html``.
174 Further analysis can be conducted by running the ``gcov`` command
175 directly on the various .gcda output files. Please read the ``gcov``
176 documentation for more information.
178 QEMU iotests
179 ============
181 QEMU iotests, under the directory ``tests/qemu-iotests``, is the testing
182 framework widely used to test block layer related features. It is higher level
183 than "make check" tests and 99% of the code is written in bash or Python
184 scripts.  The testing success criteria is golden output comparison, and the
185 test files are named with numbers.
187 To run iotests, make sure QEMU is built successfully, then switch to the
188 ``tests/qemu-iotests`` directory under the build directory, and run ``./check``
189 with desired arguments from there.
191 By default, "raw" format and "file" protocol is used; all tests will be
192 executed, except the unsupported ones. You can override the format and protocol
193 with arguments:
195 .. code::
197   # test with qcow2 format
198   ./check -qcow2
199   # or test a different protocol
200   ./check -nbd
202 It's also possible to list test numbers explicitly:
204 .. code::
206   # run selected cases with qcow2 format
207   ./check -qcow2 001 030 153
209 Cache mode can be selected with the "-c" option, which may help reveal bugs
210 that are specific to certain cache mode.
212 More options are supported by the ``./check`` script, run ``./check -h`` for
213 help.
215 Writing a new test case
216 -----------------------
218 Consider writing a tests case when you are making any changes to the block
219 layer. An iotest case is usually the choice for that. There are already many
220 test cases, so it is possible that extending one of them may achieve the goal
221 and save the boilerplate to create one.  (Unfortunately, there isn't a 100%
222 reliable way to find a related one out of hundreds of tests.  One approach is
223 using ``git grep``.)
225 Usually an iotest case consists of two files. One is an executable that
226 produces output to stdout and stderr, the other is the expected reference
227 output. They are given the same number in file names. E.g. Test script ``055``
228 and reference output ``055.out``.
230 In rare cases, when outputs differ between cache mode ``none`` and others, a
231 ``.out.nocache`` file is added. In other cases, when outputs differ between
232 image formats, more than one ``.out`` files are created ending with the
233 respective format names, e.g. ``178.out.qcow2`` and ``178.out.raw``.
235 There isn't a hard rule about how to write a test script, but a new test is
236 usually a (copy and) modification of an existing case.  There are a few
237 commonly used ways to create a test:
239 * A Bash script. It will make use of several environmental variables related
240   to the testing procedure, and could source a group of ``common.*`` libraries
241   for some common helper routines.
243 * A Python unittest script. Import ``iotests`` and create a subclass of
244   ``iotests.QMPTestCase``, then call ``iotests.main`` method. The downside of
245   this approach is that the output is too scarce, and the script is considered
246   harder to debug.
248 * A simple Python script without using unittest module. This could also import
249   ``iotests`` for launching QEMU and utilities etc, but it doesn't inherit
250   from ``iotests.QMPTestCase`` therefore doesn't use the Python unittest
251   execution. This is a combination of 1 and 2.
253 Pick the language per your preference since both Bash and Python have
254 comparable library support for invoking and interacting with QEMU programs. If
255 you opt for Python, it is strongly recommended to write Python 3 compatible
256 code.
258 Docker based tests
259 ==================
261 Introduction
262 ------------
264 The Docker testing framework in QEMU utilizes public Docker images to build and
265 test QEMU in predefined and widely accessible Linux environments.  This makes
266 it possible to expand the test coverage across distros, toolchain flavors and
267 library versions.
269 Prerequisites
270 -------------
272 Install "docker" with the system package manager and start the Docker service
273 on your development machine, then make sure you have the privilege to run
274 Docker commands. Typically it means setting up passwordless ``sudo docker``
275 command or login as root. For example:
277 .. code::
279   $ sudo yum install docker
280   $ # or `apt-get install docker` for Ubuntu, etc.
281   $ sudo systemctl start docker
282   $ sudo docker ps
284 The last command should print an empty table, to verify the system is ready.
286 An alternative method to set up permissions is by adding the current user to
287 "docker" group and making the docker daemon socket file (by default
288 ``/var/run/docker.sock``) accessible to the group:
290 .. code::
292   $ sudo groupadd docker
293   $ sudo usermod $USER -G docker
294   $ sudo chown :docker /var/run/docker.sock
296 Note that any one of above configurations makes it possible for the user to
297 exploit the whole host with Docker bind mounting or other privileged
298 operations.  So only do it on development machines.
300 Quickstart
301 ----------
303 From source tree, type ``make docker`` to see the help. Testing can be started
304 without configuring or building QEMU (``configure`` and ``make`` are done in
305 the container, with parameters defined by the make target):
307 .. code::
309   make docker-test-build@min-glib
311 This will create a container instance using the ``min-glib`` image (the image
312 is downloaded and initialized automatically), in which the ``test-build`` job
313 is executed.
315 Images
316 ------
318 Along with many other images, the ``min-glib`` image is defined in a Dockerfile
319 in ``tests/docker/dockefiles/``, called ``min-glib.docker``. ``make docker``
320 command will list all the available images.
322 To add a new image, simply create a new ``.docker`` file under the
323 ``tests/docker/dockerfiles/`` directory.
325 A ``.pre`` script can be added beside the ``.docker`` file, which will be
326 executed before building the image under the build context directory. This is
327 mainly used to do necessary host side setup. One such setup is ``binfmt_misc``,
328 for example, to make qemu-user powered cross build containers work.
330 Tests
331 -----
333 Different tests are added to cover various configurations to build and test
334 QEMU.  Docker tests are the executables under ``tests/docker`` named
335 ``test-*``. They are typically shell scripts and are built on top of a shell
336 library, ``tests/docker/common.rc``, which provides helpers to find the QEMU
337 source and build it.
339 The full list of tests is printed in the ``make docker`` help.
341 Tools
342 -----
344 There are executables that are created to run in a specific Docker environment.
345 This makes it easy to write scripts that have heavy or special dependencies,
346 but are still very easy to use.
348 Currently the only tool is ``travis``, which mimics the Travis-CI tests in a
349 container. It runs in the ``travis`` image:
351 .. code::
353   make docker-travis@travis
355 Debugging a Docker test failure
356 -------------------------------
358 When CI tasks, maintainers or yourself report a Docker test failure, follow the
359 below steps to debug it:
361 1. Locally reproduce the failure with the reported command line. E.g. run
362    ``make docker-test-mingw@fedora J=8``.
363 2. Add "V=1" to the command line, try again, to see the verbose output.
364 3. Further add "DEBUG=1" to the command line. This will pause in a shell prompt
365    in the container right before testing starts. You could either manually
366    build QEMU and run tests from there, or press Ctrl-D to let the Docker
367    testing continue.
368 4. If you press Ctrl-D, the same building and testing procedure will begin, and
369    will hopefully run into the error again. After that, you will be dropped to
370    the prompt for debug.
372 Options
373 -------
375 Various options can be used to affect how Docker tests are done. The full
376 list is in the ``make docker`` help text. The frequently used ones are:
378 * ``V=1``: the same as in top level ``make``. It will be propagated to the
379   container and enable verbose output.
380 * ``J=$N``: the number of parallel tasks in make commands in the container,
381   similar to the ``-j $N`` option in top level ``make``. (The ``-j`` option in
382   top level ``make`` will not be propagated into the container.)
383 * ``DEBUG=1``: enables debug. See the previous "Debugging a Docker test
384   failure" section.
386 VM testing
387 ==========
389 This test suite contains scripts that bootstrap various guest images that have
390 necessary packages to build QEMU. The basic usage is documented in ``Makefile``
391 help which is displayed with ``make vm-test``.
393 Quickstart
394 ----------
396 Run ``make vm-test`` to list available make targets. Invoke a specific make
397 command to run build test in an image. For example, ``make vm-build-freebsd``
398 will build the source tree in the FreeBSD image. The command can be executed
399 from either the source tree or the build dir; if the former, ``./configure`` is
400 not needed. The command will then generate the test image in ``./tests/vm/``
401 under the working directory.
403 Note: images created by the scripts accept a well-known RSA key pair for SSH
404 access, so they SHOULD NOT be exposed to external interfaces if you are
405 concerned about attackers taking control of the guest and potentially
406 exploiting a QEMU security bug to compromise the host.
408 QEMU binary
409 -----------
411 By default, qemu-system-x86_64 is searched in $PATH to run the guest. If there
412 isn't one, or if it is older than 2.10, the test won't work. In this case,
413 provide the QEMU binary in env var: ``QEMU=/path/to/qemu-2.10+``.
415 Make jobs
416 ---------
418 The ``-j$X`` option in the make command line is not propagated into the VM,
419 specify ``J=$X`` to control the make jobs in the guest.
421 Debugging
422 ---------
424 Add ``DEBUG=1`` and/or ``V=1`` to the make command to allow interactive
425 debugging and verbose output. If this is not enough, see the next section.
427 Manual invocation
428 -----------------
430 Each guest script is an executable script with the same command line options.
431 For example to work with the netbsd guest, use ``$QEMU_SRC/tests/vm/netbsd``:
433 .. code::
435     $ cd $QEMU_SRC/tests/vm
437     # To bootstrap the image
438     $ ./netbsd --build-image --image /var/tmp/netbsd.img
439     <...>
441     # To run an arbitrary command in guest (the output will not be echoed unless
442     # --debug is added)
443     $ ./netbsd --debug --image /var/tmp/netbsd.img uname -a
445     # To build QEMU in guest
446     $ ./netbsd --debug --image /var/tmp/netbsd.img --build-qemu $QEMU_SRC
448     # To get to an interactive shell
449     $ ./netbsd --interactive --image /var/tmp/netbsd.img sh
451 Adding new guests
452 -----------------
454 Please look at existing guest scripts for how to add new guests.
456 Most importantly, create a subclass of BaseVM and implement ``build_image()``
457 method and define ``BUILD_SCRIPT``, then finally call ``basevm.main()`` from
458 the script's ``main()``.
460 * Usually in ``build_image()``, a template image is downloaded from a
461   predefined URL. ``BaseVM._download_with_cache()`` takes care of the cache and
462   the checksum, so consider using it.
464 * Once the image is downloaded, users, SSH server and QEMU build deps should
465   be set up:
467   - Root password set to ``BaseVM.ROOT_PASS``
468   - User ``BaseVM.GUEST_USER`` is created, and password set to
469     ``BaseVM.GUEST_PASS``
470   - SSH service is enabled and started on boot,
471     ``$QEMU_SRC/tests/keys/id_rsa.pub`` is added to ssh's ``authorized_keys``
472     file of both root and the normal user
473   - DHCP client service is enabled and started on boot, so that it can
474     automatically configure the virtio-net-pci NIC and communicate with QEMU
475     user net (10.0.2.2)
476   - Necessary packages are installed to untar the source tarball and build
477     QEMU
479 * Write a proper ``BUILD_SCRIPT`` template, which should be a shell script that
480   untars a raw virtio-blk block device, which is the tarball data blob of the
481   QEMU source tree, then configure/build it. Running "make check" is also
482   recommended.
484 Image fuzzer testing
485 ====================
487 An image fuzzer was added to exercise format drivers. Currently only qcow2 is
488 supported. To start the fuzzer, run
490 .. code::
492   tests/image-fuzzer/runner.py -c '[["qemu-img", "info", "$test_img"]]' /tmp/test qcow2
494 Alternatively, some command different from "qemu-img info" can be tested, by
495 changing the ``-c`` option.
497 Acceptance tests using the Avocado Framework
498 ============================================
500 The ``tests/acceptance`` directory hosts functional tests, also known
501 as acceptance level tests.  They're usually higher level tests, and
502 may interact with external resources and with various guest operating
503 systems.
505 These tests are written using the Avocado Testing Framework (which must
506 be installed separately) in conjunction with a the ``avocado_qemu.Test``
507 class, implemented at ``tests/acceptance/avocado_qemu``.
509 Tests based on ``avocado_qemu.Test`` can easily:
511  * Customize the command line arguments given to the convenience
512    ``self.vm`` attribute (a QEMUMachine instance)
514  * Interact with the QEMU monitor, send QMP commands and check
515    their results
517  * Interact with the guest OS, using the convenience console device
518    (which may be useful to assert the effectiveness and correctness of
519    command line arguments or QMP commands)
521  * Interact with external data files that accompany the test itself
522    (see ``self.get_data()``)
524  * Download (and cache) remote data files, such as firmware and kernel
525    images
527  * Have access to a library of guest OS images (by means of the
528    ``avocado.utils.vmimage`` library)
530  * Make use of various other test related utilities available at the
531    test class itself and at the utility library:
533    - http://avocado-framework.readthedocs.io/en/latest/api/test/avocado.html#avocado.Test
534    - http://avocado-framework.readthedocs.io/en/latest/api/utils/avocado.utils.html
536 Installation
537 ------------
539 To install Avocado and its dependencies, run:
541 .. code::
543   pip install --user avocado-framework
545 Alternatively, follow the instructions on this link:
547   http://avocado-framework.readthedocs.io/en/latest/GetStartedGuide.html#installing-avocado
549 Overview
550 --------
552 This directory provides the ``avocado_qemu`` Python module, containing
553 the ``avocado_qemu.Test`` class.  Here's a simple usage example:
555 .. code::
557   from avocado_qemu import Test
560   class Version(Test):
561       """
562       :avocado: enable
563       :avocado: tags=quick
564       """
565       def test_qmp_human_info_version(self):
566           self.vm.launch()
567           res = self.vm.command('human-monitor-command',
568                                 command_line='info version')
569           self.assertRegexpMatches(res, r'^(\d+\.\d+\.\d)')
571 To execute your test, run:
573 .. code::
575   avocado run version.py
577 Tests may be classified according to a convention by using docstring
578 directives such as ``:avocado: tags=TAG1,TAG2``.  To run all tests
579 in the current directory, tagged as "quick", run:
581 .. code::
583   avocado run -t quick .
585 The ``avocado_qemu.Test`` base test class
586 -----------------------------------------
588 The ``avocado_qemu.Test`` class has a number of characteristics that
589 are worth being mentioned right away.
591 First of all, it attempts to give each test a ready to use QEMUMachine
592 instance, available at ``self.vm``.  Because many tests will tweak the
593 QEMU command line, launching the QEMUMachine (by using ``self.vm.launch()``)
594 is left to the test writer.
596 At test "tear down", ``avocado_qemu.Test`` handles the QEMUMachine
597 shutdown.
599 QEMUMachine
600 ~~~~~~~~~~~
602 The QEMUMachine API is already widely used in the Python iotests,
603 device-crash-test and other Python scripts.  It's a wrapper around the
604 execution of a QEMU binary, giving its users:
606  * the ability to set command line arguments to be given to the QEMU
607    binary
609  * a ready to use QMP connection and interface, which can be used to
610    send commands and inspect its results, as well as asynchronous
611    events
613  * convenience methods to set commonly used command line arguments in
614    a more succinct and intuitive way
616 QEMU binary selection
617 ~~~~~~~~~~~~~~~~~~~~~
619 The QEMU binary used for the ``self.vm`` QEMUMachine instance will
620 primarily depend on the value of the ``qemu_bin`` parameter.  If it's
621 not explicitly set, its default value will be the result of a dynamic
622 probe in the same source tree.  A suitable binary will be one that
623 targets the architecture matching host machine.
625 Based on this description, test writers will usually rely on one of
626 the following approaches:
628 1) Set ``qemu_bin``, and use the given binary
630 2) Do not set ``qemu_bin``, and use a QEMU binary named like
631    "${arch}-softmmu/qemu-system-${arch}", either in the current
632    working directory, or in the current source tree.
634 The resulting ``qemu_bin`` value will be preserved in the
635 ``avocado_qemu.Test`` as an attribute with the same name.
637 Attribute reference
638 -------------------
640 Besides the attributes and methods that are part of the base
641 ``avocado.Test`` class, the following attributes are available on any
642 ``avocado_qemu.Test`` instance.
647 A QEMUMachine instance, initially configured according to the given
648 ``qemu_bin`` parameter.
650 qemu_bin
651 ~~~~~~~~
653 The preserved value of the ``qemu_bin`` parameter or the result of the
654 dynamic probe for a QEMU binary in the current working directory or
655 source tree.
657 Parameter reference
658 -------------------
660 To understand how Avocado parameters are accessed by tests, and how
661 they can be passed to tests, please refer to::
663   http://avocado-framework.readthedocs.io/en/latest/WritingTests.html#accessing-test-parameters
665 Parameter values can be easily seen in the log files, and will look
666 like the following:
668 .. code::
670   PARAMS (key=qemu_bin, path=*, default=x86_64-softmmu/qemu-system-x86_64) => 'x86_64-softmmu/qemu-system-x86_64
672 qemu_bin
673 ~~~~~~~~
675 The exact QEMU binary to be used on QEMUMachine.
677 Uninstalling Avocado
678 --------------------
680 If you've followed the installation instructions above, you can easily
681 uninstall Avocado.  Start by listing the packages you have installed::
683   pip list --user
685 And remove any package you want with::
687   pip uninstall <package_name>