From 7fe48226c0d8af045a9f70d533ef115d9ba1aecf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ludovic=20Court=C3=A8s?= <ludo@gnu.org>
Date: Wed, 15 Jun 2011 14:12:45 +0000
Subject: [PATCH] doc: Add more details on `lib/testing.nix'.

svn path=/nixos/trunk/; revision=27474
---
 doc/manual/development.xml | 46 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/doc/manual/development.xml b/doc/manual/development.xml
index 3887904a92e8..c8001a5c6d75 100644
--- a/doc/manual/development.xml
+++ b/doc/manual/development.xml
@@ -480,6 +480,52 @@ $ qemu-system-x86_64 -kernel ./kernel/bzImage -initrd ./initrd/initrd -hda /dev/
     a NixOS or Nixpkgs change.
   </para>
 
+  <para>
+    The actual Nix programming interface to VM testing is in NixOS,
+    under <link
+    xlink:href="https://svn.nixos.org/repos/nix/nixos/trunk/lib/testing.nix">
+    <filename>lib/testing.nix</filename></link>.  This file defines a
+    function which takes an attribute set containing a
+    <literal>nixpkgs</literal> attribute (the path to a Nixpkgs
+    checkout), and a <literal>system</literal> attribute (the system
+    type).  It returns an attribute set containing several utility
+    functions, among which the main entry point is
+    <literal>makeTest</literal>.
+  </para>
+
+  <para>
+    The <literal>makeTest</literal> function takes a function similar to
+    that found in <link
+    xlink:href="https://svn.nixos.org/repos/nix/nixos/trunk/tests/nfs.nix">
+    <filename>tests/nfs.nix</filename></link> (discussed above).  It
+    returns an attribute set containing (among others):
+
+    <variablelist>
+
+      <varlistentry>
+	<term><varname>test</varname></term>
+	<listitem>A derivation containing the test log as an HTML file,
+	as seen above, suitable for presentation in the Hydra continuous
+	build system.</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term><varname>report</varname></term>
+	<listitem>A derivation containing a code coverage report, with
+	meta-data suitable for Hydra.</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term><varname>driver</varname></term>
+	<listitem>A derivation containing scripts to run the VM test or
+	interact with the VM network interactively, as seen above.
+	</listitem>
+      </varlistentry>
+
+    </variablelist>
+  </para>
+    
+
 </section>
 
 </chapter>