diff options
Diffstat (limited to 'nixos/doc/manual/development/running-nixos-tests.xml')
| -rw-r--r-- | nixos/doc/manual/development/running-nixos-tests.xml | 77 |
1 files changed, 77 insertions, 0 deletions
diff --git a/nixos/doc/manual/development/running-nixos-tests.xml b/nixos/doc/manual/development/running-nixos-tests.xml new file mode 100644 index 000000000000..d9be761eb01d --- /dev/null +++ b/nixos/doc/manual/development/running-nixos-tests.xml @@ -0,0 +1,77 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-running-nixos-tests"> + +<title>Running Tests</title> + +<para>You can run tests using <command>nix-build</command>. For +example, to run the test <filename +xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/login.nix">login.nix</filename>, +you just do: + +<screen> +$ nix-build '<nixpkgs/nixos/tests/login.nix>' +</screen> + +or, if you don’t want to rely on <envar>NIX_PATH</envar>: + +<screen> +$ cd /my/nixpkgs/nixos/tests +$ nix-build login.nix +… +running the VM test script +machine: QEMU running (pid 8841) +… +6 out of 6 tests succeeded +</screen> + +After building/downloading all required dependencies, this will +perform a build that starts a QEMU/KVM virtual machine containing a +NixOS system. The virtual machine mounts the Nix store of the host; +this makes VM creation very fast, as no disk image needs to be +created. Afterwards, you can view a pretty-printed log of the test: + +<screen> +$ firefox 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 login.nix -A driver +$ ./result/bin/nixos-run-vms +</screen> + +The script <command>nixos-run-vms</command> starts the virtual +machines defined by test. The root file system of the VMs is created +on the fly and kept across VM restarts in +<filename>./</filename><varname>hostname</varname><filename>.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> + +You can then take any Perl statement, e.g. + +<screen> +> startAll +> $machine->succeed("touch /tmp/foo") +</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> + +</section> \ No newline at end of file |