Merge branch 'main' into test_guidelines_random_asserts

2 files changed, 17 insertions, 2 deletions

diff --git a/doc/TESTS.rst.txt b/doc/TESTS.rst.txt
index fd8845291..ba09aa800 100644
--- a/doc/TESTS.rst.txt
+++ b/doc/TESTS.rst.txt
@@ -106,6 +106,8 @@ module called ``test_yyy.py``.  If you only need to test one aspect of
 More often, we need to group a number of tests together, so we create
 a test class::
 
+  import pytest
+
   # import xxx symbols
   from numpy.xxx.yyy import zzz
   import pytest
@@ -115,11 +117,23 @@ a test class::
           assert zzz() == 'Hello from zzz'
 
       def test_invalid_parameter(self):
-          with pytest.raises(xxxError, match='expected error message'):
+          with pytest.raises(ValueError, match='.*some matching regex.*'):
               ...
 
 Within these test methods, ``assert`` and related functions are used to test
 whether a certain assumption is valid. If the assertion fails, the test fails.
+``pytest`` internally rewrites the ``assert`` statement to give informative
+output when it fails, so should be preferred over the legacy variant
+``numpy.testing.assert_``. Whereas plain ``assert`` statements are ignored
+when running Python in optimized mode with ``-O``, this is not an issue when
+running tests with pytest.
+
+Similarly, the pytest functions :func:`pytest.raises` and :func:`pytest.warns`
+should be preferred over their legacy counterparts
+:func:`numpy.testing.assert_raises` and :func:`numpy.testing.assert_warns`,
+since the pytest variants are more broadly used and allow more explicit
+targeting of warnings and errors when used with the ``match`` regex.
+
 
 Note that ``test_`` functions or methods should not have a docstring, because
 that makes it hard to identify the test from the output of running the test
@@ -185,7 +199,7 @@ Parametric tests
 
 One very nice feature of testing is allowing easy testing across a range
 of parameters - a nasty problem for standard unit tests. Use the
-``dec.paramaterize`` decorator.
+``pytest.mark.parametrize`` decorator.
 
 Doctests
 --------
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 95865c024..fdb9f926d 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -292,6 +292,7 @@ intersphinx_mapping = {
     'skimage': ('https://scikit-image.org/docs/stable', None),
     'pandas': ('https://pandas.pydata.org/pandas-docs/stable', None),
     'scipy-lecture-notes': ('https://scipy-lectures.org', None),
+    'pytest': ('https://docs.pytest.org/en/stable', None),
 }