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.

`assertion` (string)

: A message that is printed before the comparison, after `Checking:`.

`expected` (path or value coercible to store path)

: The path to the expected [file system object] content

`actual` (value coercible to store path) <!-- path value is possible, but wrong in practice, but let's not bother readers with our predictions -->

: The path to the actual file system object content to check

`postFailureMessage` (string)

: A message that is printed last if the file system object contents at the two paths don't match exactly.

:::{.example #ex-testEqualContents-toyexample}

# Check that two paths have the same contents

```nix
testers.testEqualContents {
  assertion = "sed -e performs replacement";
  expected = writeText "expected" ''
    foo baz baz
  '';
  actual =
    runCommand "actual"
      {
        # not really necessary for a package that's in stdenv
        nativeBuildInputs = [ gnused ];
        base = writeText "base" ''
          foo bar baz
        '';
      }
      ''
        sed -e 's/bar/baz/g' $base >$out
      '';
  # if applicable
  postFailureMessage = ''
    The bar-baz replacer produced an unexpected result.
    If the new behavior is acceptable and validated against the bar-baz specification, run ./adopt-new-bar-baz-result.sh to adjust this test and require the new behavior.
  '';
}
```

:::

## `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