doc: Add a section on VM testing, mostly copied from the wiki.

svn path=/nixos/trunk/; revision=26211
This commit is contained in:
Ludovic Courtès 2011-03-08 20:55:43 +00:00
parent f1277862cd
commit 79a322f050

View file

@ -341,5 +341,109 @@ $ qemu-system-x86_64 -kernel ./kernel/bzImage -initrd ./initrd/initrd -hda /dev/
</section>
<section>
<title>Whole-system testing using virtual machines</title>
<para>
Complete NixOS GNU/Linux systems can be tested in virtual machines
(VMs). This makes it possible to test a system upgrade or
configuration change before rebooting into it, using the
<command>nixos-rebuild build-vm</command> or
<command>nixos-rebuild build-vm-with-bootloader</command> command.
</para>
<para>
<!-- The following is adapted from
http://wiki.nixos.org/wiki/NixOS_VM_tests, by Eelco Dolstra. -->
The <filename>tests/</filename> directory in the NixOS source tree
contains several <emphasis>whole-system unit tests</emphasis>.
These tests can be run<note><para>NixOS tests can be run both from
NixOS and from a non-NixOS GNU/Linux distribution, provided the
Nix package manager is installed.</para></note> from the NixOS
source tree as follows:
<screen>
$ nix-build tests/ -A nfs.test
</screen>
This performs an automated test of the NFS client and server
functionality in the Linux kernel, including file locking
semantics (e.g., whether locks are maintained across server
crashes). It will first build or download all the dependencies of
the test (e.g., all packages needed to run a NixOS VM). The test
is defined in <link
xlink:href="https://svn.nixos.org/repos/nix/nixos/trunk/tests/nfs.nix">
<filename>tests/nfs.nix</filename></link>. If the test succeeds,
<command>nix-build</command> will place a symlink
<filename>./result</filename> in the current directory pointing at
the location in the Nix store of the test results (e.g.,
screenshots, test reports, and so on). In particular, a
pretty-printed log of the test is written to
<filename>log.html</filename>, which can be viewed using something
like:
<screen>
$ icecat result/log.html
</screen>
</para>
<para>
It is also possible to run the test environment interactively,
allowing you to experiment with the VMs. For example:
<screen>
$ nix-build tests/ -A nfs.driver
$ ./result/bin/nixos-run-vms
</screen>
The script <command>nixos-run-vms</command> starts the three
virtual machines defined in the NFS test using QEMU/KVM. The root
file system of the VMs is created on the fly and kept across VM
restarts in
<filename>./<varname>hostname</varname>.qcow2</filename>.
</para>
<para>
Finally, the test itself can be run interactively. This is
particularly useful when developing or debugging a test:
<screen>
$ nix-build tests/ -A nfs.driver
$ ./result/bin/nixos-test-driver
starting VDE switch for network 1
>
</screen>
Perl statements can now be typed in to start or manipulate the
VMs:
<screen>
> startAll;
(the VMs start booting)
> $server->waitForJob("nfs-kernel-nfsd");
> $client1->succeed("flock -x /data/lock -c 'sleep 100000' &");
> $client2->fail("flock -n -s /data/lock true");
> $client1->shutdown;
(this releases client1's lock)
> $client2->succeed("flock -n -s /data/lock true");
</screen>
The function <command>testScript</command> executes the entire
test script and drops you back into the test driver command line
upon its completion. This allows you to inspect the state of the
VMs after the test (e.g. to debug the test script).
</para>
<para>
This and other tests are continuously run on <link
xlink:href="http://hydra.nixos.org/jobset/nixos/trunk/with-status">the
Hydra instance at <literal>nixos.org</literal></link>, which
allows developers to be notified of any regressions introduced by
a NixOS or Nixpkgs change.
</para>
</section>
</chapter>