Add support for ``pytest``

This is the minimal configuration required for the test suite to 
pass using the pytest framework. This is part of the test suite
refactoring project.

- Ignore two classes that start with the word "Test"
- Provide the standard test header to pytest
- Update the documentation

git-svn-id: https://svn.code.sf.net/p/docutils/code/trunk@9237 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

4 files changed, 33 insertions, 6 deletions

diff --git a/docutils/docs/dev/testing.txt b/docutils/docs/dev/testing.txt
index 2a18fcd86..a7c62b167 100644
--- a/docutils/docs/dev/testing.txt
+++ b/docutils/docs/dev/testing.txt
@@ -39,15 +39,15 @@ In a pinch, the edge cases should cover most of it.
 __ policies.html#check-ins
 
 .. note::
-   Due to incompatible customization of the standard unittest_
-   framework, the test suite does not work with popular test frameworks
-   like pytest_ or nose_.
+   The standard ``alltests.py`` test runner uses the standard library's
+   unittest_ framework.
+
+   For the pytest_ test framework, from a shell run::
+
+       pytest --quiet ./test
 
    .. _unittest: https://docs.python.org/3/library/unittest.html
    .. _pytest: https://pypi.org/project/pytest/
-   .. _nose: https://pypi.org/project/nose3/
-
-   .. cf. https://sourceforge.net/p/docutils/feature-requests/81/
 
 .. [#] When using the `Python launcher for Windows`__, make sure to
    specify a Python version, e.g., ``py -3.9 -u alltests.py`` for
diff --git a/docutils/docutils/transforms/universal.py b/docutils/docutils/transforms/universal.py
index 3f93f8589..518cfc415 100644
--- a/docutils/docutils/transforms/universal.py
+++ b/docutils/docutils/transforms/universal.py
@@ -172,6 +172,9 @@ class TestMessages(Transform):
     Used for testing purposes.
     """
 
+    # marker for pytest to ignore this class during test discovery
+    __test__ = False
+
     default_priority = 880
 
     def apply(self):
diff --git a/docutils/test/conftest.py b/docutils/test/conftest.py
new file mode 100644
index 000000000..bd0ef995a
--- /dev/null
+++ b/docutils/test/conftest.py
@@ -0,0 +1,21 @@
+def pytest_report_header(config):

+    import os

+    import platform

+    import sys

+    import time

+

+    # DocutilsTestSupport must be imported before docutils

+    from . import DocutilsTestSupport  # NoQA: F401

+    import docutils

+

+    return '\n'.join((

+        '',

+        f'Testing Docutils {docutils.__version__} '

+        f'with Python {sys.version.split()[0]} '

+        f'on {time.strftime("%Y-%m-%d at %H:%M:%S")}',

+        f'OS: {platform.system()} {platform.release()} {platform.version()} '

+        f'({sys.platform}, {platform.platform()})',

+        f'Working directory: {os.getcwd()}',

+        f'Docutils package: {os.path.dirname(docutils.__file__)}',

+        '',

+    ))

diff --git a/docutils/test/test_transforms/test___init__.py b/docutils/test/test_transforms/test___init__.py
index a3b47eb50..61978e6dc 100755
--- a/docutils/test/test_transforms/test___init__.py
+++ b/docutils/test/test_transforms/test___init__.py
@@ -15,6 +15,9 @@ from docutils import transforms, utils
 
 class TestTransform(transforms.Transform):
 
+    # marker for pytest to ignore this class during test discovery
+    __test__ = False
+
     default_priority = 100
 
     applied = 0