diff --git a/AUTHORS b/AUTHORS index d7be48075..fd98f8141 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/4557.doc.rst b/changelog/4557.doc.rst new file mode 100644 index 000000000..dba2e39cd --- /dev/null +++ b/changelog/4557.doc.rst @@ -0,0 +1 @@ +Markers example documentation page updated to support latest pytest version. diff --git a/changelog/4558.doc.rst b/changelog/4558.doc.rst new file mode 100644 index 000000000..09dc5b863 --- /dev/null +++ b/changelog/4558.doc.rst @@ -0,0 +1 @@ +Update cache documentation example to correctly show cache hit and miss. 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/cache.rst b/doc/en/cache.rst index 914c36fed..a0fa72db1 100644 --- a/doc/en/cache.rst +++ b/doc/en/cache.rst @@ -185,11 +185,14 @@ across pytest invocations:: import pytest import time + def expensive_computation(): + print("running expensive computation...") + @pytest.fixture def mydata(request): val = request.config.cache.get("example/value", None) if val is None: - time.sleep(9*0.6) # expensive computation :) + expensive_computation() val = 42 request.config.cache.set("example/value", val) return val @@ -197,8 +200,7 @@ across pytest invocations:: def test_function(mydata): assert mydata == 23 -If you run this command once, it will take a while because -of the sleep: +If you run this command for the first time, you can see the print statement: .. code-block:: pytest @@ -217,7 +219,7 @@ of the sleep: 1 failed in 0.12 seconds If you run it a second time the value will be retrieved from -the cache and this will be quick: +the cache and nothing will be printed: .. code-block:: pytest diff --git a/doc/en/example/markers.rst b/doc/en/example/markers.rst index 8ab885f0f..9d325c30e 100644 --- a/doc/en/example/markers.rst +++ b/doc/en/example/markers.rst @@ -308,7 +308,7 @@ apply a marker to an individual test instance:: @pytest.mark.foo @pytest.mark.parametrize(("n", "expected"), [ (1, 2), - pytest.mark.bar((1, 3)), + pytest.param((1, 3), marks=pytest.mark.bar), (2, 3), ]) def test_increment(n, expected): @@ -318,15 +318,6 @@ In this example the mark "foo" will apply to each of the three tests, whereas the "bar" mark is only applied to the second test. Skip and xfail marks can also be applied in this way, see :ref:`skip/xfail with parametrize`. -.. note:: - - If the data you are parametrizing happen to be single callables, you need to be careful - when marking these items. ``pytest.mark.xfail(my_func)`` won't work because it's also the - signature of a function being decorated. To resolve this ambiguity, you need to pass a - reason argument: - ``pytest.mark.xfail(func_bar, reason="Issue#7")``. - - .. _`adding a custom marker from a plugin`: Custom marker and command line option to control test runs diff --git a/doc/en/fixture.rst b/doc/en/fixture.rst index e70787a62..133901dde 100644 --- a/doc/en/fixture.rst +++ b/doc/en/fixture.rst @@ -804,7 +804,7 @@ different ``App`` instances and respective smtp servers. There is no need for the ``app`` fixture to be aware of the ``smtp_connection`` parametrization because pytest will fully analyse the fixture dependency graph. -Note, that the ``app`` fixture has a scope of ``module`` and uses a +Note that the ``app`` fixture has a scope of ``module`` and uses a module-scoped ``smtp_connection`` fixture. The example would still work if ``smtp_connection`` was cached on a ``session`` scope: it is fine for fixtures to use "broader" scoped fixtures but not the other way round: diff --git a/doc/en/getting-started.rst b/doc/en/getting-started.rst index 22ffe7bd4..500fc3d93 100644 --- a/doc/en/getting-started.rst +++ b/doc/en/getting-started.rst @@ -7,9 +7,6 @@ Installation and Getting Started **PyPI package name**: `pytest `_ -**Dependencies**: `py `_, -`colorama (Windows) `_, - **Documentation as PDF**: `download latest `_ ``pytest`` is a framework that makes building simple and scalable tests easy. Tests are expressive and readable—no boilerplate code required. Get started in minutes with a small unit test or complex functional test for your application or library. diff --git a/doc/en/usage.rst b/doc/en/usage.rst index 865e007f5..bb1e9218c 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: