Document the text_placeholders fixture

QuLogic · timhoffm · QuLogic · commit 3d0fd3c1d842 · 2025-04-10T14:51:57.000-04:00
Co-authored-by: Tim Hoffmann &lt;2836374+timhoffm@users.noreply.github.com&gt;
diff --git a/doc/devel/testing.rst b/doc/devel/testing.rst
@@ -163,9 +163,10 @@ the tests, they should now pass.
 
 It is preferred that new tests use ``style='mpl20'`` as this leads to smaller
 figures and reflects the newer look of default Matplotlib plots. Also, if the
-texts (labels, tick labels, etc) are not really part of what is tested, use
-``remove_text=True`` as this will lead to smaller figures and reduce possible
-issues with font mismatch on different platforms.
+texts (labels, tick labels, etc) are not really part of what is tested, use the
+``remove_text=True`` argument or add the ``text_placeholders`` fixture as this
+will lead to smaller figures and reduce possible issues with font mismatch on
+different platforms.
 
 
 Compare two methods of creating an image
diff --git a/lib/matplotlib/testing/conftest.py b/lib/matplotlib/testing/conftest.py
@@ -129,6 +129,14 @@ def test_imshow_xarray(xr):
 
 @pytest.fixture
 def text_placeholders(monkeypatch):
+    """
+    Replace texts with placeholder rectangles.
+
+    The rectangle size only depends on the font size and the number of characters. It is
+    thus insensitive to font properties and rendering details. This should be used for
+    tests that depend on text geometries but not the actual text rendering, e.g. layout
+    tests.
+    """
     from matplotlib.patches import Rectangle
 
     def patched_get_text_metrics_with_cache(renderer, text, fontprop, ismath, dpi):
