Merge pull request #333236 from nbraud/testers/runCommand

testers.runCommand: init

1 files changed, 35 insertions, 0 deletions

diff --git a/doc/build-helpers/testers.chapter.md b/doc/build-helpers/testers.chapter.md
index ec659e75bdb5..5c1b704655cf 100644
--- a/doc/build-helpers/testers.chapter.md
+++ b/doc/build-helpers/testers.chapter.md
@@ -339,6 +339,41 @@ once to get a derivation hash, and again to produce the final fixed output deriv
 
 :::
 
+## `runCommand` {#tester-runCommand}
+
+`runCommand :: { name, script, stdenv ? stdenvNoCC, hash ? "...", ... } -> Derivation`
+
+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.