Warn if a defined pixel difference tolerance is no longer necessary

tests/compare-pdf/README.md

@@ -30,9 +30,10 @@ comparison = ComparePDF(
 Page numbers are one-based.  A tolerated page passes only if the number of
 changed pixels, the greatest individual RGB-channel difference, and the
 greatest combined RGB difference all meet their limits.  The comparator logs
-these diagnostics for every non-exact page and records when a tolerance was
-used.  Command-line comparison remains exact; tolerances are deliberately a
-test-code API for now.
+these diagnostics for every non-exact page, records when a tolerance was
+used, and reports when a configured tolerance was unnecessary because the
+page matched exactly.  Command-line comparison remains exact; tolerances are
+deliberately a test-code API for now.
 
 PDF Visual Comparison Tool
 ==========================

tests/compare-pdf/compare_pdf/compare_pdf.py

@@ -134,7 +134,14 @@ def _display_image(self, image, page_num, mswait):
     def _compare_images(self, images, page_num) -> bool:
         equal = all(np.array_equal(images[0], img) for img in images)
         if equal:
-            self.logger.info(f"All images on Page {page_num} are equal")
+            tolerance = self.page_tolerances.get(page_num)
+            if tolerance is None:
+                self.logger.info(f"All images on Page {page_num} are equal")
+            else:
+                self.logger.info(
+                    "All images on Page %s are equal; the configured page "
+                    "tolerance was not needed. Consider removing or narrowing it. "
+                    "Reason: %s", page_num, tolerance.reason)
             return True
 
         comparison_result = True

tests/testComparePdf/test_comparePdf.py

@@ -60,6 +60,22 @@ def test_page_tolerance_requires_every_limit(caplog):
     assert tolerance.reason in caplog.text
 
 
+def test_exact_page_reports_an_unused_configured_tolerance(caplog):
+    image = np.zeros((2, 2, 3), dtype=np.uint8)
+    tolerance = PageTolerance(
+        max_different_pixels=1,
+        max_channel_difference=1,
+        max_combined_rgb_difference=1,
+        reason='A tolerance that should be reviewed when unused.',
+    )
+
+    with caplog.at_level(logging.INFO, logger='cewe2pdf.test'):
+        assert comparison_with_tolerances({1: tolerance})._compare_images([image, image], 1)
+
+    assert 'tolerance was not needed' in caplog.text
+    assert tolerance.reason in caplog.text
+
+
 def test_page_tolerance_rejects_a_difference_above_any_limit():
     new, approved = one_pixel_difference()
     tolerance = PageTolerance(