|
| 1 | +""" |
| 2 | +Helper functions for testing. |
| 3 | +""" |
| 4 | + |
| 5 | +import inspect |
| 6 | +import os |
| 7 | + |
| 8 | +from matplotlib.testing.compare import compare_images |
| 9 | + |
| 10 | +from ..exceptions import GMTImageComparisonFailure |
| 11 | +from ..figure import Figure |
| 12 | + |
| 13 | + |
| 14 | +def check_figures_equal(*, tol=0.0, result_dir="result_images"): |
| 15 | + """ |
| 16 | + Decorator for test cases that generate and compare two figures. |
| 17 | +
|
| 18 | + The decorated function must take two arguments, *fig_ref* and *fig_test*, |
| 19 | + and draw the reference and test images on them. After the function |
| 20 | + returns, the figures are saved and compared. |
| 21 | +
|
| 22 | + This decorator is practically identical to matplotlib's check_figures_equal |
| 23 | + function, but adapted for PyGMT figures. See also the original code at |
| 24 | + https://matplotlib.org/3.3.1/api/testing_api.html# |
| 25 | + matplotlib.testing.decorators.check_figures_equal |
| 26 | +
|
| 27 | + Parameters |
| 28 | + ---------- |
| 29 | + tol : float |
| 30 | + The RMS threshold above which the test is considered failed. |
| 31 | + result_dir : str |
| 32 | + The directory where the figures will be stored. |
| 33 | +
|
| 34 | + Examples |
| 35 | + -------- |
| 36 | +
|
| 37 | + >>> import pytest |
| 38 | + >>> import shutil |
| 39 | +
|
| 40 | + >>> @check_figures_equal(result_dir="tmp_result_images") |
| 41 | + ... def test_check_figures_equal(fig_ref, fig_test): |
| 42 | + ... fig_ref.basemap(projection="X5c", region=[0, 5, 0, 5], frame=True) |
| 43 | + ... fig_test.basemap(projection="X5c", region=[0, 5, 0, 5], frame="af") |
| 44 | + >>> test_check_figures_equal() |
| 45 | + >>> assert len(os.listdir("tmp_result_images")) == 0 |
| 46 | + >>> shutil.rmtree(path="tmp_result_images") # cleanup folder if tests pass |
| 47 | +
|
| 48 | + >>> @check_figures_equal(result_dir="tmp_result_images") |
| 49 | + ... def test_check_figures_unequal(fig_ref, fig_test): |
| 50 | + ... fig_ref.basemap(projection="X5c", region=[0, 5, 0, 5], frame=True) |
| 51 | + ... fig_test.basemap(projection="X5c", region=[0, 3, 0, 3], frame=True) |
| 52 | + >>> with pytest.raises(GMTImageComparisonFailure): |
| 53 | + ... test_check_figures_unequal() |
| 54 | + >>> for suffix in ["", "-expected", "-failed-diff"]: |
| 55 | + ... assert os.path.exists( |
| 56 | + ... os.path.join( |
| 57 | + ... "tmp_result_images", |
| 58 | + ... f"test_check_figures_unequal{suffix}.png", |
| 59 | + ... ) |
| 60 | + ... ) |
| 61 | + >>> shutil.rmtree(path="tmp_result_images") # cleanup folder if tests pass |
| 62 | + """ |
| 63 | + |
| 64 | + def decorator(func): |
| 65 | + |
| 66 | + os.makedirs(result_dir, exist_ok=True) |
| 67 | + old_sig = inspect.signature(func) |
| 68 | + |
| 69 | + def wrapper(*args, **kwargs): |
| 70 | + try: |
| 71 | + fig_ref = Figure() |
| 72 | + fig_test = Figure() |
| 73 | + func(*args, fig_ref=fig_ref, fig_test=fig_test, **kwargs) |
| 74 | + ref_image_path = os.path.join( |
| 75 | + result_dir, func.__name__ + "-expected.png" |
| 76 | + ) |
| 77 | + test_image_path = os.path.join(result_dir, func.__name__ + ".png") |
| 78 | + fig_ref.savefig(ref_image_path) |
| 79 | + fig_test.savefig(test_image_path) |
| 80 | + |
| 81 | + # Code below is adapted for PyGMT, and is originally based on |
| 82 | + # matplotlib.testing.decorators._raise_on_image_difference |
| 83 | + err = compare_images( |
| 84 | + expected=ref_image_path, |
| 85 | + actual=test_image_path, |
| 86 | + tol=tol, |
| 87 | + in_decorator=True, |
| 88 | + ) |
| 89 | + if err is None: # Images are the same |
| 90 | + os.remove(ref_image_path) |
| 91 | + os.remove(test_image_path) |
| 92 | + else: # Images are not the same |
| 93 | + for key in ["actual", "expected", "diff"]: |
| 94 | + err[key] = os.path.relpath(err[key]) |
| 95 | + raise GMTImageComparisonFailure( |
| 96 | + "images not close (RMS %(rms).3f):\n\t%(actual)s\n\t%(expected)s " |
| 97 | + % err |
| 98 | + ) |
| 99 | + finally: |
| 100 | + del fig_ref |
| 101 | + del fig_test |
| 102 | + |
| 103 | + parameters = [ |
| 104 | + param |
| 105 | + for param in old_sig.parameters.values() |
| 106 | + if param.name not in {"fig_test", "fig_ref"} |
| 107 | + ] |
| 108 | + new_sig = old_sig.replace(parameters=parameters) |
| 109 | + wrapper.__signature__ = new_sig |
| 110 | + |
| 111 | + return wrapper |
| 112 | + |
| 113 | + return decorator |
0 commit comments