From 261693fe5d961548deae5bda60896beecbc90a27 Mon Sep 17 00:00:00 2001
From: Connor Baker <ConnorBaker01@gmail.com>
Date: Tue, 18 Feb 2025 16:26:16 -0800
Subject: [PATCH 01/10] testers.testEqualArrayOrMap: init

---
 doc/build-helpers/testers.chapter.md          |  91 ++++++
 doc/redirects.json                            |  12 +
 pkgs/build-support/testers/default.nix        |   5 +
 pkgs/build-support/testers/test/default.nix   |   2 +
 .../testEqualArrayOrMap/assert-equal-array.sh |  65 ++++
 .../testEqualArrayOrMap/assert-equal-map.sh   |  96 ++++++
 .../testers/testEqualArrayOrMap/tester.nix    |  92 ++++++
 .../testers/testEqualArrayOrMap/tests.nix     | 279 ++++++++++++++++++
 8 files changed, 642 insertions(+)
 create mode 100644 pkgs/build-support/testers/testEqualArrayOrMap/assert-equal-array.sh
 create mode 100644 pkgs/build-support/testers/testEqualArrayOrMap/assert-equal-map.sh
 create mode 100644 pkgs/build-support/testers/testEqualArrayOrMap/tester.nix
 create mode 100644 pkgs/build-support/testers/testEqualArrayOrMap/tests.nix

diff --git a/doc/build-helpers/testers.chapter.md b/doc/build-helpers/testers.chapter.md
index 74e70162ed3d..904ee76a0d95 100644
--- a/doc/build-helpers/testers.chapter.md
+++ b/doc/build-helpers/testers.chapter.md
@@ -347,6 +347,97 @@ testers.testEqualContents {
 
 :::
 
+## `testEqualArrayOrMap` {#tester-testEqualArrayOrMap}
+
+Check that bash arrays (including associative arrays, referred to as "maps") are populated correctly.
+
+This can be used to ensure setup hooks are registered in a certain order, or write unit tests for shell functions which transform arrays.
+
+:::{.example #ex-testEqualArrayOrMap-test-function-add-cowbell}
+
+# Test a function which appends a value to an array
+
+```nix
+testers.testEqualArrayOrMap {
+  name = "test-function-add-cowbell";
+  valuesArray = [
+    "cowbell"
+    "cowbell"
+  ];
+  expectedArray = [
+    "cowbell"
+    "cowbell"
+    "cowbell"
+  ];
+  checkSetupScript = ''
+    addCowbell() {
+      local -rn arrayNameRef="$1"
+      arrayNameRef+=( "cowbell" )
+    }
+
+    nixLog "appending all values in valuesArray to actualArray"
+    for value in "''${valuesArray[@]}"; do
+      actualArray+=( "$value" )
+    done
+
+    nixLog "applying addCowbell"
+    addCowbell actualArray
+  '';
+}
+```
+
+:::
+
+### Inputs {#tester-testEqualArrayOrMap-inputs}
+
+NOTE: Internally, this tester uses `__structuredAttrs` to handle marhsalling between Nix expressions and shell variables.
+This imposes the restriction that arrays and "maps" have values which are string-coercible.
+
+NOTE: At least one of `expectedArray` and `expectedMap` must be provided.
+
+`name` (string)
+
+: The name of the test.
+
+`checkSetupScript` (string)
+
+: The singular task of `checkSetupScript` is to populate `actualArray` or `actualMap` (it may populate both).
+  To do this, checkSetupScript may access the following shell variables:
+
+  - `valuesArray`
+  - `valuesMap`
+  - `actualArray`
+  - `actualMap`
+
+  While both `expectedArray` and `expectedMap` are in scope during the execution of `checkSetupScript`, they *must not* be accessed or modified from within `checkSetupScript`.
+
+`valuesArray` (array of string-like values, optional)
+
+: An array of string-coercible values.
+  This array may be used within `checkSetupScript`.
+
+`valuesMap` (attribute set of string-like values, optional)
+
+: An attribute set of string-coercible values.
+  This attribute set may be used within `checkSetupScript`.
+
+`expectedArray` (array of string-like values, optional)
+
+: An array of string-coercible values.
+  This array *must not* be accessed or modified from within `checkSetupScript`.
+  When provided, `checkSetupScript` is expected to populate `actualArray`.
+
+`expectedMap` (attribute set of string-like values, optional)
+
+: An attribute set of string-coercible values.
+  This attribute set *must not* be accessed or modified from within `checkSetupScript`.
+  When provided, `checkSetupScript` is expected to populate `actualMap`.
+
+### Return value {#tester-testEqualArrayOrMap-return}
+
+The tester produces an empty output and only succeeds when `expectedArray` and `expectedMap` match `actualArray` and `actualMap`, respectively, when non-null.
+The build log will contain differences encountered.
+
 ## `testEqualDerivation` {#tester-testEqualDerivation}
 
 Checks that two packages produce the exact same build instructions.
diff --git a/doc/redirects.json b/doc/redirects.json
index fe713d03384a..c72770cb50c1 100644
--- a/doc/redirects.json
+++ b/doc/redirects.json
@@ -11,6 +11,9 @@
   "ex-testBuildFailurePrime-doc-example": [
     "index.html#ex-testBuildFailurePrime-doc-example"
   ],
+  "ex-testEqualArrayOrMap-test-function-add-cowbell": [
+    "index.html#ex-testEqualArrayOrMap-test-function-add-cowbell"
+  ],
   "neovim": [
     "index.html#neovim"
   ],
@@ -344,6 +347,15 @@
   "tester-testBuildFailurePrime-return": [
     "index.html#tester-testBuildFailurePrime-return"
   ],
+  "tester-testEqualArrayOrMap": [
+    "index.html#tester-testEqualArrayOrMap"
+  ],
+  "tester-testEqualArrayOrMap-inputs": [
+    "index.html#tester-testEqualArrayOrMap-inputs"
+  ],
+  "tester-testEqualArrayOrMap-return": [
+    "index.html#tester-testEqualArrayOrMap-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 9934e84d7b5e..bdb1726e37ee 100644
--- a/pkgs/build-support/testers/default.nix
+++ b/pkgs/build-support/testers/default.nix
@@ -69,6 +69,11 @@
     fi
   '';
 
+  # See https://nixos.org/manual/nixpkgs/unstable/#tester-testEqualArrayOrMap
+  # or doc/build-helpers/testers.chapter.md
+  # NOTE: Must be `import`-ed rather than `callPackage`-d to preserve the `override` attribute.
+  testEqualArrayOrMap = import ./testEqualArrayOrMap/tester.nix { inherit lib runCommand; };
+
   # See https://nixos.org/manual/nixpkgs/unstable/#tester-testVersion
   # or doc/build-helpers/testers.chapter.md
   testVersion =
diff --git a/pkgs/build-support/testers/test/default.nix b/pkgs/build-support/testers/test/default.nix
index 7e4df128391d..2bd3d1247817 100644
--- a/pkgs/build-support/testers/test/default.nix
+++ b/pkgs/build-support/testers/test/default.nix
@@ -356,4 +356,6 @@ lib.recurseIntoAttrs {
         touch -- "$out"
       '';
   };
+
+  testEqualArrayOrMap = lib.recurseIntoAttrs (pkgs.callPackages ../testEqualArrayOrMap/tests.nix { });
 }
diff --git a/pkgs/build-support/testers/testEqualArrayOrMap/assert-equal-array.sh b/pkgs/build-support/testers/testEqualArrayOrMap/assert-equal-array.sh
new file mode 100644
index 000000000000..4e68b3b1488c
--- /dev/null
+++ b/pkgs/build-support/testers/testEqualArrayOrMap/assert-equal-array.sh
@@ -0,0 +1,65 @@
+# shellcheck shell=bash
+
+# Asserts that two arrays are equal, printing out differences if they are not.
+# Does not short circuit on the first difference.
+assertEqualArray() {
+  if (($# != 2)); then
+    nixErrorLog "expected two arguments!"
+    nixErrorLog "usage: assertEqualArray expectedArrayRef actualArrayRef"
+    exit 1
+  fi
+
+  local -nr expectedArrayRef="$1"
+  local -nr actualArrayRef="$2"
+
+  if [[ ! ${expectedArrayRef@a} =~ a ]]; then
+    nixErrorLog "first arugment expectedArrayRef must be an array reference"
+    exit 1
+  fi
+
+  if [[ ! ${actualArrayRef@a} =~ a ]]; then
+    nixErrorLog "second arugment actualArrayRef must be an array reference"
+    exit 1
+  fi
+
+  local -ir expectedLength=${#expectedArrayRef[@]}
+  local -ir actualLength=${#actualArrayRef[@]}
+
+  local -i hasDiff=0
+
+  if ((expectedLength != actualLength)); then
+    nixErrorLog "arrays differ in length: expectedArray has length $expectedLength but actualArray has length $actualLength"
+    hasDiff=1
+  fi
+
+  local -i idx=0
+  local expectedValue
+  local actualValue
+
+  # We iterate so long as at least one array has indices we've not considered.
+  # This means that `idx` is a valid index to *at least one* of the arrays.
+  for ((idx = 0; idx < expectedLength || idx < actualLength; idx++)); do
+    # Update values for variables which are still in range/valid.
+    if ((idx < expectedLength)); then
+      expectedValue="${expectedArrayRef[idx]}"
+    fi
+
+    if ((idx < actualLength)); then
+      actualValue="${actualArrayRef[idx]}"
+    fi
+
+    # Handle comparisons.
+    if ((idx >= expectedLength)); then
+      nixErrorLog "arrays differ at index $idx: expectedArray has no such index but actualArray has value ${actualValue@Q}"
+      hasDiff=1
+    elif ((idx >= actualLength)); then
+      nixErrorLog "arrays differ at index $idx: expectedArray has value ${expectedValue@Q} but actualArray has no such index"
+      hasDiff=1
+    elif [[ $expectedValue != "$actualValue" ]]; then
+      nixErrorLog "arrays differ at index $idx: expectedArray has value ${expectedValue@Q} but actualArray has value ${actualValue@Q}"
+      hasDiff=1
+    fi
+  done
+
+  ((hasDiff)) && exit 1 || return 0
+}
diff --git a/pkgs/build-support/testers/testEqualArrayOrMap/assert-equal-map.sh b/pkgs/build-support/testers/testEqualArrayOrMap/assert-equal-map.sh
new file mode 100644
index 000000000000..1e07b3aaff02
--- /dev/null
+++ b/pkgs/build-support/testers/testEqualArrayOrMap/assert-equal-map.sh
@@ -0,0 +1,96 @@
+# shellcheck shell=bash
+
+# Asserts that two maps are equal, printing out differences if they are not.
+# Does not short circuit on the first difference.
+assertEqualMap() {
+  if (($# != 2)); then
+    nixErrorLog "expected two arguments!"
+    nixErrorLog "usage: assertEqualMap expectedMapRef actualMapRef"
+    exit 1
+  fi
+
+  local -nr expectedMapRef="$1"
+  local -nr actualMapRef="$2"
+
+  if [[ ! ${expectedMapRef@a} =~ A ]]; then
+    nixErrorLog "first arugment expectedMapRef must be an associative array reference"
+    exit 1
+  fi
+
+  if [[ ! ${actualMapRef@a} =~ A ]]; then
+    nixErrorLog "second arugment actualMapRef must be an associative array reference"
+    exit 1
+  fi
+
+  # NOTE:
+  # From the `sort` manpage: "The locale specified by the environment affects sort order. Set LC_ALL=C to get the
+  # traditional sort order that uses native byte values."
+  # We specify the environment variable in a subshell to avoid polluting the caller's environment.
+
+  local -a sortedExpectedKeys
+  mapfile -d '' -t sortedExpectedKeys < <(printf '%s\0' "${!expectedMapRef[@]}" | LC_ALL=C sort --stable --zero-terminated)
+
+  local -a sortedActualKeys
+  mapfile -d '' -t sortedActualKeys < <(printf '%s\0' "${!actualMapRef[@]}" | LC_ALL=C sort --stable --zero-terminated)
+
+  local -ir expectedLength=${#expectedMapRef[@]}
+  local -ir actualLength=${#actualMapRef[@]}
+
+  local -i hasDiff=0
+
+  if ((expectedLength != actualLength)); then
+    nixErrorLog "maps differ in length: expectedMap has length $expectedLength but actualMap has length $actualLength"
+    hasDiff=1
+  fi
+
+  local -i expectedKeyIdx=0
+  local expectedKey
+  local expectedValue
+  local -i actualKeyIdx=0
+  local actualKey
+  local actualValue
+
+  # We iterate so long as at least one map has keys we've not considered.
+  while ((expectedKeyIdx < expectedLength || actualKeyIdx < actualLength)); do
+    # Update values for variables which are still in range/valid.
+    if ((expectedKeyIdx < expectedLength)); then
+      expectedKey="${sortedExpectedKeys["$expectedKeyIdx"]}"
+      expectedValue="${expectedMapRef["$expectedKey"]}"
+    fi
+
+    if ((actualKeyIdx < actualLength)); then
+      actualKey="${sortedActualKeys["$actualKeyIdx"]}"
+      actualValue="${actualMapRef["$actualKey"]}"
+    fi
+
+    # In the case actualKeyIdx is valid and expectedKey comes after actualKey or expectedKeyIdx is invalid, actualMap
+    # has an extra key relative to expectedMap.
+    # NOTE: In Bash, && and || have the same precedence, so use the fact they're left-associative to enforce groups.
+    if ((actualKeyIdx < actualLength)) && [[ $expectedKey > $actualKey ]] || ((expectedKeyIdx >= expectedLength)); then
+      nixErrorLog "maps differ at key ${actualKey@Q}: expectedMap has no such key but actualMap has value ${actualValue@Q}"
+      hasDiff=1
+      actualKeyIdx+=1
+
+    # In the case actualKeyIdx is invalid or expectedKey comes before actualKey, expectedMap has an extra key relative
+    # to actualMap.
+    # NOTE: By virtue of the previous condition being false, we know the negation is true. Namely, expectedKeyIdx is
+    # valid AND (actualKeyIdx is invalid OR expectedKey <= actualKey).
+    elif ((actualKeyIdx >= actualLength)) || [[ $expectedKey < $actualKey ]]; then
+      nixErrorLog "maps differ at key ${expectedKey@Q}: expectedMap has value ${expectedValue@Q} but actualMap has no such key"
+      hasDiff=1
+      expectedKeyIdx+=1
+
+    # In the case where both key indices are valid and the keys are equal.
+    else
+      if [[ $expectedValue != "$actualValue" ]]; then
+        nixErrorLog "maps differ at key ${expectedKey@Q}: expectedMap has value ${expectedValue@Q} but actualMap has value ${actualValue@Q}"
+        hasDiff=1
+      fi
+
+      expectedKeyIdx+=1
+      actualKeyIdx+=1
+    fi
+  done
+
+  ((hasDiff)) && exit 1 || return 0
+}
diff --git a/pkgs/build-support/testers/testEqualArrayOrMap/tester.nix b/pkgs/build-support/testers/testEqualArrayOrMap/tester.nix
new file mode 100644
index 000000000000..73f8972c0eb6
--- /dev/null
+++ b/pkgs/build-support/testers/testEqualArrayOrMap/tester.nix
@@ -0,0 +1,92 @@
+# NOTE: Must be `import`-ed rather than `callPackage`-d to preserve the `override` attribute.
+# NOTE: We must use `pkgs.runCommand` instead of `testers.runCommand` to build `testers.testEqualArrayOrMap`, or else
+# our negative tests will not work. See ./tests.nix for more information.
+{
+  lib,
+  runCommand,
+}:
+let
+  inherit (lib) maintainers;
+  inherit (lib.customisation) makeOverridable;
+  inherit (lib.strings) optionalString;
+
+  testEqualArrayOrMap =
+    {
+      name,
+      valuesArray ? null,
+      valuesMap ? null,
+      expectedArray ? null,
+      expectedMap ? null,
+      checkSetupScript ? ''
+        nixErrorLog "no checkSetupScript provided!"
+        exit 1
+      '',
+    }:
+    runCommand name
+      {
+        __structuredAttrs = true;
+        strictDeps = true;
+
+        nativeBuildInputs = [
+          ./assert-equal-array.sh
+          ./assert-equal-map.sh
+        ];
+
+        inherit valuesArray valuesMap;
+        inherit expectedArray expectedMap;
+
+        preCheckSetupScript =
+          optionalString (expectedArray == null && expectedMap == null) ''
+            nixErrorLog "neither expectedArray nor expectedMap were set, so test is meaningless!"
+            exit 1
+          ''
+          + optionalString (valuesArray != null) ''
+            nixLog "using valuesArray: $(declare -p valuesArray)"
+          ''
+          + optionalString (valuesMap != null) ''
+            nixLog "using valuesMap: $(declare -p valuesMap)"
+          ''
+          + optionalString (expectedArray != null) ''
+            nixLog "using expectedArray: $(declare -p expectedArray)"
+            declare -ag actualArray
+          ''
+          + optionalString (expectedMap != null) ''
+            nixLog "using expectedMap: $(declare -p expectedMap)"
+            declare -Ag actualMap
+          '';
+
+        # NOTE:
+        # The singular task of checkSetupScript is to populate actualArray or actualMap. To do this, checkSetupScript
+        # may access valuesArray, valuesMap, actualArray, and actualMap, but should *never* access or modify expectedArray,
+        # or expectedMap.
+        inherit checkSetupScript;
+
+        postCheckSetupScript =
+          optionalString (expectedArray != null) ''
+            nixLog "using actualArray: $(declare -p actualArray)"
+            nixLog "comparing actualArray against expectedArray"
+            assertEqualArray expectedArray actualArray
+            nixLog "actualArray matches expectedArray"
+          ''
+          + optionalString (expectedMap != null) ''
+            nixLog "using actualMap: $(declare -p actualMap)"
+            nixLog "comparing actualMap against expectedMap"
+            assertEqualMap expectedMap actualMap
+            nixLog "actualMap matches expectedMap"
+          '';
+      }
+      ''
+        nixLog "running preCheckSetupScript"
+        runHook preCheckSetupScript
+
+        nixLog "running checkSetupScript"
+        runHook checkSetupScript
+
+        nixLog "running postCheckSetupScript"
+        runHook postCheckSetupScript
+
+        nixLog "test passed"
+        touch "$out"
+      '';
+in
+makeOverridable testEqualArrayOrMap
diff --git a/pkgs/build-support/testers/testEqualArrayOrMap/tests.nix b/pkgs/build-support/testers/testEqualArrayOrMap/tests.nix
new file mode 100644
index 000000000000..92888151d43e
--- /dev/null
+++ b/pkgs/build-support/testers/testEqualArrayOrMap/tests.nix
@@ -0,0 +1,279 @@
+# NOTE: We must use `pkgs.runCommand` instead of `testers.runCommand` for negative tests -- those wrapped with
+# `testers.testBuildFailure`. This is due to the fact that `testers.testBuildFailure` modifies the derivation such that
+# it produces an output containing the exit code, logs, and other things. Since `testers.runCommand` expects the empty
+# derivation, it produces a hash mismatch.
+{ runCommand, testers, ... }:
+let
+  inherit (testers) testEqualArrayOrMap testBuildFailure;
+  concatValuesArrayToActualArray = ''
+    nixLog "appending all values in valuesArray to actualArray"
+    for value in "''${valuesArray[@]}"; do
+      actualArray+=( "$value" )
+    done
+  '';
+  concatValuesMapToActualMap = ''
+    nixLog "adding all values in valuesMap to actualMap"
+    for key in "''${!valuesMap[@]}"; do
+      actualMap["$key"]="''${valuesMap["$key"]}"
+    done
+  '';
+in
+{
+  # NOTE: This particular test is used in the docs:
+  # See https://nixos.org/manual/nixpkgs/unstable/#tester-testEqualArrayOrMap
+  # or doc/build-helpers/testers.chapter.md
+  docs-test-function-add-cowbell = testEqualArrayOrMap {
+    name = "test-function-add-cowbell";
+    valuesArray = [
+      "cowbell"
+      "cowbell"
+    ];
+    expectedArray = [
+      "cowbell"
+      "cowbell"
+      "cowbell"
+    ];
+    checkSetupScript = ''
+      addCowbell() {
+        local -rn arrayNameRef="$1"
+        arrayNameRef+=( "cowbell" )
+      }
+
+      nixLog "appending all values in valuesArray to actualArray"
+      for value in "''${valuesArray[@]}"; do
+        actualArray+=( "$value" )
+      done
+
+      nixLog "applying addCowbell"
+      addCowbell actualArray
+    '';
+  };
+  array-append = testEqualArrayOrMap {
+    name = "testEqualArrayOrMap-array-append";
+    valuesArray = [
+      "apple"
+      "bee"
+      "cat"
+    ];
+    expectedArray = [
+      "apple"
+      "bee"
+      "cat"
+      "dog"
+    ];
+    checkSetupScript = ''
+      ${concatValuesArrayToActualArray}
+      actualArray+=( "dog" )
+    '';
+  };
+  array-prepend = testEqualArrayOrMap {
+    name = "testEqualArrayOrMap-array-prepend";
+    valuesArray = [
+      "apple"
+      "bee"
+      "cat"
+    ];
+    expectedArray = [
+      "dog"
+      "apple"
+      "bee"
+      "cat"
+    ];
+    checkSetupScript = ''
+      actualArray+=( "dog" )
+      ${concatValuesArrayToActualArray}
+    '';
+  };
+  array-empty = testEqualArrayOrMap {
+    name = "testEqualArrayOrMap-array-empty";
+    valuesArray = [
+      "apple"
+      "bee"
+      "cat"
+    ];
+    expectedArray = [ ];
+    checkSetupScript = ''
+      # doing nothing
+    '';
+  };
+  array-missing-value =
+    let
+      name = "testEqualArrayOrMap-array-missing-value";
+      failure = testEqualArrayOrMap {
+        name = "${name}-failure";
+        valuesArray = [ "apple" ];
+        expectedArray = [ ];
+        checkSetupScript = concatValuesArrayToActualArray;
+      };
+    in
+    runCommand name
+      {
+        failed = testBuildFailure failure;
+        passthru = {
+          inherit failure;
+        };
+      }
+      ''
+        nixLog "Checking for exit code 1"
+        (( 1 == "$(cat "$failed/testBuildFailure.exit")" ))
+        nixLog "Checking for first error message"
+        grep -F \
+          "ERROR: assertEqualArray: arrays differ in length: expectedArray has length 0 but actualArray has length 1" \
+          "$failed/testBuildFailure.log"
+        nixLog "Checking for second error message"
+        grep -F \
+          "ERROR: assertEqualArray: arrays differ at index 0: expectedArray has no such index but actualArray has value 'apple'" \
+          "$failed/testBuildFailure.log"
+        nixLog "Test passed"
+        touch $out
+      '';
+  map-insert = testEqualArrayOrMap {
+    name = "testEqualArrayOrMap-map-insert";
+    valuesMap = {
+      apple = "0";
+      bee = "1";
+      cat = "2";
+    };
+    expectedMap = {
+      apple = "0";
+      bee = "1";
+      cat = "2";
+      dog = "3";
+    };
+    checkSetupScript = ''
+      ${concatValuesMapToActualMap}
+      actualMap["dog"]="3"
+    '';
+  };
+  map-remove = testEqualArrayOrMap {
+    name = "testEqualArrayOrMap-map-remove";
+    valuesMap = {
+      apple = "0";
+      bee = "1";
+      cat = "2";
+      dog = "3";
+    };
+    expectedMap = {
+      apple = "0";
+      cat = "2";
+      dog = "3";
+    };
+    checkSetupScript = ''
+      ${concatValuesMapToActualMap}
+      unset 'actualMap[bee]'
+    '';
+  };
+  map-missing-key =
+    let
+      name = "testEqualArrayOrMap-map-missing-key";
+      failure = testEqualArrayOrMap {
+        name = "${name}-failure";
+        valuesMap = {
+          bee = "1";
+          cat = "2";
+          dog = "3";
+        };
+        expectedMap = {
+          apple = "0";
+          bee = "1";
+          cat = "2";
+          dog = "3";
+        };
+        checkSetupScript = concatValuesMapToActualMap;
+      };
+    in
+    runCommand name
+      {
+        failed = testBuildFailure failure;
+        passthru = {
+          inherit failure;
+        };
+      }
+      ''
+        nixLog "Checking for exit code 1"
+        (( 1 == "$(cat "$failed/testBuildFailure.exit")" ))
+        nixLog "Checking for first error message"
+        grep -F \
+          "ERROR: assertEqualMap: maps differ in length: expectedMap has length 4 but actualMap has length 3" \
+          "$failed/testBuildFailure.log"
+        nixLog "Checking for second error message"
+        grep -F \
+          "ERROR: assertEqualMap: maps differ at key 'apple': expectedMap has value '0' but actualMap has no such key" \
+          "$failed/testBuildFailure.log"
+        nixLog "Test passed"
+        touch $out
+      '';
+  map-missing-key-with-empty =
+    let
+      name = "map-missing-key-with-empty";
+      failure = testEqualArrayOrMap {
+        name = "${name}-failure";
+        valuesArray = [ ];
+        expectedMap.apple = 1;
+        checkSetupScript = ''
+          nixLog "doing nothing in checkSetupScript"
+        '';
+      };
+    in
+    runCommand name
+      {
+        failed = testBuildFailure failure;
+        passthru = {
+          inherit failure;
+        };
+      }
+      ''
+        nixLog "Checking for exit code 1"
+        (( 1 == "$(cat "$failed/testBuildFailure.exit")" ))
+        nixLog "Checking for first error message"
+        grep -F \
+          "ERROR: assertEqualMap: maps differ in length: expectedMap has length 1 but actualMap has length 0" \
+          "$failed/testBuildFailure.log"
+        nixLog "Checking for second error message"
+        grep -F \
+          "ERROR: assertEqualMap: maps differ at key 'apple': expectedMap has value '1' but actualMap has no such key" \
+          "$failed/testBuildFailure.log"
+        nixLog "Test passed"
+        touch $out
+      '';
+  map-extra-key =
+    let
+      name = "testEqualArrayOrMap-map-extra-key";
+      failure = testEqualArrayOrMap {
+        name = "${name}-failure";
+        valuesMap = {
+          apple = "0";
+          bee = "1";
+          cat = "2";
+          dog = "3";
+        };
+        expectedMap = {
+          apple = "0";
+          bee = "1";
+          dog = "3";
+        };
+        checkSetupScript = concatValuesMapToActualMap;
+      };
+    in
+    runCommand
+      {
+        failed = testBuildFailure failure;
+        passthru = {
+          inherit failure;
+        };
+      }
+      ''
+        nixLog "Checking for exit code 1"
+        (( 1 == "$(cat "$failed/testBuildFailure.exit")" ))
+        nixLog "Checking for first error message"
+        grep -F \
+          "ERROR: assertEqualMap: maps differ in length: expectedMap has length 3 but actualMap has length 4" \
+          "$failed/testBuildFailure.log"
+        nixLog "Checking for second error message"
+        grep -F \
+          "ERROR: assertEqualMap: maps differ at key 'cat': expectedMap has no such key but actualMap has value '2'" \
+          "$failed/testBuildFailure.log"
+        nixLog "Test passed"
+        touch $out
+      '';
+}

From 731b74db8b1e2e55147e23b66ea248c9cdf1abd8 Mon Sep 17 00:00:00 2001
From: Connor Baker <ConnorBaker01@gmail.com>
Date: Thu, 20 Feb 2025 22:37:59 +0000
Subject: [PATCH 02/10] testers.testEqualArrayOrMap: use buildCommandPath and
 change checkSetupScript argument to script

---
 doc/build-helpers/testers.chapter.md          | 44 +++++-----
 pkgs/build-support/testers/default.nix        |  2 +-
 .../testEqualArrayOrMap/assert-equal-array.sh | 14 +++-
 .../testEqualArrayOrMap/assert-equal-map.sh   | 14 +++-
 .../testEqualArrayOrMap/build-command.sh      | 64 ++++++++++++++
 .../testers/testEqualArrayOrMap/tester.nix    | 83 ++++---------------
 .../testers/testEqualArrayOrMap/tests.nix     | 22 +++--
 7 files changed, 132 insertions(+), 111 deletions(-)
 create mode 100644 pkgs/build-support/testers/testEqualArrayOrMap/build-command.sh

diff --git a/doc/build-helpers/testers.chapter.md b/doc/build-helpers/testers.chapter.md
index 904ee76a0d95..d3c8a7a78bb6 100644
--- a/doc/build-helpers/testers.chapter.md
+++ b/doc/build-helpers/testers.chapter.md
@@ -351,7 +351,7 @@ testers.testEqualContents {
 
 Check that bash arrays (including associative arrays, referred to as "maps") are populated correctly.
 
-This can be used to ensure setup hooks are registered in a certain order, or write unit tests for shell functions which transform arrays.
+This can be used to ensure setup hooks are registered in a certain order, or to write unit tests for shell functions which transform arrays.
 
 :::{.example #ex-testEqualArrayOrMap-test-function-add-cowbell}
 
@@ -369,7 +369,7 @@ testers.testEqualArrayOrMap {
     "cowbell"
     "cowbell"
   ];
-  checkSetupScript = ''
+  script = ''
     addCowbell() {
       local -rn arrayNameRef="$1"
       arrayNameRef+=( "cowbell" )
@@ -390,8 +390,8 @@ testers.testEqualArrayOrMap {
 
 ### Inputs {#tester-testEqualArrayOrMap-inputs}
 
-NOTE: Internally, this tester uses `__structuredAttrs` to handle marhsalling between Nix expressions and shell variables.
-This imposes the restriction that arrays and "maps" have values which are string-coercible.
+NOTE: Internally, this tester uses `__structuredAttrs` to handle marshalling between Nix expressions and shell variables.
+This imposes the restriction that arrays and "maps" have values which are string-like.
 
 NOTE: At least one of `expectedArray` and `expectedMap` must be provided.
 
@@ -399,39 +399,39 @@ NOTE: At least one of `expectedArray` and `expectedMap` must be provided.
 
 : The name of the test.
 
-`checkSetupScript` (string)
+`script` (string)
 
-: The singular task of `checkSetupScript` is to populate `actualArray` or `actualMap` (it may populate both).
-  To do this, checkSetupScript may access the following shell variables:
+: The singular task of `script` is to populate `actualArray` or `actualMap` (it may populate both).
+  To do this, `script` may access the following shell variables:
 
-  - `valuesArray`
-  - `valuesMap`
-  - `actualArray`
-  - `actualMap`
+  - `valuesArray` (available when `valuesArray` is provided to the tester)
+  - `valuesMap` (available when `valuesMap` is provided to the tester)
+  - `actualArray` (available when `expectedArray` is provided to the tester)
+  - `actualMap` (available when `expectedMap` is provided to the tester)
 
-  While both `expectedArray` and `expectedMap` are in scope during the execution of `checkSetupScript`, they *must not* be accessed or modified from within `checkSetupScript`.
+  While both `expectedArray` and `expectedMap` are in scope during the execution of `script`, they *must not* be accessed or modified from within `script`.
 
 `valuesArray` (array of string-like values, optional)
 
-: An array of string-coercible values.
-  This array may be used within `checkSetupScript`.
+: An array of string-like values.
+  This array may be used within `script`.
 
 `valuesMap` (attribute set of string-like values, optional)
 
-: An attribute set of string-coercible values.
-  This attribute set may be used within `checkSetupScript`.
+: An attribute set of string-like values.
+  This attribute set may be used within `script`.
 
 `expectedArray` (array of string-like values, optional)
 
-: An array of string-coercible values.
-  This array *must not* be accessed or modified from within `checkSetupScript`.
-  When provided, `checkSetupScript` is expected to populate `actualArray`.
+: An array of string-like values.
+  This array *must not* be accessed or modified from within `script`.
+  When provided, `script` is expected to populate `actualArray`.
 
 `expectedMap` (attribute set of string-like values, optional)
 
-: An attribute set of string-coercible values.
-  This attribute set *must not* be accessed or modified from within `checkSetupScript`.
-  When provided, `checkSetupScript` is expected to populate `actualMap`.
+: An attribute set of string-like values.
+  This attribute set *must not* be accessed or modified from within `script`.
+  When provided, `script` is expected to populate `actualMap`.
 
 ### Return value {#tester-testEqualArrayOrMap-return}
 
diff --git a/pkgs/build-support/testers/default.nix b/pkgs/build-support/testers/default.nix
index bdb1726e37ee..a0ebc7061488 100644
--- a/pkgs/build-support/testers/default.nix
+++ b/pkgs/build-support/testers/default.nix
@@ -72,7 +72,7 @@
   # See https://nixos.org/manual/nixpkgs/unstable/#tester-testEqualArrayOrMap
   # or doc/build-helpers/testers.chapter.md
   # NOTE: Must be `import`-ed rather than `callPackage`-d to preserve the `override` attribute.
-  testEqualArrayOrMap = import ./testEqualArrayOrMap/tester.nix { inherit lib runCommand; };
+  testEqualArrayOrMap = import ./testEqualArrayOrMap/tester.nix { inherit lib stdenvNoCC; };
 
   # See https://nixos.org/manual/nixpkgs/unstable/#tester-testVersion
   # or doc/build-helpers/testers.chapter.md
diff --git a/pkgs/build-support/testers/testEqualArrayOrMap/assert-equal-array.sh b/pkgs/build-support/testers/testEqualArrayOrMap/assert-equal-array.sh
index 4e68b3b1488c..92fa981e44ee 100644
--- a/pkgs/build-support/testers/testEqualArrayOrMap/assert-equal-array.sh
+++ b/pkgs/build-support/testers/testEqualArrayOrMap/assert-equal-array.sh
@@ -1,5 +1,11 @@
 # shellcheck shell=bash
 
+# Tests if an array is declared.
+isDeclaredArray() {
+  # shellcheck disable=SC2034
+  local -nr arrayRef="$1" && [[ ${!arrayRef@a} =~ a ]]
+}
+
 # Asserts that two arrays are equal, printing out differences if they are not.
 # Does not short circuit on the first difference.
 assertEqualArray() {
@@ -12,13 +18,13 @@ assertEqualArray() {
   local -nr expectedArrayRef="$1"
   local -nr actualArrayRef="$2"
 
-  if [[ ! ${expectedArrayRef@a} =~ a ]]; then
-    nixErrorLog "first arugment expectedArrayRef must be an array reference"
+  if ! isDeclaredArray expectedArrayRef; then
+    nixErrorLog "first arugment expectedArrayRef must be an array reference to a declared array"
     exit 1
   fi
 
-  if [[ ! ${actualArrayRef@a} =~ a ]]; then
-    nixErrorLog "second arugment actualArrayRef must be an array reference"
+  if ! isDeclaredArray actualArrayRef; then
+    nixErrorLog "second arugment actualArrayRef must be an array reference to a declared array"
     exit 1
   fi
 
diff --git a/pkgs/build-support/testers/testEqualArrayOrMap/assert-equal-map.sh b/pkgs/build-support/testers/testEqualArrayOrMap/assert-equal-map.sh
index 1e07b3aaff02..f66fab4f8468 100644
--- a/pkgs/build-support/testers/testEqualArrayOrMap/assert-equal-map.sh
+++ b/pkgs/build-support/testers/testEqualArrayOrMap/assert-equal-map.sh
@@ -1,5 +1,11 @@
 # shellcheck shell=bash
 
+# Tests if a map is declared.
+isDeclaredMap() {
+  # shellcheck disable=SC2034
+  local -nr mapRef="$1" && [[ ${!mapRef@a} =~ A ]]
+}
+
 # Asserts that two maps are equal, printing out differences if they are not.
 # Does not short circuit on the first difference.
 assertEqualMap() {
@@ -12,13 +18,13 @@ assertEqualMap() {
   local -nr expectedMapRef="$1"
   local -nr actualMapRef="$2"
 
-  if [[ ! ${expectedMapRef@a} =~ A ]]; then
-    nixErrorLog "first arugment expectedMapRef must be an associative array reference"
+  if ! isDeclaredMap expectedMapRef; then
+    nixErrorLog "first arugment expectedMapRef must be an associative array reference to a declared associative array"
     exit 1
   fi
 
-  if [[ ! ${actualMapRef@a} =~ A ]]; then
-    nixErrorLog "second arugment actualMapRef must be an associative array reference"
+  if ! isDeclaredMap actualMapRef; then
+    nixErrorLog "second arugment actualMapRef must be an associative array reference to a declared associative array"
     exit 1
   fi
 
diff --git a/pkgs/build-support/testers/testEqualArrayOrMap/build-command.sh b/pkgs/build-support/testers/testEqualArrayOrMap/build-command.sh
new file mode 100644
index 000000000000..b1733692d1e9
--- /dev/null
+++ b/pkgs/build-support/testers/testEqualArrayOrMap/build-command.sh
@@ -0,0 +1,64 @@
+# shellcheck shell=bash
+
+set -eu
+
+preScript() {
+  # If neither expectedArray nor expectedMap are declared, the test is meaningless.
+  if ! isDeclaredArray expectedArray && ! isDeclaredMap expectedMap; then
+    nixErrorLog "neither expectedArray nor expectedMap were set, so test is meaningless!"
+    exit 1
+  fi
+
+  if isDeclaredArray valuesArray; then
+    # shellcheck disable=SC2154
+    nixLog "using valuesArray: $(declare -p valuesArray)"
+  fi
+
+  if isDeclaredMap valuesMap; then
+    # shellcheck disable=SC2154
+    nixLog "using valuesMap: $(declare -p valuesMap)"
+  fi
+
+  if isDeclaredArray expectedArray; then
+    # shellcheck disable=SC2154
+    nixLog "using expectedArray: $(declare -p expectedArray)"
+    declare -ag actualArray=()
+  fi
+
+  if isDeclaredMap expectedMap; then
+    # shellcheck disable=SC2154
+    nixLog "using expectedMap: $(declare -p expectedMap)"
+    declare -Ag actualMap=()
+  fi
+
+  return 0
+}
+
+scriptPhase() {
+  runHook preScript
+
+  runHook script
+
+  runHook postScript
+}
+
+postScript() {
+  if isDeclaredArray expectedArray; then
+    nixLog "using actualArray: $(declare -p actualArray)"
+    nixLog "comparing actualArray against expectedArray"
+    assertEqualArray expectedArray actualArray
+    nixLog "actualArray matches expectedArray"
+  fi
+
+  if isDeclaredMap expectedMap; then
+    nixLog "using actualMap: $(declare -p actualMap)"
+    nixLog "comparing actualMap against expectedMap"
+    assertEqualMap expectedMap actualMap
+    nixLog "actualMap matches expectedMap"
+  fi
+
+  return 0
+}
+
+runHook scriptPhase
+touch "${out:?}"
diff --git a/pkgs/build-support/testers/testEqualArrayOrMap/tester.nix b/pkgs/build-support/testers/testEqualArrayOrMap/tester.nix
index 73f8972c0eb6..34373b01db3c 100644
--- a/pkgs/build-support/testers/testEqualArrayOrMap/tester.nix
+++ b/pkgs/build-support/testers/testEqualArrayOrMap/tester.nix
@@ -3,12 +3,10 @@
 # our negative tests will not work. See ./tests.nix for more information.
 {
   lib,
-  runCommand,
+  stdenvNoCC,
 }:
 let
-  inherit (lib) maintainers;
   inherit (lib.customisation) makeOverridable;
-  inherit (lib.strings) optionalString;
 
   testEqualArrayOrMap =
     {
@@ -17,76 +15,25 @@ let
       valuesMap ? null,
       expectedArray ? null,
       expectedMap ? null,
-      checkSetupScript ? ''
-        nixErrorLog "no checkSetupScript provided!"
-        exit 1
-      '',
+      script,
     }:
-    runCommand name
-      {
-        __structuredAttrs = true;
-        strictDeps = true;
+    stdenvNoCC.mkDerivation (finalAttrs: {
+      __structuredAttrs = true;
+      strictDeps = true;
 
-        nativeBuildInputs = [
-          ./assert-equal-array.sh
-          ./assert-equal-map.sh
-        ];
+      inherit name;
 
-        inherit valuesArray valuesMap;
-        inherit expectedArray expectedMap;
+      nativeBuildInputs = [
+        ./assert-equal-array.sh
+        ./assert-equal-map.sh
+      ];
 
-        preCheckSetupScript =
-          optionalString (expectedArray == null && expectedMap == null) ''
-            nixErrorLog "neither expectedArray nor expectedMap were set, so test is meaningless!"
-            exit 1
-          ''
-          + optionalString (valuesArray != null) ''
-            nixLog "using valuesArray: $(declare -p valuesArray)"
-          ''
-          + optionalString (valuesMap != null) ''
-            nixLog "using valuesMap: $(declare -p valuesMap)"
-          ''
-          + optionalString (expectedArray != null) ''
-            nixLog "using expectedArray: $(declare -p expectedArray)"
-            declare -ag actualArray
-          ''
-          + optionalString (expectedMap != null) ''
-            nixLog "using expectedMap: $(declare -p expectedMap)"
-            declare -Ag actualMap
-          '';
+      inherit valuesArray valuesMap;
+      inherit expectedArray expectedMap;
 
-        # NOTE:
-        # The singular task of checkSetupScript is to populate actualArray or actualMap. To do this, checkSetupScript
-        # may access valuesArray, valuesMap, actualArray, and actualMap, but should *never* access or modify expectedArray,
-        # or expectedMap.
-        inherit checkSetupScript;
+      inherit script;
 
-        postCheckSetupScript =
-          optionalString (expectedArray != null) ''
-            nixLog "using actualArray: $(declare -p actualArray)"
-            nixLog "comparing actualArray against expectedArray"
-            assertEqualArray expectedArray actualArray
-            nixLog "actualArray matches expectedArray"
-          ''
-          + optionalString (expectedMap != null) ''
-            nixLog "using actualMap: $(declare -p actualMap)"
-            nixLog "comparing actualMap against expectedMap"
-            assertEqualMap expectedMap actualMap
-            nixLog "actualMap matches expectedMap"
-          '';
-      }
-      ''
-        nixLog "running preCheckSetupScript"
-        runHook preCheckSetupScript
-
-        nixLog "running checkSetupScript"
-        runHook checkSetupScript
-
-        nixLog "running postCheckSetupScript"
-        runHook postCheckSetupScript
-
-        nixLog "test passed"
-        touch "$out"
-      '';
+      buildCommandPath = ./build-command.sh;
+    });
 in
 makeOverridable testEqualArrayOrMap
diff --git a/pkgs/build-support/testers/testEqualArrayOrMap/tests.nix b/pkgs/build-support/testers/testEqualArrayOrMap/tests.nix
index 92888151d43e..bcb2a176a424 100644
--- a/pkgs/build-support/testers/testEqualArrayOrMap/tests.nix
+++ b/pkgs/build-support/testers/testEqualArrayOrMap/tests.nix
@@ -33,7 +33,7 @@ in
       "cowbell"
       "cowbell"
     ];
-    checkSetupScript = ''
+    script = ''
       addCowbell() {
         local -rn arrayNameRef="$1"
         arrayNameRef+=( "cowbell" )
@@ -61,7 +61,7 @@ in
       "cat"
       "dog"
     ];
-    checkSetupScript = ''
+    script = ''
       ${concatValuesArrayToActualArray}
       actualArray+=( "dog" )
     '';
@@ -79,7 +79,7 @@ in
       "bee"
       "cat"
     ];
-    checkSetupScript = ''
+    script = ''
       actualArray+=( "dog" )
       ${concatValuesArrayToActualArray}
     '';
@@ -92,7 +92,7 @@ in
       "cat"
     ];
     expectedArray = [ ];
-    checkSetupScript = ''
+    script = ''
       # doing nothing
     '';
   };
@@ -103,7 +103,7 @@ in
         name = "${name}-failure";
         valuesArray = [ "apple" ];
         expectedArray = [ ];
-        checkSetupScript = concatValuesArrayToActualArray;
+        script = concatValuesArrayToActualArray;
       };
     in
     runCommand name
@@ -140,7 +140,7 @@ in
       cat = "2";
       dog = "3";
     };
-    checkSetupScript = ''
+    script = ''
       ${concatValuesMapToActualMap}
       actualMap["dog"]="3"
     '';
@@ -158,7 +158,7 @@ in
       cat = "2";
       dog = "3";
     };
-    checkSetupScript = ''
+    script = ''
       ${concatValuesMapToActualMap}
       unset 'actualMap[bee]'
     '';
@@ -179,7 +179,7 @@ in
           cat = "2";
           dog = "3";
         };
-        checkSetupScript = concatValuesMapToActualMap;
+        script = concatValuesMapToActualMap;
       };
     in
     runCommand name
@@ -210,9 +210,7 @@ in
         name = "${name}-failure";
         valuesArray = [ ];
         expectedMap.apple = 1;
-        checkSetupScript = ''
-          nixLog "doing nothing in checkSetupScript"
-        '';
+        script = "";
       };
     in
     runCommand name
@@ -252,7 +250,7 @@ in
           bee = "1";
           dog = "3";
         };
-        checkSetupScript = concatValuesMapToActualMap;
+        script = concatValuesMapToActualMap;
       };
     in
     runCommand

From 1a47f317c22fc2a0bb1a8d0a38d40b4d9770f319 Mon Sep 17 00:00:00 2001
From: Connor Baker <ConnorBaker01@gmail.com>
Date: Thu, 20 Feb 2025 23:18:13 +0000
Subject: [PATCH 03/10] testers.testEqualArrayOrMap: remove old comment

---
 pkgs/build-support/testers/testEqualArrayOrMap/tester.nix | 2 --
 1 file changed, 2 deletions(-)

diff --git a/pkgs/build-support/testers/testEqualArrayOrMap/tester.nix b/pkgs/build-support/testers/testEqualArrayOrMap/tester.nix
index 34373b01db3c..3a3a008eb82f 100644
--- a/pkgs/build-support/testers/testEqualArrayOrMap/tester.nix
+++ b/pkgs/build-support/testers/testEqualArrayOrMap/tester.nix
@@ -1,6 +1,4 @@
 # NOTE: Must be `import`-ed rather than `callPackage`-d to preserve the `override` attribute.
-# NOTE: We must use `pkgs.runCommand` instead of `testers.runCommand` to build `testers.testEqualArrayOrMap`, or else
-# our negative tests will not work. See ./tests.nix for more information.
 {
   lib,
   stdenvNoCC,

From c80dc38159bc0a86d6a0aaed143e678a379668bb Mon Sep 17 00:00:00 2001
From: Connor Baker <ConnorBaker01@gmail.com>
Date: Fri, 21 Feb 2025 10:14:31 -0800
Subject: [PATCH 04/10] testers.testEqualArrayOrMap: remove unused finalAttrs

---
 pkgs/build-support/testers/testEqualArrayOrMap/tester.nix | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/pkgs/build-support/testers/testEqualArrayOrMap/tester.nix b/pkgs/build-support/testers/testEqualArrayOrMap/tester.nix
index 3a3a008eb82f..d72893c49bdb 100644
--- a/pkgs/build-support/testers/testEqualArrayOrMap/tester.nix
+++ b/pkgs/build-support/testers/testEqualArrayOrMap/tester.nix
@@ -15,7 +15,7 @@ let
       expectedMap ? null,
       script,
     }:
-    stdenvNoCC.mkDerivation (finalAttrs: {
+    stdenvNoCC.mkDerivation {
       __structuredAttrs = true;
       strictDeps = true;
 
@@ -32,6 +32,6 @@ let
       inherit script;
 
       buildCommandPath = ./build-command.sh;
-    });
+    };
 in
 makeOverridable testEqualArrayOrMap

From abf9e606cfab600eeafc06be495f229f2b275cc6 Mon Sep 17 00:00:00 2001
From: Connor Baker <ConnorBaker01@gmail.com>
Date: Fri, 21 Feb 2025 10:22:09 -0800
Subject: [PATCH 05/10] testers.testEqualArrayOrMap: move argument check from
 bash to Nix

---
 .../testers/testEqualArrayOrMap/build-command.sh         | 9 +++------
 .../build-support/testers/testEqualArrayOrMap/tester.nix | 4 ++++
 2 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/pkgs/build-support/testers/testEqualArrayOrMap/build-command.sh b/pkgs/build-support/testers/testEqualArrayOrMap/build-command.sh
index b1733692d1e9..3ea8300c8c72 100644
--- a/pkgs/build-support/testers/testEqualArrayOrMap/build-command.sh
+++ b/pkgs/build-support/testers/testEqualArrayOrMap/build-command.sh
@@ -2,13 +2,10 @@
 
 set -eu
 
-preScript() {
-  # If neither expectedArray nor expectedMap are declared, the test is meaningless.
-  if ! isDeclaredArray expectedArray && ! isDeclaredMap expectedMap; then
-    nixErrorLog "neither expectedArray nor expectedMap were set, so test is meaningless!"
-    exit 1
-  fi
+# NOTE: If neither expectedArray nor expectedMap are declared, the test is meaningless.
+# This precondition is checked in the Nix expression through an assert.
 
+preScript() {
   if isDeclaredArray valuesArray; then
     # shellcheck disable=SC2154
     nixLog "using valuesArray: $(declare -p valuesArray)"
diff --git a/pkgs/build-support/testers/testEqualArrayOrMap/tester.nix b/pkgs/build-support/testers/testEqualArrayOrMap/tester.nix
index d72893c49bdb..1ac1bb42b73f 100644
--- a/pkgs/build-support/testers/testEqualArrayOrMap/tester.nix
+++ b/pkgs/build-support/testers/testEqualArrayOrMap/tester.nix
@@ -4,6 +4,7 @@
   stdenvNoCC,
 }:
 let
+  inherit (lib.asserts) assertMsg;
   inherit (lib.customisation) makeOverridable;
 
   testEqualArrayOrMap =
@@ -15,6 +16,9 @@ let
       expectedMap ? null,
       script,
     }:
+    assert assertMsg (
+      expectedArray != null || expectedMap != null
+    ) "testEqualArrayOrMap: at least one of 'expectedArray' or 'expectedMap' must be provided";
     stdenvNoCC.mkDerivation {
       __structuredAttrs = true;
       strictDeps = true;

From 4e6be8f313fd604821162a63902f018037ed6c45 Mon Sep 17 00:00:00 2001
From: Connor Baker <ConnorBaker01@gmail.com>
Date: Fri, 21 Feb 2025 12:10:17 -0800
Subject: [PATCH 06/10] testers.testEqualArrayOrMap: use default.nix and move
 recurseIntoAttrs into tests.nix

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

diff --git a/pkgs/build-support/testers/default.nix b/pkgs/build-support/testers/default.nix
index a0ebc7061488..7686aceddf8a 100644
--- a/pkgs/build-support/testers/default.nix
+++ b/pkgs/build-support/testers/default.nix
@@ -72,7 +72,7 @@
   # See https://nixos.org/manual/nixpkgs/unstable/#tester-testEqualArrayOrMap
   # or doc/build-helpers/testers.chapter.md
   # NOTE: Must be `import`-ed rather than `callPackage`-d to preserve the `override` attribute.
-  testEqualArrayOrMap = import ./testEqualArrayOrMap/tester.nix { inherit lib stdenvNoCC; };
+  testEqualArrayOrMap = import ./testEqualArrayOrMap { inherit lib stdenvNoCC; };
 
   # See https://nixos.org/manual/nixpkgs/unstable/#tester-testVersion
   # 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 2bd3d1247817..b9a815cb81dc 100644
--- a/pkgs/build-support/testers/test/default.nix
+++ b/pkgs/build-support/testers/test/default.nix
@@ -357,5 +357,5 @@ lib.recurseIntoAttrs {
       '';
   };
 
-  testEqualArrayOrMap = lib.recurseIntoAttrs (pkgs.callPackages ../testEqualArrayOrMap/tests.nix { });
+  testEqualArrayOrMap = pkgs.callPackages ../testEqualArrayOrMap/tests.nix { };
 }
diff --git a/pkgs/build-support/testers/testEqualArrayOrMap/tester.nix b/pkgs/build-support/testers/testEqualArrayOrMap/default.nix
similarity index 100%
rename from pkgs/build-support/testers/testEqualArrayOrMap/tester.nix
rename to pkgs/build-support/testers/testEqualArrayOrMap/default.nix
diff --git a/pkgs/build-support/testers/testEqualArrayOrMap/tests.nix b/pkgs/build-support/testers/testEqualArrayOrMap/tests.nix
index bcb2a176a424..2202c8ab82d8 100644
--- a/pkgs/build-support/testers/testEqualArrayOrMap/tests.nix
+++ b/pkgs/build-support/testers/testEqualArrayOrMap/tests.nix
@@ -2,8 +2,13 @@
 # `testers.testBuildFailure`. This is due to the fact that `testers.testBuildFailure` modifies the derivation such that
 # it produces an output containing the exit code, logs, and other things. Since `testers.runCommand` expects the empty
 # derivation, it produces a hash mismatch.
-{ runCommand, testers, ... }:
+{
+  lib,
+  runCommand,
+  testers,
+}:
 let
+  inherit (lib.attrsets) recurseIntoAttrs;
   inherit (testers) testEqualArrayOrMap testBuildFailure;
   concatValuesArrayToActualArray = ''
     nixLog "appending all values in valuesArray to actualArray"
@@ -18,7 +23,7 @@ let
     done
   '';
 in
-{
+recurseIntoAttrs {
   # NOTE: This particular test is used in the docs:
   # See https://nixos.org/manual/nixpkgs/unstable/#tester-testEqualArrayOrMap
   # or doc/build-helpers/testers.chapter.md

From 40019a5e1477950340f37148ac7e8a3308245d18 Mon Sep 17 00:00:00 2001
From: Connor Baker <ConnorBaker01@gmail.com>
Date: Tue, 25 Feb 2025 22:41:28 +0000
Subject: [PATCH 07/10] testers.testEqualArrayOrMap: unwrap namerefs before
 passing to avoid nesting

---
 .../testers/testEqualArrayOrMap/assert-equal-array.sh         | 4 ++--
 .../testers/testEqualArrayOrMap/assert-equal-map.sh           | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/pkgs/build-support/testers/testEqualArrayOrMap/assert-equal-array.sh b/pkgs/build-support/testers/testEqualArrayOrMap/assert-equal-array.sh
index 92fa981e44ee..ef43dedba625 100644
--- a/pkgs/build-support/testers/testEqualArrayOrMap/assert-equal-array.sh
+++ b/pkgs/build-support/testers/testEqualArrayOrMap/assert-equal-array.sh
@@ -18,12 +18,12 @@ assertEqualArray() {
   local -nr expectedArrayRef="$1"
   local -nr actualArrayRef="$2"
 
-  if ! isDeclaredArray expectedArrayRef; then
+  if ! isDeclaredArray "${!expectedArrayRef}"; then
     nixErrorLog "first arugment expectedArrayRef must be an array reference to a declared array"
     exit 1
   fi
 
-  if ! isDeclaredArray actualArrayRef; then
+  if ! isDeclaredArray "${!actualArrayRef}"; then
     nixErrorLog "second arugment actualArrayRef must be an array reference to a declared array"
     exit 1
   fi
diff --git a/pkgs/build-support/testers/testEqualArrayOrMap/assert-equal-map.sh b/pkgs/build-support/testers/testEqualArrayOrMap/assert-equal-map.sh
index f66fab4f8468..b601f9e424e9 100644
--- a/pkgs/build-support/testers/testEqualArrayOrMap/assert-equal-map.sh
+++ b/pkgs/build-support/testers/testEqualArrayOrMap/assert-equal-map.sh
@@ -18,12 +18,12 @@ assertEqualMap() {
   local -nr expectedMapRef="$1"
   local -nr actualMapRef="$2"
 
-  if ! isDeclaredMap expectedMapRef; then
+  if ! isDeclaredMap "${!expectedMapRef}"; then
     nixErrorLog "first arugment expectedMapRef must be an associative array reference to a declared associative array"
     exit 1
   fi
 
-  if ! isDeclaredMap actualMapRef; then
+  if ! isDeclaredMap "${!actualMapRef}"; then
     nixErrorLog "second arugment actualMapRef must be an associative array reference to a declared associative array"
     exit 1
   fi

From 12ffaa4e85fa84a04375acf68090b1d6f37e7aed Mon Sep 17 00:00:00 2001
From: Connor Baker <ConnorBaker01@gmail.com>
Date: Thu, 27 Feb 2025 18:05:11 +0000
Subject: [PATCH 08/10] testers.testEqualArrayOrMap: switch to callPackage

---
 pkgs/build-support/testers/default.nix                     | 3 +--
 pkgs/build-support/testers/testEqualArrayOrMap/default.nix | 1 -
 2 files changed, 1 insertion(+), 3 deletions(-)

diff --git a/pkgs/build-support/testers/default.nix b/pkgs/build-support/testers/default.nix
index 7686aceddf8a..693264dd494f 100644
--- a/pkgs/build-support/testers/default.nix
+++ b/pkgs/build-support/testers/default.nix
@@ -71,8 +71,7 @@
 
   # See https://nixos.org/manual/nixpkgs/unstable/#tester-testEqualArrayOrMap
   # or doc/build-helpers/testers.chapter.md
-  # NOTE: Must be `import`-ed rather than `callPackage`-d to preserve the `override` attribute.
-  testEqualArrayOrMap = import ./testEqualArrayOrMap { inherit lib stdenvNoCC; };
+  testEqualArrayOrMap = callPackage ./testEqualArrayOrMap { };
 
   # See https://nixos.org/manual/nixpkgs/unstable/#tester-testVersion
   # or doc/build-helpers/testers.chapter.md
diff --git a/pkgs/build-support/testers/testEqualArrayOrMap/default.nix b/pkgs/build-support/testers/testEqualArrayOrMap/default.nix
index 1ac1bb42b73f..1fccacdf0c3a 100644
--- a/pkgs/build-support/testers/testEqualArrayOrMap/default.nix
+++ b/pkgs/build-support/testers/testEqualArrayOrMap/default.nix
@@ -1,4 +1,3 @@
-# NOTE: Must be `import`-ed rather than `callPackage`-d to preserve the `override` attribute.
 {
   lib,
   stdenvNoCC,

From b2bb4944104b81ff6b511125c7b3b70947c8b241 Mon Sep 17 00:00:00 2001
From: Connor Baker <ConnorBaker01@gmail.com>
Date: Thu, 27 Feb 2025 18:06:43 +0000
Subject: [PATCH 09/10] testers.testEqualArrayOrMap: inline let expression

---
 .../testers/testEqualArrayOrMap/default.nix   | 57 +++++++++----------
 1 file changed, 26 insertions(+), 31 deletions(-)

diff --git a/pkgs/build-support/testers/testEqualArrayOrMap/default.nix b/pkgs/build-support/testers/testEqualArrayOrMap/default.nix
index 1fccacdf0c3a..4dc17d0e2b58 100644
--- a/pkgs/build-support/testers/testEqualArrayOrMap/default.nix
+++ b/pkgs/build-support/testers/testEqualArrayOrMap/default.nix
@@ -2,39 +2,34 @@
   lib,
   stdenvNoCC,
 }:
-let
-  inherit (lib.asserts) assertMsg;
-  inherit (lib.customisation) makeOverridable;
+lib.makeOverridable (
+  {
+    name,
+    valuesArray ? null,
+    valuesMap ? null,
+    expectedArray ? null,
+    expectedMap ? null,
+    script,
+  }:
+  assert lib.assertMsg (
+    expectedArray != null || expectedMap != null
+  ) "testEqualArrayOrMap: at least one of 'expectedArray' or 'expectedMap' must be provided";
+  stdenvNoCC.mkDerivation {
+    __structuredAttrs = true;
+    strictDeps = true;
 
-  testEqualArrayOrMap =
-    {
-      name,
-      valuesArray ? null,
-      valuesMap ? null,
-      expectedArray ? null,
-      expectedMap ? null,
-      script,
-    }:
-    assert assertMsg (
-      expectedArray != null || expectedMap != null
-    ) "testEqualArrayOrMap: at least one of 'expectedArray' or 'expectedMap' must be provided";
-    stdenvNoCC.mkDerivation {
-      __structuredAttrs = true;
-      strictDeps = true;
+    inherit name;
 
-      inherit name;
+    nativeBuildInputs = [
+      ./assert-equal-array.sh
+      ./assert-equal-map.sh
+    ];
 
-      nativeBuildInputs = [
-        ./assert-equal-array.sh
-        ./assert-equal-map.sh
-      ];
+    inherit valuesArray valuesMap;
+    inherit expectedArray expectedMap;
 
-      inherit valuesArray valuesMap;
-      inherit expectedArray expectedMap;
+    inherit script;
 
-      inherit script;
-
-      buildCommandPath = ./build-command.sh;
-    };
-in
-makeOverridable testEqualArrayOrMap
+    buildCommandPath = ./build-command.sh;
+  }
+)

From 674c90732c4de6ff43c8859b143b1f59fad85b4e Mon Sep 17 00:00:00 2001
From: Connor Baker <ConnorBaker01@gmail.com>
Date: Wed, 19 Feb 2025 15:51:19 -0800
Subject: [PATCH 10/10] tests.testers.testEqualArrayOrMap: switch to
 testBuildFailure'

---
 .../testers/testEqualArrayOrMap/tests.nix     | 204 ++++++------------
 1 file changed, 62 insertions(+), 142 deletions(-)

diff --git a/pkgs/build-support/testers/testEqualArrayOrMap/tests.nix b/pkgs/build-support/testers/testEqualArrayOrMap/tests.nix
index 2202c8ab82d8..5a382ded7138 100644
--- a/pkgs/build-support/testers/testEqualArrayOrMap/tests.nix
+++ b/pkgs/build-support/testers/testEqualArrayOrMap/tests.nix
@@ -2,14 +2,10 @@
 # `testers.testBuildFailure`. This is due to the fact that `testers.testBuildFailure` modifies the derivation such that
 # it produces an output containing the exit code, logs, and other things. Since `testers.runCommand` expects the empty
 # derivation, it produces a hash mismatch.
-{
-  lib,
-  runCommand,
-  testers,
-}:
+{ lib, testers }:
 let
   inherit (lib.attrsets) recurseIntoAttrs;
-  inherit (testers) testEqualArrayOrMap testBuildFailure;
+  inherit (testers) testBuildFailure' testEqualArrayOrMap;
   concatValuesArrayToActualArray = ''
     nixLog "appending all values in valuesArray to actualArray"
     for value in "''${valuesArray[@]}"; do
@@ -101,37 +97,18 @@ recurseIntoAttrs {
       # doing nothing
     '';
   };
-  array-missing-value =
-    let
+  array-missing-value = testBuildFailure' {
+    drv = testEqualArrayOrMap {
       name = "testEqualArrayOrMap-array-missing-value";
-      failure = testEqualArrayOrMap {
-        name = "${name}-failure";
-        valuesArray = [ "apple" ];
-        expectedArray = [ ];
-        script = concatValuesArrayToActualArray;
-      };
-    in
-    runCommand name
-      {
-        failed = testBuildFailure failure;
-        passthru = {
-          inherit failure;
-        };
-      }
-      ''
-        nixLog "Checking for exit code 1"
-        (( 1 == "$(cat "$failed/testBuildFailure.exit")" ))
-        nixLog "Checking for first error message"
-        grep -F \
-          "ERROR: assertEqualArray: arrays differ in length: expectedArray has length 0 but actualArray has length 1" \
-          "$failed/testBuildFailure.log"
-        nixLog "Checking for second error message"
-        grep -F \
-          "ERROR: assertEqualArray: arrays differ at index 0: expectedArray has no such index but actualArray has value 'apple'" \
-          "$failed/testBuildFailure.log"
-        nixLog "Test passed"
-        touch $out
-      '';
+      valuesArray = [ "apple" ];
+      expectedArray = [ ];
+      script = concatValuesArrayToActualArray;
+    };
+    expectedBuilderLogEntries = [
+      "ERROR: assertEqualArray: arrays differ in length: expectedArray has length 0 but actualArray has length 1"
+      "ERROR: assertEqualArray: arrays differ at index 0: expectedArray has no such index but actualArray has value 'apple'"
+    ];
+  };
   map-insert = testEqualArrayOrMap {
     name = "testEqualArrayOrMap-map-insert";
     valuesMap = {
@@ -168,115 +145,58 @@ recurseIntoAttrs {
       unset 'actualMap[bee]'
     '';
   };
-  map-missing-key =
-    let
+  map-missing-key = testBuildFailure' {
+    drv = testEqualArrayOrMap {
       name = "testEqualArrayOrMap-map-missing-key";
-      failure = testEqualArrayOrMap {
-        name = "${name}-failure";
-        valuesMap = {
-          bee = "1";
-          cat = "2";
-          dog = "3";
-        };
-        expectedMap = {
-          apple = "0";
-          bee = "1";
-          cat = "2";
-          dog = "3";
-        };
-        script = concatValuesMapToActualMap;
+      valuesMap = {
+        bee = "1";
+        cat = "2";
+        dog = "3";
       };
-    in
-    runCommand name
-      {
-        failed = testBuildFailure failure;
-        passthru = {
-          inherit failure;
-        };
-      }
-      ''
-        nixLog "Checking for exit code 1"
-        (( 1 == "$(cat "$failed/testBuildFailure.exit")" ))
-        nixLog "Checking for first error message"
-        grep -F \
-          "ERROR: assertEqualMap: maps differ in length: expectedMap has length 4 but actualMap has length 3" \
-          "$failed/testBuildFailure.log"
-        nixLog "Checking for second error message"
-        grep -F \
-          "ERROR: assertEqualMap: maps differ at key 'apple': expectedMap has value '0' but actualMap has no such key" \
-          "$failed/testBuildFailure.log"
-        nixLog "Test passed"
-        touch $out
-      '';
-  map-missing-key-with-empty =
-    let
-      name = "map-missing-key-with-empty";
-      failure = testEqualArrayOrMap {
-        name = "${name}-failure";
-        valuesArray = [ ];
-        expectedMap.apple = 1;
-        script = "";
+      expectedMap = {
+        apple = "0";
+        bee = "1";
+        cat = "2";
+        dog = "3";
       };
-    in
-    runCommand name
-      {
-        failed = testBuildFailure failure;
-        passthru = {
-          inherit failure;
-        };
-      }
-      ''
-        nixLog "Checking for exit code 1"
-        (( 1 == "$(cat "$failed/testBuildFailure.exit")" ))
-        nixLog "Checking for first error message"
-        grep -F \
-          "ERROR: assertEqualMap: maps differ in length: expectedMap has length 1 but actualMap has length 0" \
-          "$failed/testBuildFailure.log"
-        nixLog "Checking for second error message"
-        grep -F \
-          "ERROR: assertEqualMap: maps differ at key 'apple': expectedMap has value '1' but actualMap has no such key" \
-          "$failed/testBuildFailure.log"
-        nixLog "Test passed"
-        touch $out
-      '';
-  map-extra-key =
-    let
+      script = concatValuesMapToActualMap;
+    };
+    expectedBuilderLogEntries = [
+      "ERROR: assertEqualMap: maps differ in length: expectedMap has length 4 but actualMap has length 3"
+      "ERROR: assertEqualMap: maps differ at key 'apple': expectedMap has value '0' but actualMap has no such key"
+    ];
+  };
+  map-missing-key-with-empty = testBuildFailure' {
+    drv = testEqualArrayOrMap {
+      name = "testEqualArrayOrMap-map-missing-key-with-empty";
+      valuesArray = [ ];
+      expectedMap.apple = 1;
+      script = "";
+    };
+    expectedBuilderLogEntries = [
+      "ERROR: assertEqualMap: maps differ in length: expectedMap has length 1 but actualMap has length 0"
+      "ERROR: assertEqualMap: maps differ at key 'apple': expectedMap has value '1' but actualMap has no such key"
+    ];
+  };
+  map-extra-key = testBuildFailure' {
+    drv = testEqualArrayOrMap {
       name = "testEqualArrayOrMap-map-extra-key";
-      failure = testEqualArrayOrMap {
-        name = "${name}-failure";
-        valuesMap = {
-          apple = "0";
-          bee = "1";
-          cat = "2";
-          dog = "3";
-        };
-        expectedMap = {
-          apple = "0";
-          bee = "1";
-          dog = "3";
-        };
-        script = concatValuesMapToActualMap;
+      valuesMap = {
+        apple = "0";
+        bee = "1";
+        cat = "2";
+        dog = "3";
       };
-    in
-    runCommand
-      {
-        failed = testBuildFailure failure;
-        passthru = {
-          inherit failure;
-        };
-      }
-      ''
-        nixLog "Checking for exit code 1"
-        (( 1 == "$(cat "$failed/testBuildFailure.exit")" ))
-        nixLog "Checking for first error message"
-        grep -F \
-          "ERROR: assertEqualMap: maps differ in length: expectedMap has length 3 but actualMap has length 4" \
-          "$failed/testBuildFailure.log"
-        nixLog "Checking for second error message"
-        grep -F \
-          "ERROR: assertEqualMap: maps differ at key 'cat': expectedMap has no such key but actualMap has value '2'" \
-          "$failed/testBuildFailure.log"
-        nixLog "Test passed"
-        touch $out
-      '';
+      expectedMap = {
+        apple = "0";
+        bee = "1";
+        dog = "3";
+      };
+      script = concatValuesMapToActualMap;
+    };
+    expectedBuilderLogEntries = [
+      "ERROR: assertEqualMap: maps differ in length: expectedMap has length 3 but actualMap has length 4"
+      "ERROR: assertEqualMap: maps differ at key 'cat': expectedMap has no such key but actualMap has value '2'"
+    ];
+  };
 }