Merge pull request #3917 from dhirensr/docs_for_detailed_info

T3566,T3546: added a blurb in usage.rst for usage of flag -r

Author: nicoddemus

AUTHORS

@@ -47,6 +47,7 @@ Christian Theunert
 Christian Tismer
 Christopher Gilling
 Cyrus Maden
+Dhiren Serai
 Daniel Grana
 Daniel Hahler
 Daniel Nuri

changelog/3566.doc.rst

@@ -0,0 +1 @@
+Added a blurb in usage.rst for the usage of -r flag which is used to show an extra test summary info.

doc/en/conf.py

@@ -329,7 +329,7 @@
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {"python": ("http://docs.python.org/3", None)}
+intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
 
 
 def setup(app):

doc/en/usage.rst

@@ -140,6 +140,48 @@ will be shown (because KeyboardInterrupt is caught by pytest). By using this
 option you make sure a trace is shown.
 
 
+.. _`pytest.detailed_failed_tests_usage`:
+
+Detailed summary report
+-----------------------
+
+.. versionadded:: 2.9
+
+The ``-r`` flag can be used to display test results summary at the end of the test session,
+making it easy in large test suites to get a clear picture of all failures, skips, xfails, etc.
+
+Example::
+
+    $ pytest -ra
+    ======================== test session starts ========================
+    ...
+    ====================== short test summary info ======================
+    FAIL summary\test_foo.py::test_1
+    SKIP [1] summary\test_foo.py:12: not supported in this platform
+    XPASS summary\test_bar.py::test_4 flaky
+
+    ===== 1 failed, 1 passed, 1 skipped, 1 xpassed in 0.08 seconds ======
+
+
+The ``-r`` options accepts a number of characters after it, with ``a`` used above meaning "all except passes".
+
+Here is the full list of available characters that can be used:
+
+ - ``f`` - failed
+ - ``E`` - error
+ - ``s`` - skipped
+ - ``x`` - xfailed
+ - ``X`` - xpassed
+ - ``p`` - passed
+ - ``P`` - passed with output
+ - ``a`` - all except ``pP``
+
+More than one character can be used, so for example to only see failed and skipped tests, you can execute::
+
+    $ pytest -rfs
+
+
+
 .. _pdb-option:
 
 Dropping to PDB_ (Python Debugger) on failures