diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9668e76e023..23c75b934d1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -369,35 +369,13 @@ or run tests which contain names that match a specific keyword expression: Writing an image-based test is only slightly more difficult than a simple test. The main consideration is that you must specify the "baseline" or reference image, and compare it with a "generated" or test image. This is handled using -the *decorator* functions `@check_figures_equal` and -`@pytest.mark.mpl_image_compare` whose usage are further described below. - -#### Using check_figures_equal - -This approach draws the same figure using two different methods (the reference -method and the tested method), and checks that both of them are the same. -It takes two `pygmt.Figure` objects ('fig_ref' and 'fig_test'), generates a png -image, and checks for the Root Mean Square (RMS) error between the two. -Here's an example: - -```python -@check_figures_equal() -def test_my_plotting_case(): - "Test that my plotting function works" - fig_ref, fig_test = Figure(), Figure() - fig_ref.grdimage("@earth_relief_01d_g", projection="W120/15c", cmap="geo") - fig_test.grdimage(grid, projection="W120/15c", cmap="geo") - return fig_ref, fig_test -``` - -Note: This is the recommended way to test plots whenever possible, such as when -we want to compare a reference GMT plot created from NetCDF files with one -generated by PyGMT that passes through several layers of virtualfile machinery. -Using this method will help save space in the git repository by not having to -store baseline images as with the other method below. +the *decorator* functions `@pytest.mark.mpl_image_compare` and `@check_figures_equal` +whose usage are further described below. #### Using mpl_image_compare +> **This is the preferred way to test plots whenever possible.** + This method uses the [pytest-mpl](https://github.com/matplotlib/pytest-mpl) plug-in to test plot generating code. Every time the tests are run, `pytest-mpl` compares the generated plots with known @@ -502,6 +480,24 @@ summarized as follows: git push dvc push +#### Using check_figures_equal + +This approach draws the same figure using two different methods (the reference +method and the tested method), and checks that both of them are the same. +It takes two `pygmt.Figure` objects ('fig_ref' and 'fig_test'), generates a png +image, and checks for the Root Mean Square (RMS) error between the two. +Here's an example: + +```python +@check_figures_equal() +def test_my_plotting_case(): + "Test that my plotting function works" + fig_ref, fig_test = Figure(), Figure() + fig_ref.grdimage("@earth_relief_01d_g", projection="W120/15c", cmap="geo") + fig_test.grdimage(grid, projection="W120/15c", cmap="geo") + return fig_ref, fig_test +``` + ### Documentation #### Building the documentation