Docs

Author: nicoddemus

doc/en/how-to/subtests.rst

@@ -16,15 +16,13 @@ Subtests are an alternative to parametrization, particularly useful when the exa
 
 .. code-block:: python
 
-    def contains_docstring(p: Path) -> bool:
-        """Return True if the given Python file contains a top-level docstring."""
-        ...
+    # content of test_subtest.py
 
 
-    def test_py_files_contain_docstring(subtests: pytest.Subtests) -> None:
-        for path in Path.cwd().glob("*.py"):
-            with subtests.test(path=str(path)):
-                assert contains_docstring(path)
+    def test(subtests):
+        for i in range(5):
+            with subtests.test(msg="custom message", i=i):
+                assert i % 2 == 0
 
 Each assertion failure or error is caught by the context manager and reported individually:
 
@@ -33,6 +31,12 @@ Each assertion failure or error is caught by the context manager and reported in
     $ pytest -q test_subtest.py
 
 
+In the output above:
+
+* Each subtest is reported with the ``,`` character.
+* Subtests are reported first and the "top-level" test is reported at the end on its own.
+* Subtest failures are reported as ``SUBFAIL``.
+
 Note that it is possible to use ``subtests`` multiple times in the same test, or even mix and match with normal assertions
 outside the ``subtests.test`` block:
 
@@ -88,3 +92,4 @@ Subtests
 * Can be generated dynamically.
 * Cannot be referenced individually from the command line.
 * Plugins that handle test execution cannot target individual subtests.
+* An assertion failure inside a subtest does not interrupt the test, letting users see all failures in the same report.