DOC/FIX: clarify the docs for check_figures_equal

tacaswell · tacaswell · commit d2328feda9df · 2020-03-27T18:42:43.000-04:00
Clarify that the names matter and add a check with a better exception. closes #16916
diff --git a/lib/matplotlib/testing/decorators.py b/lib/matplotlib/testing/decorators.py
@@ -356,12 +356,11 @@ def image_comparison(baseline_images, extensions=None, tol=0,
 
 
 def check_figures_equal(*, extensions=("png", "pdf", "svg"), tol=0):
-    """
-    Decorator for test cases that generate and compare two figures.
+    """Decorator for test cases that generate and compare two figures.
 
-    The decorated function must take two arguments, *fig_test* and *fig_ref*,
-    and draw the test and reference images on them.  After the function
-    returns, the figures are saved and compared.
+    The decorated function must take two keyword arguments, *fig_test*
+    and *fig_ref*, and draw the test and reference images on them.
+    After the function returns, the figures are saved and compared.
 
     This decorator should be preferred over `image_comparison` when possible in
     order to keep the size of the test suite from ballooning.
@@ -382,6 +381,7 @@ def check_figures_equal(*, extensions=("png", "pdf", "svg"), tol=0):
         def test_plot(fig_test, fig_ref):
             fig_test.subplots().plot([1, 3, 5])
             fig_ref.subplots().plot([0, 1, 2], [1, 3, 5])
+
     """
     ALLOWED_CHARS = set(string.digits + string.ascii_letters + '_-[]()')
     KEYWORD_ONLY = inspect.Parameter.KEYWORD_ONLY
@@ -391,6 +391,11 @@ def decorator(func):
         _, result_dir = _image_directories(func)
         old_sig = inspect.signature(func)
 
+        if not all(k in old_sig.parameters for k in {"fig_test", "fig_ref"}):
+            raise ValueError("The decorated function must have at least the "
+                             "parameters 'fig_ref' and 'fig_test', but your "
+                             f"function has the signature {old_sig}")
+
         @pytest.mark.parametrize("ext", extensions)
         def wrapper(*args, **kwargs):
             ext = kwargs['ext']
diff --git a/lib/matplotlib/tests/test_testing.py b/lib/matplotlib/tests/test_testing.py
@@ -15,3 +15,10 @@ def test_warn_to_fail():
 @pytest.mark.parametrize("b", [1])
 def test_parametrize_with_check_figure_equal(a, fig_ref, b, fig_test):
     assert a == b
+
+
+def test_wrap_failure():
+    with pytest.raises(ValueError, match="^The decorated function"):
+        @check_figures_equal()
+        def should_fail(test, ref):
+            ...
