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

svn path=/nixos/trunk/; revision=26211

doc/manual/development.xml

@@ -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>