diff --git a/nixos/doc/manual/development/writing-nixos-tests.xml b/nixos/doc/manual/development/writing-nixos-tests.xml
index 7b25a39e83b..a8f6aa00858 100644
--- a/nixos/doc/manual/development/writing-nixos-tests.xml
+++ b/nixos/doc/manual/development/writing-nixos-tests.xml
@@ -272,8 +272,37 @@ startAll;
     </listitem>
   </varlistentry>
 
+  <varlistentry>
+    <term><methodname>systemctl</methodname></term>
+    <listitem>
+      <para>Runs <literal>systemctl</literal> commands with optional support for
+      <literal>systemctl --user</literal></para>
+    <para>
+      <programlisting>
+        $machine->systemctl("list-jobs --no-pager"); // runs `systemctl list-jobs --no-pager`
+        $machine->systemctl("list-jobs --no-pager", "any-user"); // spawns a shell for `any-user` and runs `systemctl --user list-jobs --no-pager`
+      </programlisting>
+    </para>
+    </listitem>
+  </varlistentry>
+
 </variablelist>
 
 </para>
 
+<para>
+  To test user units declared by <literal>systemd.user.services</literal> the optional <literal>$user</literal>
+  argument can be used:
+
+  <programlisting>
+    $machine->start;
+    $machine->waitForX;
+    $machine->waitForUnit("xautolock.service", "x-session-user");
+  </programlisting>
+
+  This applies to <literal>systemctl</literal>, <literal>getUnitInfo</literal>,
+  <literal>waitForUnit</literal>, <literal>startJob</literal>
+  and <literal>stopJob</literal>.
+</para>
+
 </section>
diff --git a/nixos/doc/manual/release-notes/rl-1803.xml b/nixos/doc/manual/release-notes/rl-1803.xml
index c8549e7c4ad..12ff2e39a1b 100644
--- a/nixos/doc/manual/release-notes/rl-1803.xml
+++ b/nixos/doc/manual/release-notes/rl-1803.xml
@@ -234,6 +234,13 @@ following incompatible changes:</para>
       to your <literal>configuration.nix</literal>.
     </para>
   </listitem>
+  <listitem>
+    <para>
+      The NixOS test driver supports user services declared by <literal>systemd.user.services</literal>.
+      The methods <literal>waitForUnit</literal>, <literal>getUnitInfo</literal>, <literal>startJob</literal>
+      and <literal>stopJob</literal> provide an optional <literal>$user</literal> argument for that purpose.
+    </para>
+  </listitem>
 </itemizedlist>
 
 </section>