diff --git a/doc/build-helpers/testers.chapter.md b/doc/build-helpers/testers.chapter.md
index 344f4dc75dfd..d4e33b04f3e9 100644
--- a/doc/build-helpers/testers.chapter.md
+++ b/doc/build-helpers/testers.chapter.md
@@ -405,6 +405,22 @@ The tester produces an empty output and only succeeds when the checks using `exp
 
 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
@@ -427,6 +443,11 @@ testers.testEqualContents {
       ''
         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.
+  '';
 }
 ```
 
@@ -695,3 +716,5 @@ Notable attributes:
  * `nodes`: the evaluated NixOS configurations. Useful for debugging and exploring the configuration.
 
  * `driverInteractive`: a script that launches an interactive Python session in the context of the `testScript`.
+
+[file system object]: https://nix.dev/manual/nix/latest/store/file-system-object
diff --git a/pkgs/build-support/testers/default.nix b/pkgs/build-support/testers/default.nix
index ca6731722ec1..9bd25940a194 100644
--- a/pkgs/build-support/testers/default.nix
+++ b/pkgs/build-support/testers/default.nix
@@ -56,10 +56,16 @@
       assertion,
       actual,
       expected,
+      postFailureMessage ? null,
     }:
     runCommand "equal-contents-${lib.strings.toLower assertion}"
       {
-        inherit assertion actual expected;
+        inherit
+          assertion
+          actual
+          expected
+          postFailureMessage
+          ;
         nativeBuildInputs = [ diffoscopeMinimal ];
       }
       ''
@@ -69,6 +75,10 @@
         then
           echo
           echo 'Contents must be equal, but were not!'
+          if [[ -n "''${postFailureMessage:-}" ]]; then
+            echo
+            echo "$postFailureMessage"
+          fi
           echo
           echo "+: expected,   at $expected"
           echo "-: unexpected, at $actual"
diff --git a/pkgs/build-support/testers/test/default.nix b/pkgs/build-support/testers/test/default.nix
index 67e11da2383b..739f415d7670 100644
--- a/pkgs/build-support/testers/test/default.nix
+++ b/pkgs/build-support/testers/test/default.nix
@@ -270,22 +270,40 @@ lib.recurseIntoAttrs {
       '';
     };
 
-    fileMissing = testers.testBuildFailure (
-      testers.testEqualContents {
-        assertion = "Directories with different file list are not recognized as equal";
-        expected = runCommand "expected" { } ''
-          mkdir -p -- "$out/c"
-          echo a >"$out/a"
-          echo b >"$out/b"
-          echo d >"$out/c/d"
+    # - Test whether a missing file triggers a failure as expected
+    # - Test the postFailureMessage
+    fileMissing =
+      let
+        log = testers.testBuildFailure (
+          testers.testEqualContents {
+            assertion = "Directories with different file list are not recognized as equal";
+            expected = runCommand "expected" { } ''
+              mkdir -p -- "$out/c"
+              echo a >"$out/a"
+              echo b >"$out/b"
+              echo d >"$out/c/d"
+            '';
+            actual = runCommand "actual" { } ''
+              mkdir -p -- "$out/c"
+              echo a >"$out/a"
+              echo d >"$out/c/d"
+            '';
+            inherit postFailureMessage;
+          }
+        );
+        postFailureMessage = ''
+          If after careful review, you find that the changes are acceptable, run `suchandsuch` to adopt the new behavior.
         '';
-        actual = runCommand "actual" { } ''
-          mkdir -p -- "$out/c"
-          echo a >"$out/a"
-          echo d >"$out/c/d"
+      in
+      runCommand "fileMissing-failure-and-log-check"
+        {
+          inherit log;
+          inherit postFailureMessage;
+        }
+        ''
+          grep -F "$postFailureMessage" "$log/testBuildFailure.log"
+          touch $out
         '';
-      }
-    );
 
     equalExe = testers.testEqualContents {
       assertion = "The same executable file contents at different paths are recognized as equal";