nixosTest: Document stdout waiting behavior

1 files changed, 6 insertions, 0 deletions

diff --git a/nixos/doc/manual/development/writing-nixos-tests.section.md b/nixos/doc/manual/development/writing-nixos-tests.section.md
index bf80099f1a2..a8c54aa6676 100644
--- a/nixos/doc/manual/development/writing-nixos-tests.section.md
+++ b/nixos/doc/manual/development/writing-nixos-tests.section.md
@@ -159,6 +159,10 @@ The following methods are available on machine objects:
 `execute`
 
 :   Execute a shell command, returning a list `(status, stdout)`.
+    If the command detaches, it must close stdout, as `execute` will wait
+    for this to consume all output reliably. This can be achieved by
+    redirecting stdout to stderr `>&2`, to `/dev/console`, `/dev/null` or
+    a file.
     Takes an optional parameter `check_return` that defaults to `True`.
     Setting this parameter to `False` will not check for the return code
     and return -1 instead. This can be used for commands that shut down
@@ -179,6 +183,8 @@ The following methods are available on machine objects:
 
     -   Dereferencing unset variables fail the command.
 
+    -   It will wait for stdout to be closed. See `execute`.
+
 `fail`
 
 :   Like `succeed`, but raising an exception if the command returns a zero