diff --git a/docs/Contributors_Guide/testing.rst b/docs/Contributors_Guide/testing.rst index 28574df4d7..f0e10804d4 100644 --- a/docs/Contributors_Guide/testing.rst +++ b/docs/Contributors_Guide/testing.rst @@ -66,30 +66,46 @@ To run only the GridStat unit tests:: Subsetting Tests by Marker ^^^^^^^^^^^^^^^^^^^^^^^^^^ -Unit tests can include one of the custom markers listed in the -internal/tests/pytests/pytest.ini file. Some examples include: - - * diff - * run_metplus - * util - * wrapper_a - * wrapper_b - * wrapper_c - * wrapper_d - * wrapper - * long - * plotting - -To apply a marker to a unit test function, add the following on the line before -the function definition:: +Pytest allows contributors to use markers on test functions. Markers are used +to set various features/attributes to test functions so that users can easily +exclude or include some tests from the test execution. Pytest provides many +inbuilt markers such as xfail, skip and parametrize. Apart from the inbuilt +marker names, users can create their own custom marker names. + +**Creating Pytest Markers** + +The METplus team has defined various custom marker names for the unit tests +and contributors can add to these markers. These custom markers are listed +with a brief description, in the *internal/tests/pytests/pytest.ini* file. +Some examples include: + + * diff (custom marker for diff util tests that require additional packages) + * run_metplus (custom marker for testing run_metplus.py script) + * util (custom marker for testing metplus/util logic) + * long (custom marker for tests that take a long time to run) + * plotting (custom marker for tests that involve plotting) + +To set up unit test functions so that they can be easily excluded or included +from text execution, contributors can add the following on the line before +the function definition in the Python test file:: + @pytest.mark. -where is one of the custom marker strings listed in pytest.ini. +where is one of the custom marker strings listed in the +*internal/tests/pytests/pytest.ini* file. -New pytest markers should be added to the pytest.ini file with a brief -description. If they are not added to the markers list, then a warning will -be output when running the tests. +To see an example of the “util” custom marker (@pytest.mark.util), +look in the file *internal/tests/pytests/util/time_util/test_time_util.py*. + +New pytest markers should be added to the *internal/tests/pytests/pytest.ini* +file with a brief description. If they are not added to the markers list, +then a warning will be output when running the tests. + +**Using Pytest Markers** + +The tests that have associated marker names can be now run to include +or exclude tests based on the given name. To run only tests with a given marker, run::