From 2ce6a39b52d09ce86350fc4dda0d6ff3ddece912 Mon Sep 17 00:00:00 2001
From: Connor Baker <ConnorBaker01@gmail.com>
Date: Wed, 19 Feb 2025 15:50:32 -0800
Subject: [PATCH 1/7] testers.testBuildFailure': init

---
 doc/build-helpers/testers.chapter.md        |  61 +++++++++++
 doc/redirects.json                          |  12 +++
 pkgs/build-support/testers/default.nix      |  66 ++++++++++++
 pkgs/build-support/testers/test/default.nix | 114 ++++++++++++++++++++
 4 files changed, 253 insertions(+)

diff --git a/doc/build-helpers/testers.chapter.md b/doc/build-helpers/testers.chapter.md
index e0eb0cd1a5de6..81e13043e896e 100644
--- a/doc/build-helpers/testers.chapter.md
+++ b/doc/build-helpers/testers.chapter.md
@@ -255,6 +255,67 @@ runCommand "example" {
 
 :::
 
+## `testBuildFailure'` {#tester-testBuildFailurePrime}
+
+This tester wraps the functionality provided by [`testers.testBuildFailure`](#tester-testBuildFailure) to make writing checks easier by simplifying checking the exit code of the builder and asserting the existence of entries in the builder's log.
+Additionally, users may specify a script containing additional checks, accessing the result of applying `testers.testBuildFailure` through the variable `failed`.
+
+:::{.example #ex-testBuildFailurePrime-doc-example}
+
+# Check that a build fails, and verify the changes made during build
+
+```nix
+testers.testBuildFailure' {
+  drv = runCommand "doc-example" { } ''
+    echo ok-ish >"$out"
+    echo failing though
+    exit 3
+  '';
+  expectedBuilderExitCode = 3;
+  expectedBuilderLogEntries = [ "failing though" ];
+  script = ''
+    grep --silent -F 'ok-ish' "$failed/result"
+    touch "$out"
+  '';
+}
+```
+
+:::
+
+### Inputs {#tester-testBuildFailurePrime-inputs}
+
+`drv` (derivation)
+
+: The failing derivation to wrap with `testBuildFailure`.
+
+`name` (string, optional)
+
+: The name of the test.
+  When not provided, this value defaults to `testBuildFailure-${(testers.testBuildFailure drv).name}`.
+
+`expectedBuilderExitCode` (integer, optional)
+
+: The expected exit code of the builder of `drv`.
+  When not provided, this value defaults to `1`.
+
+`expectedBuilderLogEntries` (array of string-like values, optional)
+
+: A list of string-like values which must be found in the builder's log by exact match.
+  When not provided, this value defaults to `[ ]`.
+
+  NOTE: Patterns and regular expressions are not supported.
+
+`script` (string, optional)
+
+: A string containing additional checks to run.
+  When not provided, this value defaults to `""`.
+  The result of `testers.testBuildFailure drv` is available through the variable `failed`.
+  As an example, the builder's log is at `"$failed/testBuildFailure.log"`.
+
+### Return value {#tester-testBuildFailurePrime-return}
+
+The tester produces an empty output and only succeeds when the checks using `expectedBuilderExitCode`, `expectedBuilderLogEntries`, and `script` succeed.
+
 ## `testEqualContents` {#tester-testEqualContents}
 
 Check that two paths have the same contents.
diff --git a/doc/redirects.json b/doc/redirects.json
index ddf3626bbd340..fd3388f3b3b42 100644
--- a/doc/redirects.json
+++ b/doc/redirects.json
@@ -8,6 +8,9 @@
   "ex-build-helpers-extendMkDerivation": [
     "index.html#ex-build-helpers-extendMkDerivation"
   ],
+  "ex-testBuildFailurePrime-doc-example": [
+    "index.html#ex-testBuildFailurePrime-doc-example"
+  ],
   "neovim": [
     "index.html#neovim"
   ],
@@ -332,6 +335,15 @@
   "footnote-stdenv-find-inputs-location.__back.0": [
     "index.html#footnote-stdenv-find-inputs-location.__back.0"
   ],
+  "tester-testBuildFailurePrime": [
+    "index.html#tester-testBuildFailurePrime"
+  ],
+  "tester-testBuildFailurePrime-inputs": [
+    "index.html#tester-testBuildFailurePrime-inputs"
+  ],
+  "tester-testBuildFailurePrime-return": [
+    "index.html#tester-testBuildFailurePrime-return"
+  ],
   "variables-specifying-dependencies": [
     "index.html#variables-specifying-dependencies"
   ],
diff --git a/pkgs/build-support/testers/default.nix b/pkgs/build-support/testers/default.nix
index 0393895d53aff..ec3ddae2e29a8 100644
--- a/pkgs/build-support/testers/default.nix
+++ b/pkgs/build-support/testers/default.nix
@@ -34,6 +34,72 @@
     ] ++ orig.args or ["-e" ../../stdenv/generic/source-stdenv.sh (orig.builder or ../../stdenv/generic/default-builder.sh)];
   });
 
+  # See https://nixos.org/manual/nixpkgs/unstable/#tester-testBuildFailurePrime
+  # or doc/build-helpers/testers.chapter.md
+  testBuildFailure' =
+    let
+      mkBuildCommand =
+        script:
+        ''
+          if [[ -n ''${expectedBuilderExitCode:-} ]]; then
+            nixLog "checking original builder exit code"
+            builderExitCode=$(<"$failed/testBuildFailure.exit")
+            if ((expectedBuilderExitCode == builderExitCode)); then
+              nixLog "original builder exit code matches expected value of $expectedBuilderExitCode"
+            else
+              nixErrorLog "original builder produced exit code $builderExitCode but was expected to produce $expectedBuilderExitCode"
+              exit 1
+            fi
+            unset builderExitCode
+          fi
+
+          if ((''${#expectedBuilderLogEntries[@]})); then
+            nixLog "checking original builder log"
+            builderLogEntries="$(<"$failed/testBuildFailure.log")"
+            shouldExit=0
+            for expectedBuilderLogEntry in "''${expectedBuilderLogEntries[@]}"; do
+              if [[ ''${builderLogEntries} == *"$expectedBuilderLogEntry"* ]]; then
+                nixLog "original builder log contains ''${expectedBuilderLogEntry@Q}"
+              else
+                nixErrorLog "original builder log does not contain ''${expectedBuilderLogEntry@Q}"
+                shouldExit=1
+              fi
+            done
+            unset builderLogEntries
+            ((shouldExit)) && exit 1
+            unset shouldExit
+          fi
+        ''
+        + lib.optionalString (script != "") ''
+          nixLog "running additional checks from user-provided script"
+          ${script}
+        ''
+        + ''
+          touch "$out"
+        '';
+      final =
+        {
+          drv,
+          name ? null,
+          expectedBuilderExitCode ? 1, # NOTE: Should be an integer.
+          expectedBuilderLogEntries ? [ ], # NOTE: Should be an array of string-coercible values. TODO: Only checks for inclusion, not order!
+          script ? "", # Succeed by default if checks pass.
+        }:
+        (runCommand name {
+          __structuredAttrs = true;
+          strictDeps = true;
+          failed = testers.testBuildFailure drv;
+          inherit expectedBuilderExitCode expectedBuilderLogEntries;
+        } (mkBuildCommand script)).overrideAttrs
+          (
+            finalAttrs: _: {
+              # Fix name so the default value uses whatever failed ends up as.
+              name = if name != null then name else "testBuildFailure-${finalAttrs.failed.name}";
+            }
+          );
+    in
+    lib.makeOverridable final;
+
   # See https://nixos.org/manual/nixpkgs/unstable/#tester-testEqualDerivation
   # or doc/build-helpers/testers.chapter.md
   testEqualDerivation = callPackage ./test-equal-derivation.nix { };
diff --git a/pkgs/build-support/testers/test/default.nix b/pkgs/build-support/testers/test/default.nix
index b0f2b4c1d391a..ac05f95f54a98 100644
--- a/pkgs/build-support/testers/test/default.nix
+++ b/pkgs/build-support/testers/test/default.nix
@@ -220,6 +220,120 @@ lib.recurseIntoAttrs {
     sideEffectStructuredAttrs = overrideStructuredAttrs true sideEffects;
   };
 
+  testBuildFailure' = lib.recurseIntoAttrs rec {
+    # NOTE: This example is used in the docs.
+    # See https://nixos.org/manual/nixpkgs/unstable/#tester-testBuildFailurePrime
+    # or doc/build-helpers/testers.chapter.md
+    doc-example = testers.testBuildFailure' {
+      drv = runCommand "doc-example" { } ''
+        echo ok-ish >"$out"
+        echo failing though
+        exit 3
+      '';
+      expectedBuilderExitCode = 3;
+      expectedBuilderLogEntries = [ "failing though" ];
+      script = ''
+        grep --silent -F 'ok-ish' "$failed/result"
+        touch "$out"
+      '';
+    };
+
+    happy = testers.testBuildFailure' {
+      drv = runCommand "happy" { } ''
+        echo ok-ish >$out
+
+        echo failing though
+        echo also stderr 1>&2
+        echo 'line\nwith-\bbackslashes'
+        printf "incomplete line - no newline"
+
+        exit 3
+      '';
+      expectedBuilderExitCode = 3;
+      expectedBuilderLogEntries = [
+        "failing though"
+        "also stderr"
+        ''line\nwith-\bbackslashes''
+        "incomplete line - no newline"
+      ];
+      script = ''
+        grep --silent -F 'ok-ish' "$failed/result"
+        touch "$out"
+      '';
+    };
+
+    happyStructuredAttrs = overrideStructuredAttrs true happy;
+
+    helloDoesNotFail = testers.testBuildFailure' {
+      drv = testers.testBuildFailure hello;
+      expectedBuilderLogEntries = [
+        "testBuildFailure: The builder did not fail, but a failure was expected"
+      ];
+    };
+
+    multiOutput = testers.testBuildFailure' {
+      drv =
+        runCommand "multiOutput"
+          {
+            # dev will be the default output
+            outputs = [
+              "dev"
+              "doc"
+              "out"
+            ];
+          }
+          ''
+            echo i am failing
+            exit 1
+          '';
+      expectedBuilderLogEntries = [
+        "i am failing"
+      ];
+      script = ''
+        # Checking our note that dev is the default output
+        echo $failed/_ | grep -- '-dev/_' >/dev/null
+        echo 'All good.'
+        touch $out
+      '';
+    };
+
+    multiOutputStructuredAttrs = overrideStructuredAttrs true multiOutput;
+
+    sideEffects = testers.testBuildFailure' {
+      drv = stdenvNoCC.mkDerivation {
+        name = "fail-with-side-effects";
+        src = emptyDirectory;
+
+        postHook = ''
+          echo touching side-effect...
+          # Assert that the side-effect doesn't exist yet...
+          # We're checking that this hook isn't run by expect-failure.sh
+          if [[ -e side-effect ]]; then
+            echo "side-effect already exists"
+            exit 1
+          fi
+          touch side-effect
+        '';
+
+        buildPhase = ''
+          echo i am failing
+          exit 1
+        '';
+      };
+      expectedBuilderLogEntries = [
+        "touching side-effect..."
+        "i am failing"
+      ];
+      script = ''
+        [[ ! -e side-effect ]]
+
+        touch $out
+      '';
+    };
+
+    sideEffectStructuredAttrs = overrideStructuredAttrs true sideEffects;
+  };
+
   testEqualContents = lib.recurseIntoAttrs {
     equalDir = testers.testEqualContents {
       assertion = "The same directory contents at different paths are recognized as equal";

From a01f55037d3c42f5e48787f06687e7a91a347251 Mon Sep 17 00:00:00 2001
From: Connor Baker <ConnorBaker01@gmail.com>
Date: Thu, 20 Feb 2025 10:19:33 -0800
Subject: [PATCH 2/7] testers.testBuildFailure': output is created so long as
 checks succeed

---
 doc/build-helpers/testers.chapter.md        | 5 ++++-
 pkgs/build-support/testers/test/default.nix | 5 -----
 2 files changed, 4 insertions(+), 6 deletions(-)

diff --git a/doc/build-helpers/testers.chapter.md b/doc/build-helpers/testers.chapter.md
index 81e13043e896e..74e70162ed3d5 100644
--- a/doc/build-helpers/testers.chapter.md
+++ b/doc/build-helpers/testers.chapter.md
@@ -260,10 +260,14 @@ runCommand "example" {
 This tester wraps the functionality provided by [`testers.testBuildFailure`](#tester-testBuildFailure) to make writing checks easier by simplifying checking the exit code of the builder and asserting the existence of entries in the builder's log.
 Additionally, users may specify a script containing additional checks, accessing the result of applying `testers.testBuildFailure` through the variable `failed`.
 
+NOTE: This tester will produce an empty output and exit with success if none of the checks fail; there is no need to `touch "$out"` in `script`.
+
 :::{.example #ex-testBuildFailurePrime-doc-example}
 
 # Check that a build fails, and verify the changes made during build
 
+Re-using the example from [`testers.testBuildFailure`](#ex-testBuildFailure-showingenvironmentchanges), we can see how common checks are made easier and remove the need for `runCommand`:
+
 ```nix
 testers.testBuildFailure' {
   drv = runCommand "doc-example" { } ''
@@ -275,7 +279,6 @@ testers.testBuildFailure' {
   expectedBuilderLogEntries = [ "failing though" ];
   script = ''
     grep --silent -F 'ok-ish' "$failed/result"
-    touch "$out"
   '';
 }
 ```
diff --git a/pkgs/build-support/testers/test/default.nix b/pkgs/build-support/testers/test/default.nix
index ac05f95f54a98..a7187a7dbfbf8 100644
--- a/pkgs/build-support/testers/test/default.nix
+++ b/pkgs/build-support/testers/test/default.nix
@@ -234,7 +234,6 @@ lib.recurseIntoAttrs {
       expectedBuilderLogEntries = [ "failing though" ];
       script = ''
         grep --silent -F 'ok-ish' "$failed/result"
-        touch "$out"
       '';
     };
 
@@ -258,7 +257,6 @@ lib.recurseIntoAttrs {
       ];
       script = ''
         grep --silent -F 'ok-ish' "$failed/result"
-        touch "$out"
       '';
     };
 
@@ -293,7 +291,6 @@ lib.recurseIntoAttrs {
         # Checking our note that dev is the default output
         echo $failed/_ | grep -- '-dev/_' >/dev/null
         echo 'All good.'
-        touch $out
       '';
     };
 
@@ -326,8 +323,6 @@ lib.recurseIntoAttrs {
       ];
       script = ''
         [[ ! -e side-effect ]]
-
-        touch $out
       '';
     };
 

From 5d541923d28301a568d97812dbfda9a0f2cbdbf5 Mon Sep 17 00:00:00 2001
From: Connor Baker <ConnorBaker01@gmail.com>
Date: Thu, 20 Feb 2025 10:19:52 -0800
Subject: [PATCH 3/7] testers.testBuildFailure': use more strict bash for
 checks

---
 pkgs/build-support/testers/default.nix | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/pkgs/build-support/testers/default.nix b/pkgs/build-support/testers/default.nix
index ec3ddae2e29a8..83c85c3a9f7d7 100644
--- a/pkgs/build-support/testers/default.nix
+++ b/pkgs/build-support/testers/default.nix
@@ -41,6 +41,8 @@
       mkBuildCommand =
         script:
         ''
+          set -euo pipefail
+
           if [[ -n ''${expectedBuilderExitCode:-} ]]; then
             nixLog "checking original builder exit code"
             builderExitCode=$(<"$failed/testBuildFailure.exit")

From efa7ac1648cad38ca250513a8bcedd73914827e5 Mon Sep 17 00:00:00 2001
From: Connor Baker <ConnorBaker01@gmail.com>
Date: Thu, 20 Feb 2025 23:16:16 +0000
Subject: [PATCH 4/7] testers.testBuildFailure': move to separate directory and
 use buildCommandPath

---
 pkgs/build-support/testers/default.nix        |  67 +---------
 pkgs/build-support/testers/test/default.nix   | 111 +---------------
 .../testBuildFailurePrime/build-command.sh    |  40 ++++++
 .../testers/testBuildFailurePrime/tester.nix  |  47 +++++++
 .../testers/testBuildFailurePrime/tests.nix   | 119 ++++++++++++++++++
 5 files changed, 211 insertions(+), 173 deletions(-)
 create mode 100644 pkgs/build-support/testers/testBuildFailurePrime/build-command.sh
 create mode 100644 pkgs/build-support/testers/testBuildFailurePrime/tester.nix
 create mode 100644 pkgs/build-support/testers/testBuildFailurePrime/tests.nix

diff --git a/pkgs/build-support/testers/default.nix b/pkgs/build-support/testers/default.nix
index 83c85c3a9f7d7..0fcbeff9f0d0f 100644
--- a/pkgs/build-support/testers/default.nix
+++ b/pkgs/build-support/testers/default.nix
@@ -36,71 +36,8 @@
 
   # See https://nixos.org/manual/nixpkgs/unstable/#tester-testBuildFailurePrime
   # or doc/build-helpers/testers.chapter.md
-  testBuildFailure' =
-    let
-      mkBuildCommand =
-        script:
-        ''
-          set -euo pipefail
-
-          if [[ -n ''${expectedBuilderExitCode:-} ]]; then
-            nixLog "checking original builder exit code"
-            builderExitCode=$(<"$failed/testBuildFailure.exit")
-            if ((expectedBuilderExitCode == builderExitCode)); then
-              nixLog "original builder exit code matches expected value of $expectedBuilderExitCode"
-            else
-              nixErrorLog "original builder produced exit code $builderExitCode but was expected to produce $expectedBuilderExitCode"
-              exit 1
-            fi
-            unset builderExitCode
-          fi
-
-          if ((''${#expectedBuilderLogEntries[@]})); then
-            nixLog "checking original builder log"
-            builderLogEntries="$(<"$failed/testBuildFailure.log")"
-            shouldExit=0
-            for expectedBuilderLogEntry in "''${expectedBuilderLogEntries[@]}"; do
-              if [[ ''${builderLogEntries} == *"$expectedBuilderLogEntry"* ]]; then
-                nixLog "original builder log contains ''${expectedBuilderLogEntry@Q}"
-              else
-                nixErrorLog "original builder log does not contain ''${expectedBuilderLogEntry@Q}"
-                shouldExit=1
-              fi
-            done
-            unset builderLogEntries
-            ((shouldExit)) && exit 1
-            unset shouldExit
-          fi
-        ''
-        + lib.optionalString (script != "") ''
-          nixLog "running additional checks from user-provided script"
-          ${script}
-        ''
-        + ''
-          touch "$out"
-        '';
-      final =
-        {
-          drv,
-          name ? null,
-          expectedBuilderExitCode ? 1, # NOTE: Should be an integer.
-          expectedBuilderLogEntries ? [ ], # NOTE: Should be an array of string-coercible values. TODO: Only checks for inclusion, not order!
-          script ? "", # Succeed by default if checks pass.
-        }:
-        (runCommand name {
-          __structuredAttrs = true;
-          strictDeps = true;
-          failed = testers.testBuildFailure drv;
-          inherit expectedBuilderExitCode expectedBuilderLogEntries;
-        } (mkBuildCommand script)).overrideAttrs
-          (
-            finalAttrs: _: {
-              # Fix name so the default value uses whatever failed ends up as.
-              name = if name != null then name else "testBuildFailure-${finalAttrs.failed.name}";
-            }
-          );
-    in
-    lib.makeOverridable final;
+  # NOTE: Must be `import`-ed rather than `callPackage`-d to preserve the `override` attribute.
+  testBuildFailure' = import ./testBuildFailurePrime/tester.nix { inherit lib stdenvNoCC testers; };
 
   # See https://nixos.org/manual/nixpkgs/unstable/#tester-testEqualDerivation
   # or doc/build-helpers/testers.chapter.md
diff --git a/pkgs/build-support/testers/test/default.nix b/pkgs/build-support/testers/test/default.nix
index a7187a7dbfbf8..7e4df128391da 100644
--- a/pkgs/build-support/testers/test/default.nix
+++ b/pkgs/build-support/testers/test/default.nix
@@ -220,114 +220,9 @@ lib.recurseIntoAttrs {
     sideEffectStructuredAttrs = overrideStructuredAttrs true sideEffects;
   };
 
-  testBuildFailure' = lib.recurseIntoAttrs rec {
-    # NOTE: This example is used in the docs.
-    # See https://nixos.org/manual/nixpkgs/unstable/#tester-testBuildFailurePrime
-    # or doc/build-helpers/testers.chapter.md
-    doc-example = testers.testBuildFailure' {
-      drv = runCommand "doc-example" { } ''
-        echo ok-ish >"$out"
-        echo failing though
-        exit 3
-      '';
-      expectedBuilderExitCode = 3;
-      expectedBuilderLogEntries = [ "failing though" ];
-      script = ''
-        grep --silent -F 'ok-ish' "$failed/result"
-      '';
-    };
-
-    happy = testers.testBuildFailure' {
-      drv = runCommand "happy" { } ''
-        echo ok-ish >$out
-
-        echo failing though
-        echo also stderr 1>&2
-        echo 'line\nwith-\bbackslashes'
-        printf "incomplete line - no newline"
-
-        exit 3
-      '';
-      expectedBuilderExitCode = 3;
-      expectedBuilderLogEntries = [
-        "failing though"
-        "also stderr"
-        ''line\nwith-\bbackslashes''
-        "incomplete line - no newline"
-      ];
-      script = ''
-        grep --silent -F 'ok-ish' "$failed/result"
-      '';
-    };
-
-    happyStructuredAttrs = overrideStructuredAttrs true happy;
-
-    helloDoesNotFail = testers.testBuildFailure' {
-      drv = testers.testBuildFailure hello;
-      expectedBuilderLogEntries = [
-        "testBuildFailure: The builder did not fail, but a failure was expected"
-      ];
-    };
-
-    multiOutput = testers.testBuildFailure' {
-      drv =
-        runCommand "multiOutput"
-          {
-            # dev will be the default output
-            outputs = [
-              "dev"
-              "doc"
-              "out"
-            ];
-          }
-          ''
-            echo i am failing
-            exit 1
-          '';
-      expectedBuilderLogEntries = [
-        "i am failing"
-      ];
-      script = ''
-        # Checking our note that dev is the default output
-        echo $failed/_ | grep -- '-dev/_' >/dev/null
-        echo 'All good.'
-      '';
-    };
-
-    multiOutputStructuredAttrs = overrideStructuredAttrs true multiOutput;
-
-    sideEffects = testers.testBuildFailure' {
-      drv = stdenvNoCC.mkDerivation {
-        name = "fail-with-side-effects";
-        src = emptyDirectory;
-
-        postHook = ''
-          echo touching side-effect...
-          # Assert that the side-effect doesn't exist yet...
-          # We're checking that this hook isn't run by expect-failure.sh
-          if [[ -e side-effect ]]; then
-            echo "side-effect already exists"
-            exit 1
-          fi
-          touch side-effect
-        '';
-
-        buildPhase = ''
-          echo i am failing
-          exit 1
-        '';
-      };
-      expectedBuilderLogEntries = [
-        "touching side-effect..."
-        "i am failing"
-      ];
-      script = ''
-        [[ ! -e side-effect ]]
-      '';
-    };
-
-    sideEffectStructuredAttrs = overrideStructuredAttrs true sideEffects;
-  };
+  testBuildFailure' = lib.recurseIntoAttrs (
+    pkgs.callPackages ../testBuildFailurePrime/tests.nix { inherit overrideStructuredAttrs; }
+  );
 
   testEqualContents = lib.recurseIntoAttrs {
     equalDir = testers.testEqualContents {
diff --git a/pkgs/build-support/testers/testBuildFailurePrime/build-command.sh b/pkgs/build-support/testers/testBuildFailurePrime/build-command.sh
new file mode 100644
index 0000000000000..f3f292a5f724f
--- /dev/null
+++ b/pkgs/build-support/testers/testBuildFailurePrime/build-command.sh
@@ -0,0 +1,40 @@
+# shellcheck shell=bash
+
+set -eu
+
+scriptPhase() {
+  runHook preScript
+
+  nixLog "checking original builder exit code"
+  local -ir builderExitCode=$(<"${failed:?}/testBuildFailure.exit")
+  # shellcheck disable=SC2154
+  if ((expectedBuilderExitCode == builderExitCode)); then
+    nixLog "original builder exit code matches expected value of $expectedBuilderExitCode"
+  else
+    nixErrorLog "original builder produced exit code $builderExitCode but was expected to produce $expectedBuilderExitCode"
+    exit 1
+  fi
+
+  # shellcheck disable=SC2154
+  if ((${#expectedBuilderLogEntries[@]})); then
+    nixLog "checking original builder log"
+    local -r builderLogEntries="$(<"${failed:?}/testBuildFailure.log")"
+    local -i shouldExit=0
+    for expectedBuilderLogEntry in "${expectedBuilderLogEntries[@]}"; do
+      if [[ ${builderLogEntries} == *"$expectedBuilderLogEntry"* ]]; then
+        nixLog "original builder log contains ${expectedBuilderLogEntry@Q}"
+      else
+        nixErrorLog "original builder log does not contain ${expectedBuilderLogEntry@Q}"
+        shouldExit=1
+      fi
+    done
+    ((shouldExit)) && exit 1
+  fi
+
+  runHook script
+
+  runHook postScript
+}
+
+runHook scriptPhase
+touch "${out:?}"
diff --git a/pkgs/build-support/testers/testBuildFailurePrime/tester.nix b/pkgs/build-support/testers/testBuildFailurePrime/tester.nix
new file mode 100644
index 0000000000000..8b28e19dd1d78
--- /dev/null
+++ b/pkgs/build-support/testers/testBuildFailurePrime/tester.nix
@@ -0,0 +1,47 @@
+# NOTE: Must be `import`-ed rather than `callPackage`-d to preserve the `override` attribute.
+{
+  lib,
+  stdenvNoCC,
+  testers,
+}:
+let
+  inherit (lib) maintainers;
+  inherit (lib.customisation) makeOverridable;
+  inherit (testers) testBuildFailure;
+
+  # See https://nixos.org/manual/nixpkgs/unstable/#tester-testBuildFailurePrime
+  # or doc/build-helpers/testers.chapter.md
+  testBuildFailure' =
+    {
+      drv,
+      name ? "testBuildFailure-${drv.name}",
+      expectedBuilderExitCode ? 1,
+      expectedBuilderLogEntries ? [ ],
+      script ? "",
+    }:
+    let
+      failed = testBuildFailure drv;
+    in
+    stdenvNoCC.mkDerivation {
+      __structuredAttrs = true;
+      strictDeps = true;
+
+      inherit name;
+
+      nativeBuildInputs = [ failed ];
+
+      inherit failed;
+
+      inherit expectedBuilderExitCode expectedBuilderLogEntries;
+
+      inherit script;
+
+      buildCommandPath = ./build-command.sh;
+
+      meta = {
+        description = "A wrapper around testers.testBuildFailure to simplify common use cases";
+        maintainers = [ maintainers.connorbaker ];
+      };
+    };
+in
+makeOverridable testBuildFailure'
diff --git a/pkgs/build-support/testers/testBuildFailurePrime/tests.nix b/pkgs/build-support/testers/testBuildFailurePrime/tests.nix
new file mode 100644
index 0000000000000..9ba65387ae8bc
--- /dev/null
+++ b/pkgs/build-support/testers/testBuildFailurePrime/tests.nix
@@ -0,0 +1,119 @@
+{
+  emptyDirectory,
+  hello,
+  overrideStructuredAttrs,
+  runCommand,
+  stdenvNoCC,
+  testers,
+}:
+let
+  final = {
+    # NOTE: This example is used in the docs.
+    # See https://nixos.org/manual/nixpkgs/unstable/#tester-testBuildFailurePrime
+    # or doc/build-helpers/testers.chapter.md
+    doc-example = testers.testBuildFailure' {
+      drv = runCommand "doc-example" { } ''
+        echo ok-ish >"$out"
+        echo failing though
+        exit 3
+      '';
+      expectedBuilderExitCode = 3;
+      expectedBuilderLogEntries = [ "failing though" ];
+      script = ''
+        grep --silent -F 'ok-ish' "$failed/result"
+      '';
+    };
+
+    happy = testers.testBuildFailure' {
+      drv = runCommand "happy" { } ''
+        echo ok-ish >$out
+
+        echo failing though
+        echo also stderr 1>&2
+        echo 'line\nwith-\bbackslashes'
+        printf "incomplete line - no newline"
+
+        exit 3
+      '';
+      expectedBuilderExitCode = 3;
+      expectedBuilderLogEntries = [
+        "failing though"
+        "also stderr"
+        ''line\nwith-\bbackslashes''
+        "incomplete line - no newline"
+      ];
+      script = ''
+        grep --silent -F 'ok-ish' "$failed/result"
+      '';
+    };
+
+    happyStructuredAttrs = overrideStructuredAttrs true final.happy;
+
+    helloDoesNotFail = testers.testBuildFailure' {
+      drv = testers.testBuildFailure hello;
+      expectedBuilderLogEntries = [
+        "testBuildFailure: The builder did not fail, but a failure was expected"
+      ];
+    };
+
+    multiOutput = testers.testBuildFailure' {
+      drv =
+        runCommand "multiOutput"
+          {
+            # dev will be the default output
+            outputs = [
+              "dev"
+              "doc"
+              "out"
+            ];
+          }
+          ''
+            echo i am failing
+            exit 1
+          '';
+      expectedBuilderLogEntries = [
+        "i am failing"
+      ];
+      script = ''
+        # Checking our note that dev is the default output
+        echo $failed/_ | grep -- '-dev/_' >/dev/null
+        echo 'All good.'
+      '';
+    };
+
+    multiOutputStructuredAttrs = overrideStructuredAttrs true final.multiOutput;
+
+    sideEffects = testers.testBuildFailure' {
+      drv = stdenvNoCC.mkDerivation {
+        name = "fail-with-side-effects";
+        src = emptyDirectory;
+
+        postHook = ''
+          echo touching side-effect...
+          # Assert that the side-effect doesn't exist yet...
+          # We're checking that this hook isn't run by expect-failure.sh
+          if [[ -e side-effect ]]; then
+            echo "side-effect already exists"
+            exit 1
+          fi
+          touch side-effect
+        '';
+
+        buildPhase = ''
+          echo i am failing
+          exit 1
+        '';
+      };
+      expectedBuilderLogEntries = [
+        "touching side-effect..."
+        "i am failing"
+      ];
+      script = ''
+        [[ ! -e side-effect ]]
+      '';
+    };
+
+    sideEffectsStructuredAttrs = overrideStructuredAttrs true final.sideEffects;
+  };
+in
+final

From 98c6d78418bfcf3d3f84356c43ea8e8649f6c8d2 Mon Sep 17 00:00:00 2001
From: Connor Baker <ConnorBaker01@gmail.com>
Date: Fri, 21 Feb 2025 10:11:34 -0800
Subject: [PATCH 5/7] testers.testBuildFailure': move tests to preScriptHooks

---
 .../testBuildFailurePrime/build-command.sh    | 42 +++++++++++--------
 1 file changed, 24 insertions(+), 18 deletions(-)

diff --git a/pkgs/build-support/testers/testBuildFailurePrime/build-command.sh b/pkgs/build-support/testers/testBuildFailurePrime/build-command.sh
index f3f292a5f724f..f4747ff3f76c2 100644
--- a/pkgs/build-support/testers/testBuildFailurePrime/build-command.sh
+++ b/pkgs/build-support/testers/testBuildFailurePrime/build-command.sh
@@ -2,34 +2,40 @@
 
 set -eu
 
-scriptPhase() {
-  runHook preScript
+declare -ag preScriptHooks=(testBuilderExitCode)
+# shellcheck disable=SC2154
+((${#expectedBuilderLogEntries[@]})) && preScriptHooks+=(testBuilderLogEntries)
 
+testBuilderExitCode() {
   nixLog "checking original builder exit code"
   local -ir builderExitCode=$(<"${failed:?}/testBuildFailure.exit")
   # shellcheck disable=SC2154
   if ((expectedBuilderExitCode == builderExitCode)); then
     nixLog "original builder exit code matches expected value of $expectedBuilderExitCode"
+    return 0
   else
     nixErrorLog "original builder produced exit code $builderExitCode but was expected to produce $expectedBuilderExitCode"
-    exit 1
+    return 1
   fi
+}
 
-  # shellcheck disable=SC2154
-  if ((${#expectedBuilderLogEntries[@]})); then
-    nixLog "checking original builder log"
-    local -r builderLogEntries="$(<"${failed:?}/testBuildFailure.log")"
-    local -i shouldExit=0
-    for expectedBuilderLogEntry in "${expectedBuilderLogEntries[@]}"; do
-      if [[ ${builderLogEntries} == *"$expectedBuilderLogEntry"* ]]; then
-        nixLog "original builder log contains ${expectedBuilderLogEntry@Q}"
-      else
-        nixErrorLog "original builder log does not contain ${expectedBuilderLogEntry@Q}"
-        shouldExit=1
-      fi
-    done
-    ((shouldExit)) && exit 1
-  fi
+testBuilderLogEntries() {
+  nixLog "checking original builder log"
+  local -r builderLogEntries="$(<"${failed:?}/testBuildFailure.log")"
+  local -i shouldExit=0
+  for expectedBuilderLogEntry in "${expectedBuilderLogEntries[@]}"; do
+    if [[ ${builderLogEntries} == *"$expectedBuilderLogEntry"* ]]; then
+      nixLog "original builder log contains ${expectedBuilderLogEntry@Q}"
+    else
+      nixErrorLog "original builder log does not contain ${expectedBuilderLogEntry@Q}"
+      shouldExit=1
+    fi
+  done
+  return $shouldExit
+}
+
+scriptPhase() {
+  runHook preScript
 
   runHook script
 

From f93587f28b5e617a4759fbefe714f6f2ddd0230c Mon Sep 17 00:00:00 2001
From: Connor Baker <ConnorBaker01@gmail.com>
Date: Fri, 21 Feb 2025 10:12:36 -0800
Subject: [PATCH 6/7] tests.testers.testBuildFailure': add negative tests for
 exit code check and log check

---
 .../testers/testBuildFailurePrime/tests.nix   | 28 +++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/pkgs/build-support/testers/testBuildFailurePrime/tests.nix b/pkgs/build-support/testers/testBuildFailurePrime/tests.nix
index 9ba65387ae8bc..1f1adadccb32f 100644
--- a/pkgs/build-support/testers/testBuildFailurePrime/tests.nix
+++ b/pkgs/build-support/testers/testBuildFailurePrime/tests.nix
@@ -114,6 +114,34 @@ let
     };
 
     sideEffectsStructuredAttrs = overrideStructuredAttrs true final.sideEffects;
+
+    exitCodeNegativeTest = testers.testBuildFailure' {
+      drv = testers.testBuildFailure' {
+        drv = runCommand "exit-code" { } "exit 3";
+        # Default expected exit code is 1
+      };
+      expectedBuilderLogEntries = [
+        "ERROR: testBuilderExitCode: original builder produced exit code 3 but was expected to produce 1"
+      ];
+    };
+
+    exitCodeNegativeTestStructuredAttrs = overrideStructuredAttrs true final.exitCodeNegativeTest;
+
+    logNegativeTest = testers.testBuildFailure' {
+      drv = testers.testBuildFailure' {
+        drv = runCommand "exit-code" { } ''
+          nixLog "apples"
+          exit 3
+        '';
+        expectedBuilderExitCode = 3;
+        expectedBuilderLogEntries = [ "bees" ];
+      };
+      expectedBuilderLogEntries = [
+        "ERROR: testBuilderLogEntries: original builder log does not contain 'bees'"
+      ];
+    };
+
+    logNegativeTestStructuredAttrs = overrideStructuredAttrs true final.logNegativeTest;
   };
 in
 final

From c40211222cf671729968ee077ba5abdf52bb3b12 Mon Sep 17 00:00:00 2001
From: Connor Baker <ConnorBaker01@gmail.com>
Date: Fri, 21 Feb 2025 12:11:56 -0800
Subject: [PATCH 7/7] testers.testBuildFailure': use default.nix and move
 recurseIntoAttrs into tests.nix

---
 pkgs/build-support/testers/default.nix                        | 2 +-
 .../testers/testBuildFailurePrime/{tester.nix => default.nix} | 0
 pkgs/build-support/testers/testBuildFailurePrime/tests.nix    | 4 +++-
 3 files changed, 4 insertions(+), 2 deletions(-)
 rename pkgs/build-support/testers/testBuildFailurePrime/{tester.nix => default.nix} (100%)

diff --git a/pkgs/build-support/testers/default.nix b/pkgs/build-support/testers/default.nix
index 0fcbeff9f0d0f..4e0be62cc886c 100644
--- a/pkgs/build-support/testers/default.nix
+++ b/pkgs/build-support/testers/default.nix
@@ -37,7 +37,7 @@
   # See https://nixos.org/manual/nixpkgs/unstable/#tester-testBuildFailurePrime
   # or doc/build-helpers/testers.chapter.md
   # NOTE: Must be `import`-ed rather than `callPackage`-d to preserve the `override` attribute.
-  testBuildFailure' = import ./testBuildFailurePrime/tester.nix { inherit lib stdenvNoCC testers; };
+  testBuildFailure' = import ./testBuildFailurePrime { inherit lib stdenvNoCC testers; };
 
   # See https://nixos.org/manual/nixpkgs/unstable/#tester-testEqualDerivation
   # or doc/build-helpers/testers.chapter.md
diff --git a/pkgs/build-support/testers/testBuildFailurePrime/tester.nix b/pkgs/build-support/testers/testBuildFailurePrime/default.nix
similarity index 100%
rename from pkgs/build-support/testers/testBuildFailurePrime/tester.nix
rename to pkgs/build-support/testers/testBuildFailurePrime/default.nix
diff --git a/pkgs/build-support/testers/testBuildFailurePrime/tests.nix b/pkgs/build-support/testers/testBuildFailurePrime/tests.nix
index 1f1adadccb32f..2664f752cd89d 100644
--- a/pkgs/build-support/testers/testBuildFailurePrime/tests.nix
+++ b/pkgs/build-support/testers/testBuildFailurePrime/tests.nix
@@ -1,12 +1,14 @@
 {
   emptyDirectory,
   hello,
+  lib,
   overrideStructuredAttrs,
   runCommand,
   stdenvNoCC,
   testers,
 }:
 let
+  inherit (lib.attrsets) recurseIntoAttrs;
   final = {
     # NOTE: This example is used in the docs.
     # See https://nixos.org/manual/nixpkgs/unstable/#tester-testBuildFailurePrime
@@ -144,4 +146,4 @@ let
     logNegativeTestStructuredAttrs = overrideStructuredAttrs true final.logNegativeTest;
   };
 in
-final
+recurseIntoAttrs final