nixosTest: Document stdout waiting behavior

1 files changed, 12 insertions, 1 deletions

diff --git a/nixos/doc/manual/from_md/development/writing-nixos-tests.section.xml b/nixos/doc/manual/from_md/development/writing-nixos-tests.section.xml
index a3b63422433..e0fd90f2bac 100644
--- a/nixos/doc/manual/from_md/development/writing-nixos-tests.section.xml
+++ b/nixos/doc/manual/from_md/development/writing-nixos-tests.section.xml
@@ -266,7 +266,12 @@ start_all()
       <listitem>
         <para>
           Execute a shell command, returning a list
-          <literal>(status, stdout)</literal>. Takes an optional
+          <literal>(status, stdout)</literal>. If the command detaches,
+          it must close stdout, as <literal>execute</literal> will wait
+          for this to consume all output reliably. This can be achieved
+          by redirecting stdout to stderr <literal>&gt;&amp;2</literal>,
+          to <literal>/dev/console</literal>,
+          <literal>/dev/null</literal> or a file. Takes an optional
           parameter <literal>check_return</literal> that defaults to
           <literal>True</literal>. Setting this parameter to
           <literal>False</literal> will not check for the return code
@@ -306,6 +311,12 @@ start_all()
               Dereferencing unset variables fail the command.
             </para>
           </listitem>
+          <listitem>
+            <para>
+              It will wait for stdout to be closed. See
+              <literal>execute</literal>.
+            </para>
+          </listitem>
         </itemizedlist>
       </listitem>
     </varlistentry>