From 388aff16c899a3752cebdb80c80e2a2cc455d31b Mon Sep 17 00:00:00 2001 From: Adam Johnson Date: Sat, 29 Dec 2018 11:36:13 +0000 Subject: [PATCH] Improve detailed summary report docs The existing examples had 0 tests collected so didn't show the actual summary report. Also I added a section explaining the difference between `p` and `P`. --- AUTHORS | 1 + changelog/4580.doc.rst | 1 + doc/en/usage.rst | 70 +++++++++++++++++++++++++++++++++++++++--- 3 files changed, 67 insertions(+), 5 deletions(-) create mode 100644 changelog/4580.doc.rst diff --git a/AUTHORS b/AUTHORS index 1316f7b8f..baf2b9123 100644 --- a/AUTHORS +++ b/AUTHORS @@ -6,6 +6,7 @@ Contributors include:: Aaron Coleman Abdeali JK Abhijeet Kasurde +Adam Johnson Ahn Ki-Wook Alan Velasco Alexander Johnson diff --git a/changelog/4580.doc.rst b/changelog/4580.doc.rst new file mode 100644 index 000000000..2d8d52f33 --- /dev/null +++ b/changelog/4580.doc.rst @@ -0,0 +1 @@ +Improved detailed summary report documentation. diff --git a/doc/en/usage.rst b/doc/en/usage.rst index 6c42cd0ec..7e385288e 100644 --- a/doc/en/usage.rst +++ b/doc/en/usage.rst @@ -147,7 +147,7 @@ Detailed summary report .. versionadded:: 2.9 -The ``-r`` flag can be used to display test results summary at the end of the test session, +The ``-r`` flag can be used to display a "short test summary info" 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: @@ -158,9 +158,34 @@ Example: =========================== test session starts ============================ platform linux -- Python 3.x.y, pytest-4.x.y, py-1.x.y, pluggy-0.x.y rootdir: $REGENDOC_TMPDIR, inifile: - collected 0 items + collected 7 items - ======================= no tests ran in 0.12 seconds ======================= + test_examples.py ..FEsxX [100%] + + ==================================== ERRORS ==================================== + _________________________ ERROR at setup of test_error _________________________ + file /Users/chainz/tmp/pytestratest/test_examples.py, line 17 + def test_error(unknown_fixture): + E fixture 'unknown_fixture' not found + > available fixtures: cache, capfd, capfdbinary, caplog, capsys, capsysbinary, doctest_namespace, monkeypatch, pytestconfig, record_property, record_xml_attribute, record_xml_property, recwarn, tmp_path, tmp_path_factory, tmpdir, tmpdir_factory + > use 'pytest --fixtures [testpath]' for help on them. + + /Users/chainz/tmp/pytestratest/test_examples.py:17 + =================================== FAILURES =================================== + __________________________________ test_fail ___________________________________ + + def test_fail(): + > assert 0 + E assert 0 + + test_examples.py:14: AssertionError + =========================== short test summary info ============================ + FAIL test_examples.py::test_fail + ERROR test_examples.py::test_error + SKIP [1] test_examples.py:21: Example + XFAIL test_examples.py::test_xfail + XPASS test_examples.py::test_xpass + = 1 failed, 2 passed, 1 skipped, 1 xfailed, 1 xpassed, 1 error in 0.07 seconds = The ``-r`` options accepts a number of characters after it, with ``a`` used above meaning "all except passes". @@ -183,9 +208,44 @@ More than one character can be used, so for example to only see failed and skipp =========================== test session starts ============================ platform linux -- Python 3.x.y, pytest-4.x.y, py-1.x.y, pluggy-0.x.y rootdir: $REGENDOC_TMPDIR, inifile: - collected 0 items + collected 2 items - ======================= no tests ran in 0.12 seconds ======================= + test_examples.py Fs [100%] + + =================================== FAILURES =================================== + __________________________________ test_fail ___________________________________ + + def test_fail(): + > assert 0 + E assert 0 + + test_examples.py:14: AssertionError + =========================== short test summary info ============================ + FAIL test_examples.py::test_fail + SKIP [1] test_examples.py:21: Example + ===================== 1 failed, 1 skipped in 0.09 seconds ====================== + +Using ``p`` lists the passing tests, whilst ``P`` adds an extra section "PASSES" with those tests that passed but had +captured output: + +.. code-block:: pytest + + $ pytest -rpP + =========================== test session starts ============================ + platform linux -- Python 3.x.y, pytest-4.x.y, py-1.x.y, pluggy-0.x.y + rootdir: $REGENDOC_TMPDIR, inifile: + collected 2 items + + test_examples.py .. [100%] + =========================== short test summary info ============================ + PASSED test_examples.py::test_pass + PASSED test_examples.py::test_pass_with_output + + ==================================== PASSES ==================================== + ____________________________ test_pass_with_output _____________________________ + ----------------------------- Captured stdout call ----------------------------- + Passing test + =========================== 2 passed in 0.04 seconds =========================== .. _pdb-option: