docs: Add docs/devel/testing.rst

To make our efforts on QEMU testing easier to consume by contributors,
let's add a document. For example, Patchew reports build errors on
patches that should be relatively easy to reproduce with a few steps, and
it is much nicer if there is such a documentation that it can refer to.

This focuses on how to run existing tests and how to write new test
cases, without going into the frameworks themselves.

The VM based testing section is moved from tests/vm/README which now
is a single line pointing to the new doc.

Signed-off-by: Fam Zheng <famz@redhat.com>
Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>
Message-Id: <20180201022046.9425-1-famz@redhat.com>
Signed-off-by: Fam Zheng <famz@redhat.com>

1 files changed, 1 insertions, 89 deletions

diff --git a/tests/vm/README b/tests/vm/README
index ae53dce6ee..f9c04cc0e7 100644
--- a/tests/vm/README
+++ b/tests/vm/README
@@ -1,89 +1 @@
-=== VM test suite to run build in guests ===
-
-== Intro ==
-
-This test suite contains scripts that bootstrap various guest images that have
-necessary packages to build QEMU. The basic usage is documented in Makefile
-help which is displayed with "make vm-test".
-
-== Quick start ==
-
-Run "make vm-test" to list available make targets. Invoke a specific make
-command to run build test in an image. For example, "make vm-build-freebsd"
-will build the source tree in the FreeBSD image. The command can be executed
-from either the source tree or the build dir; if the former, ./configure is not
-needed. The command will then generate the test image in ./tests/vm/ under the
-working directory.
-
-Note: images created by the scripts accept a well-known RSA key pair for SSH
-access, so they SHOULD NOT be exposed to external interfaces if you are
-concerned about attackers taking control of the guest and potentially
-exploiting a QEMU security bug to compromise the host.
-
-== QEMU binary ==
-
-By default, qemu-system-x86_64 is searched in $PATH to run the guest. If there
-isn't one, or if it is older than 2.10, the test won't work. In this case,
-provide the QEMU binary in env var: QEMU=/path/to/qemu-2.10+.
-
-== Make jobs ==
-
-The "-j$X" option in the make command line is not propagated into the VM,
-specify "J=$X" to control the make jobs in the guest.
-
-== Debugging ==
-
-Add "DEBUG=1" and/or "V=1" to the make command to allow interactive debugging
-and verbose output. If this is not enough, see the next section.
-
-== Manual invocation ==
-
-Each guest script is an executable script with the same command line options.
-For example to work with the netbsd guest, use $QEMU_SRC/tests/vm/netbsd:
-
-    $ cd $QEMU_SRC/tests/vm
-
-    # To bootstrap the image
-    $ ./netbsd --build-image --image /var/tmp/netbsd.img
-    <...>
-
-    # To run an arbitrary command in guest (the output will not be echoed unless
-    # --debug is added)
-    $ ./netbsd --debug --image /var/tmp/netbsd.img uname -a
-
-    # To build QEMU in guest
-    $ ./netbsd --debug --image /var/tmp/netbsd.img --build-qemu $QEMU_SRC
-
-    # To get to an interactive shell
-    $ ./netbsd --interactive --image /var/tmp/netbsd.img sh
-
-== Adding new guests ==
-
-Please look at existing guest scripts for how to add new guests.
-
-Most importantly, create a subclass of BaseVM and implement build_image()
-method and define BUILD_SCRIPT, then finally call basevm.main() from the
-script's main().
-
-  - Usually in build_image(), a template image is downloaded from a predefined
-    URL. BaseVM._download_with_cache() takes care of the cache and the
-    checksum, so consider using it.
-
-  - Once the image is downloaded, users, SSH server and QEMU build deps should
-    be set up:
-
-    * Root password set to BaseVM.ROOT_PASS
-    * User BaseVM.GUEST_USER is created, and password set to BaseVM.GUEST_PASS
-    * SSH service is enabled and started on boot,
-      $QEMU_SRC/tests/keys/id_rsa.pub is added to ssh's "authorized_keys" file
-      of both root and the normal user
-    * DHCP client service is enabled and started on boot, so that it can
-      automatically configure the virtio-net-pci NIC and communicate with QEMU
-      user net (10.0.2.2)
-    * Necessary packages are installed to untar the source tarball and build
-      QEMU
-
-  - Write a proper BUILD_SCRIPT template, which should be a shell script that
-    untars a raw virtio-blk block device, which is the tarball data blob of the
-    QEMU source tree, then configure/build it. Running "make check" is also
-    recommended.
+See docs/devel/testing.rst for help.