testers.runCommand: add, document, and test

1 files changed, 33 insertions, 0 deletions

diff --git a/doc/build-helpers/testers.chapter.md b/doc/build-helpers/testers.chapter.md
index ec659e75bdb5..71822b82d774 100644
--- a/doc/build-helpers/testers.chapter.md
+++ b/doc/build-helpers/testers.chapter.md
@@ -339,6 +339,39 @@ once to get a derivation hash, and again to produce the final fixed output deriv
 
 :::
 
+## `runCommand` {#tester-runCommand}
+
+This is a wrapper around `pkgs.runCommandWith`, which
+- produces a fixed-output derivation, enabling the command(s) to access the network ;
+- salts the derivation's name based on its inputs, ensuring the command is re-run whenever the inputs changes.
+
+It accepts the following attributes:
+- the derivation's `name` ;
+- the `script` to be executed ;
+- `stdenv`, the environment to use, defaulting to `stdenvNoCC` ;
+- the derivation's output `hash`, defaulting to the empty file's.
+  The derivation's `outputHashMode` is set by default to recursive, so the `script` can output a directory as well.
+
+All other attributes are passed through to [`mkDerivation`](#sec-using-stdenv),
+including `nativeBuildInputs` to specify dependencies available to the `script`.
+
+:::{.example #ex-tester-runCommand-nix}
+
+# Run a command with network access
+
+```nix
+testers.runCommand {
+  name = "access-the-internet";
+  command = ''
+    curl -o /dev/null https://example.com
+    touch $out
+  '';
+  nativeBuildInputs = with pkgs; [ cacert curl ];
+}
+```
+
+:::
+
 ## `runNixOSTest` {#tester-runNixOSTest}
 
 A helper function that behaves exactly like the NixOS `runTest`, except it also assigns this Nixpkgs package set as the `pkgs` of the test and makes the `nixpkgs.*` options read-only.