testers.runCommand: add, document, and test

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.

pkgs/build-support/testers/default.nix

@@ -7,7 +7,9 @@
 
   diffoscopeMinimal,
   runCommand,
+  runCommandWith,
   stdenv,
+  stdenvNoCC,
   substituteAll,
   testers,
 }:
@@ -99,6 +101,31 @@
         else salted;
     in checked;
 
+  # See https://nixos.org/manual/nixpkgs/unstable/#tester-runCommand
+  runCommand = testers.invalidateFetcherByDrvHash (
+    {
+      hash ? "sha256-d6xi4mKdjkX2JFicDIv5niSzpyI0m/Hnm8GGAIU04kY=", # hash value of empty file
+      name,
+      script,
+      stdenv ? stdenvNoCC,
+      ...
+    }@args:
+
+    runCommandWith {
+      inherit name stdenv;
+
+      derivationArgs = {
+        outputHash = hash;
+        outputHashMode = "recursive";
+      } // lib.removeAttrs args [
+        "hash"
+        "name"
+        "script"
+        "stdenv"
+      ];
+    } script
+  );
+
   # See https://nixos.org/manual/nixpkgs/unstable/#tester-runNixOSTest
   # or doc/build-helpers/testers.chapter.md
   runNixOSTest =

pkgs/build-support/testers/test/default.nix

@@ -18,6 +18,27 @@ lib.recurseIntoAttrs {
 
   shellcheck = pkgs.callPackage ../shellcheck/tests.nix { };
 
+  runCommand = lib.recurseIntoAttrs {
+    dns-resolution = testers.runCommand {
+      name = "runCommand-dns-resolution-test";
+      nativeBuildInputs = [ pkgs.ldns ];
+      script = ''
+        drill example.com
+        touch $out
+      '';
+    };
+
+    nonDefault-hash = testers.runCommand {
+      name = "runCommand-nonDefaultHash-test";
+      script = ''
+        mkdir $out
+        touch $out/empty
+        echo aaaaaaaaaaicjnrkeflncmrlk > $out/keymash
+      '';
+      hash = "sha256-eMy+6bkG+KS75u7Zt4PM3APhtdVd60NxmBRN5GKJrHs=";
+    };
+  };
+
   runNixOSTest-example = pkgs-with-overlay.testers.runNixOSTest ({ lib, ... }: {
     name = "runNixOSTest-test";
     nodes.machine = { pkgs, ... }: {