DOC: Document newer pytest conventions

2 files changed, 17 insertions, 6 deletions

diff --git a/doc/TESTS.rst.txt b/doc/TESTS.rst.txt
index 21cc08673..cb8578e5a 100644
--- a/doc/TESTS.rst.txt
+++ b/doc/TESTS.rst.txt
@@ -106,22 +106,32 @@ 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::
 
-  from numpy.testing import assert_, assert_raises
+  import pytest
 
   # import xxx symbols
   from numpy.xxx.yyy import zzz
 
   class TestZzz:
       def test_simple(self):
-          assert_(zzz() == 'Hello from zzz')
+          assert zzz() == 'Hello from zzz'
 
       def test_invalid_parameter(self):
-          assert_raises(...)
+          with pytest.raises(ValueError, match='.*some matching regex.*'):
+              ...
 
-Within these test methods, ``assert_()`` and related functions are used to test
+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.
-Note that the Python builtin ``assert`` should not be used, because it is
-stripped during compilation with ``-O``.
+``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
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),
 }