Metadata-Version: 2.1
Name: pytest-cache
Version: 1.0
Summary: pytest plugin with mechanisms for caching across test runs
Home-page: http://bitbucket.org/hpk42/pytest-cache/
Author: Holger Krekel
Author-email: holger.krekel@gmail.com
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License (GPL)
Classifier: Operating System :: POSIX
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Utilities
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
License-File: LICENSE

pytest-cache: working with cross-testrun state
=====================================================

Usage
---------

install via::

    pip install pytest-cache

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 new --lf (rerun last failing) option
------------------------------------------

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::

    # content of test_50.py
    import pytest

    @pytest.mark.parametrize("i", range(50))
    def test_num(i):
        if i in (17,25):
           pytest.fail("bad luck") 

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] _______________________________
    
    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.06 seconds

If you then run it with ``--lf`` you will re-run the last two failures::

    $ py.test -q --lf
    collecting ... collected 50 items
    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
    ======================== 48 tests deselected by '' =========================
    2 failed, 48 deselected in 0.01 seconds

The last line indicates that 48 tests have not been run.

.. _`config.cache`:

The new config.cache object
--------------------------------

.. regendoc:wipe

Plugins or conftest.py support code can get a cached value 
using the pytest ``config`` object.  Here is a basic example
plugin which implements a `funcarg <http://pytest.org/latest/funcargs.html>`_
which re-uses previously created state across py.test invocations::

    # content of test_caching.py
    import time

    def pytest_funcarg__mydata(request):
        val = request.config.cache.get("example/value", None)
        if val is None:
            time.sleep(9*0.6) # expensive computation :)
            val = 42
            request.config.cache.set("example/value", val)
        return val 

    def test_function(mydata):
        assert mydata == 23

If you run this command once, it will take a while because
of the sleep::

    $ py.test -q
    collecting ... collected 1 items
    F
    ================================= FAILURES =================================
    ______________________________ test_function _______________________________
    
    mydata = 42
    
        def test_function(mydata):
    >       assert mydata == 23
    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 _______________________________
    
    mydata = 42
    
        def test_function(mydata):
    >       assert mydata == 23
    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.


Inspecting Cache content
-------------------------------

You can always peek at the content of the cache using the
``--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 -------------------------------
    cache/lastfailed contains:
      set(['test_caching.py::test_function'])
    example/value contains:
      42
    
    =============================  in 0.01 seconds =============================

Clearing Cache content
-------------------------------

You can instruct pytest to clear all cache files and values 
by adding the ``--clearcache`` option like this::

    py.test --clearcache

This is recommended for invocations from Continous Integration
servers where isolation and correctness is more important
than speed.

Notes
-------------

repository: http://bitbucket.org/hpk42/pytest-cache

Issues: repository: http://bitbucket.org/hpk42/pytest-cache/issues

more info on py.test: http://pytest.org


