1 files changed, 44 insertions, 0 deletions
diff --git a/nixpkgs/nixos/doc/manual/development/running-nixos-tests-interactively.xml b/nixpkgs/nixos/doc/manual/development/running-nixos-tests-interactively.xml
new file mode 100644
index 00000000000..31216874c70
--- /dev/null
+++ b/nixpkgs/nixos/doc/manual/development/running-nixos-tests-interactively.xml
@@ -0,0 +1,44 @@
+<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-interactively">
+ <title>Running Tests interactively</title>
+
+ <para>
+  The test itself can be run interactively. This is particularly useful when
+  developing or debugging a test:
+<screen>
+<prompt>$ </prompt>nix-build nixos/tests/login.nix -A driver
+<prompt>$ </prompt>./result/bin/nixos-test-driver
+starting VDE switch for network 1
+<prompt>&gt;</prompt>
+</screen>
+  You can then take any Python statement, e.g.
+<screen>
+<prompt>&gt;</prompt> start_all()
+<prompt>&gt;</prompt> test_script()
+<prompt>&gt;</prompt> machine.succeed("touch /tmp/foo")
+<prompt>&gt;</prompt> print(machine.succeed("pwd")) # Show stdout of command
+</screen>
+  The function <command>test_script</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>
+  To just start and experiment with the VMs, run:
+<screen>
+<prompt>$ </prompt>nix-build nixos/tests/login.nix -A driver
+<prompt>$ </prompt>./result/bin/nixos-run-vms
+</screen>
+  The script <command>nixos-run-vms</command> starts the virtual machines
+  defined by test.
+ </para>
+
+ <para>
+  The machine state is kept across VM restarts in
+  <filename>/tmp/vm-state-</filename><varname>machinename</varname>.
+ </para>
+</section>