test.testers.testEqualArrayOrMap: switch to testBuildFailure'

doc/build-helpers/testers.chapter.md

@@ -255,6 +255,70 @@ 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`.
+
+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" { } ''
+    echo ok-ish >"$out"
+    echo failing though
+    exit 3
+  '';
+  expectedBuilderExitCode = 3;
+  expectedBuilderLogEntries = [ "failing though" ];
+  script = ''
+    grep --silent -F 'ok-ish' "$failed/result"
+  '';
+}
+```
+
+:::
+
+### 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.
@@ -283,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 to 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"
+  ];
+  script = ''
+    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 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.
+
+`name` (string)
+
+: The name of the test.
+
+`script` (string)
+
+: 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` (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 `script`, they *must not* be accessed or modified from within `script`.
+
+`valuesArray` (array of string-like values, optional)
+
+: 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-like values.
+  This attribute set may be used within `script`.
+
+`expectedArray` (array of string-like values, optional)
+
+: 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-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}
+
+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.

doc/redirects.json

@@ -8,6 +8,12 @@
   "ex-build-helpers-extendMkDerivation": [
     "index.html#ex-build-helpers-extendMkDerivation"
   ],
+  "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"
   ],
@@ -332,6 +338,24 @@
   "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"
+  ],
+  "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"
   ],

pkgs/build-support/testers/default.nix

@@ -34,6 +34,11 @@
     ] ++ 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
+  # NOTE: Must be `import`-ed rather than `callPackage`-d to preserve the `override` attribute.
+  testBuildFailure' = import ./testBuildFailurePrime { inherit lib stdenvNoCC testers; };
+
   # See https://nixos.org/manual/nixpkgs/unstable/#tester-testEqualDerivation
   # or doc/build-helpers/testers.chapter.md
   testEqualDerivation = callPackage ./test-equal-derivation.nix { };
@@ -65,6 +70,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 { inherit lib stdenvNoCC; };
+
   # See https://nixos.org/manual/nixpkgs/unstable/#tester-testVersion
   # or doc/build-helpers/testers.chapter.md
   testVersion =

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

@@ -220,6 +220,10 @@ lib.recurseIntoAttrs {
     sideEffectStructuredAttrs = overrideStructuredAttrs true sideEffects;
   };
 
+  testBuildFailure' = lib.recurseIntoAttrs (
+    pkgs.callPackages ../testBuildFailurePrime/tests.nix { inherit overrideStructuredAttrs; }
+  );
+
   testEqualContents = lib.recurseIntoAttrs {
     equalDir = testers.testEqualContents {
       assertion = "The same directory contents at different paths are recognized as equal";
@@ -352,4 +356,6 @@ lib.recurseIntoAttrs {
         touch -- "$out"
       '';
   };
+
+  testEqualArrayOrMap = pkgs.callPackages ../testEqualArrayOrMap/tests.nix { };
 }

pkgs/build-support/testers/testBuildFailurePrime/build-command.sh

@@ -0,0 +1,47 @@
+# shellcheck shell=bash
+
+set -eu
+
+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"
+    return 1
+  fi
+}
+
+testBuilderLogEntries() {
+  nixLog "checking original builder log"
+  local -r builderLogEntries="$(<"${failed:?}/testBuildFailure.log")"
+  local -i shouldExit=0
+  local expectedBuilderLogEntry
+  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
+
+  runHook postScript
+}
+
+runHook scriptPhase
+touch "${out:?}"

pkgs/build-support/testers/testBuildFailurePrime/default.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'