nixos/testing: Improve interactive docs

3 files changed, 47 insertions, 10 deletions

diff --git a/nixos/doc/manual/development/running-nixos-tests-interactively.section.md b/nixos/doc/manual/development/running-nixos-tests-interactively.section.md
index 6170057442d..d9c316f4b13 100644
--- a/nixos/doc/manual/development/running-nixos-tests-interactively.section.md
+++ b/nixos/doc/manual/development/running-nixos-tests-interactively.section.md
@@ -38,6 +38,12 @@ directory.
 
 ## Interactive-only test configuration {#sec-nixos-test-interactive-configuration}
 
-You can add configuration that is specific to the interactive test driver, by adding to the `interactive` option.
-`interactive` is a copy of the regular test options namespace, and is used by the interactive test driver.
-It can be helpful for troubleshooting changes that you don't want to apply to regular test runs.
+The `.driverInteractive` attribute combines the regular test configuration with
+definitions from the [`interactive` submodule](#opt-interactive). This gives you
+a more usable, graphical, but slightly different configuration.
+
+You can add your own interactive-only test configuration by adding extra
+configuration to the [`interactive` submodule](#opt-interactive).
+
+To interactively run only the regular configuration, build the `<test>.driver` attribute
+instead, and call it with the flag `result/bin/nixos-test-driver --interactive`.
diff --git a/nixos/doc/manual/from_md/development/running-nixos-tests-interactively.section.xml b/nixos/doc/manual/from_md/development/running-nixos-tests-interactively.section.xml
index edd3c33ff40..35d9bbd1c1f 100644
--- a/nixos/doc/manual/from_md/development/running-nixos-tests-interactively.section.xml
+++ b/nixos/doc/manual/from_md/development/running-nixos-tests-interactively.section.xml
@@ -42,12 +42,23 @@ $ ./result/bin/nixos-test-driver --keep-vm-state
   <section xml:id="sec-nixos-test-interactive-configuration">
     <title>Interactive-only test configuration</title>
     <para>
-      You can add configuration that is specific to the interactive test
-      driver, by adding to the <literal>interactive</literal> option.
-      <literal>interactive</literal> is a copy of the regular test
-      options namespace, and is used by the interactive test driver. It
-      can be helpful for troubleshooting changes that you don’t want to
-      apply to regular test runs.
+      The <literal>.driverInteractive</literal> attribute combines the
+      regular test configuration with definitions from the
+      <link linkend="opt-interactive"><literal>interactive</literal>
+      submodule</link>. This gives you a more usable, graphical, but
+      slightly different configuration.
+    </para>
+    <para>
+      You can add your own interactive-only test configuration by adding
+      extra configuration to the
+      <link linkend="opt-interactive"><literal>interactive</literal>
+      submodule</link>.
+    </para>
+    <para>
+      To interactively run only the regular configuration, build the
+      <literal>&lt;test&gt;.driver</literal> attribute instead, and call
+      it with the flag
+      <literal>result/bin/nixos-test-driver --interactive</literal>.
     </para>
   </section>
 </section>
diff --git a/nixos/lib/testing/interactive.nix b/nixos/lib/testing/interactive.nix
index 43886fa7267..317ed424188 100644
--- a/nixos/lib/testing/interactive.nix
+++ b/nixos/lib/testing/interactive.nix
@@ -6,11 +6,31 @@ in
   options = {
     interactive = mkOption {
       description = mdDoc ''
-        Tests [can be run interactively](#sec-running-nixos-tests-interactively).
+        Tests [can be run interactively](#sec-running-nixos-tests-interactively)
+        using the program in the test derivation's `.driverInteractive` attribute.
 
         When they are, the configuration will include anything set in this submodule.
 
         You can set any top-level test option here.
+
+        Example test module:
+
+        ```nix
+        { config, lib, ... }: {
+
+          nodes.rabbitmq = {
+            services.rabbitmq.enable = true;
+          };
+
+          # When running interactively ...
+          interactive.nodes.rabbitmq = {
+            # ... enable the web ui.
+            services.rabbitmq.managementPlugin.enable = true;
+          };
+        }
+        ```
+
+        For details, see the section about [running tests interactively](#sec-running-nixos-tests-interactively).
       '';
       type = moduleType;
       visible = "shallow";