Commits

holger krekel committed 02ab82f

fixed README to include --ff description and a more recent run

Comments (0)

Files changed (1)

 after which other plugins can access a new `config.cache`_ object 
 which helps sharing values between ``py.test`` invocations.
 
-The plugin also introduces a new ``--lf`` option to rerun the 
-last failing tests and a ``--clearcache`` option to remove 
-cache contents ahead of a test run.
+The plugin provides two options to rerun failures, namely ``--lf`` to
+only re-run the failures and ``--ff`` to run all tests but the failures
+from the last run first.  For cleanup (usually not needed), a
+``--clearcache`` option allows to remove all cross-session cache
+contents ahead of a test run.
 
 
-The new --lf (rerun last failing) option
-------------------------------------------
+Rerunning only failures or failures first
+-----------------------------------------------
 
-The cache plugin introduces the ``--lf`` option to py.test which
-alows to rerun all test failures of a previous test run.  
-If no tests failed previously, all tests will be run as normal.  
-It is thus usually fine to always pass ``--lf``.
-
-As an example, let's create 50 test invocation of which
-only 2 fail::
+First, let's create 50 test invocation of which only 2 fail::
 
     # content of test_50.py
     import pytest
 If you run this for the first time you will see two failures::
 
     $ py.test -q
-    collecting ... collected 50 items
     .................F.......F........................
-    ================================= FAILURES =================================
-    _______________________________ test_num[17] _______________________________
+    =================================== FAILURES ===================================
+    _________________________________ test_num[17] _________________________________
     
     i = 17
     
     E          Failed: bad luck
     
     test_50.py:6: Failed
-    _______________________________ test_num[25] _______________________________
+    _________________________________ test_num[25] _________________________________
     
     i = 25
     
     E          Failed: bad luck
     
     test_50.py:6: Failed
-    2 failed, 48 passed in 0.06 seconds
 
-If you then run it with ``--lf`` you will re-run the last two failures::
+If you then run it with ``--lf`` you will run only the two failing test
+from the last run::
 
-    $ py.test -q --lf
-    collecting ... collected 50 items
-    FF
-    ================================= FAILURES =================================
-    _______________________________ test_num[17] _______________________________
+    $ py.test --lf
+    ============================= test session starts ==============================
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.5
+    run-last-failure: rerun last 2 failures
+    plugins: cache
+    collected 50 items
+    
+    test_50.py FF
+    
+    =================================== FAILURES ===================================
+    _________________________________ test_num[17] _________________________________
     
     i = 17
     
     E          Failed: bad luck
     
     test_50.py:6: Failed
-    _______________________________ test_num[25] _______________________________
+    _________________________________ test_num[25] _________________________________
     
     i = 25
     
     E          Failed: bad luck
     
     test_50.py:6: Failed
-    ======================== 48 tests deselected by '' =========================
-    2 failed, 48 deselected in 0.01 seconds
+    =================== 2 failed, 48 deselected in 0.02 seconds ====================
 
 The last line indicates that 48 tests have not been run.
 
+If you run with the ``--ff`` option, all tests will be run but the first
+failures will be executed first (as can be seen from the series of ``FF`` and
+dots)::
+
+    $ py.test --ff
+    ============================= test session starts ==============================
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.5
+    run-last-failure: rerun last 2 failures first
+    plugins: cache
+    collected 50 items
+    
+    test_50.py FF................................................
+    
+    =================================== FAILURES ===================================
+    _________________________________ test_num[17] _________________________________
+    
+    i = 17
+    
+        @pytest.mark.parametrize("i", range(50))
+        def test_num(i):
+            if i in (17,25):
+    >          pytest.fail("bad luck")
+    E          Failed: bad luck
+    
+    test_50.py:6: Failed
+    _________________________________ test_num[25] _________________________________
+    
+    i = 25
+    
+        @pytest.mark.parametrize("i", range(50))
+        def test_num(i):
+            if i in (17,25):
+    >          pytest.fail("bad luck")
+    E          Failed: bad luck
+    
+    test_50.py:6: Failed
+    ===================== 2 failed, 48 passed in 0.07 seconds ======================
+
 .. _`config.cache`:
 
 The new config.cache object
 of the sleep::
 
     $ py.test -q
-    collecting ... collected 1 items
     F
-    ================================= FAILURES =================================
-    ______________________________ test_function _______________________________
+    =================================== FAILURES ===================================
+    ________________________________ test_function _________________________________
     
     mydata = 42
     
     E       assert 42 == 23
     
     test_caching.py:12: AssertionError
-    1 failed in 5.43 seconds
 
 If you run it a second time the value will be retrieved from
 the cache and this will be quick::
 
     $ py.test -q
-    collecting ... collected 1 items
     F
-    ================================= FAILURES =================================
-    ______________________________ test_function _______________________________
+    =================================== FAILURES ===================================
+    ________________________________ test_function _________________________________
     
     mydata = 42
     
     E       assert 42 == 23
     
     test_caching.py:12: AssertionError
-    1 failed in 0.02 seconds
 
 Consult the `pytest-cache API <http://packages.python.org/pytest-cache/api.html>`_
 for more details.
 ``--cache`` command line option::
 
     $ py.test --cache
-    =========================== test session starts ============================
-    platform linux2 -- Python 2.7.3 -- pytest-2.2.5.dev2
-    cachedir: /home/hpk/tmp/doc-exec-257/.cache
-    ------------------------------- cache values -------------------------------
+    ============================= test session starts ==============================
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.5
+    plugins: cache
+    cachedir: /tmp/doc-exec-6/.cache
+    --------------------------------- cache values ---------------------------------
+    example/value contains:
+      42
     cache/lastfailed contains:
       set(['test_caching.py::test_function'])
-    example/value contains:
-      42
     
-    =============================  in 0.01 seconds =============================
+    ===============================  in 0.01 seconds ===============================
 
 Clearing Cache content
 -------------------------------