test_ok1/doc/test/plugin/figleaf.txt

pytest_figleaf plugin
=====================

write and report coverage data with 'figleaf'.



command line options
--------------------


``-F``
    trace python coverage with figleaf and write HTML for files below the current working dir
``--figleaf-data=FIGLEAFDATA``
    path to coverage tracing file.
``--figleaf-html=FIGLEAFHTML``
    path to the coverage html dir.

Getting and improving this plugin
---------------------------------


Do you find the above documentation or the plugin itself lacking,
not fit for what you need?  Here is a **30 seconds guide**
to get you started on improving the plugin:

1. Download `pytest_figleaf.py`_ plugin source code 
2. put it somewhere as ``pytest_figleaf.py`` into your import path 
3. a subsequent test run will now use your local version! 

Further information: extend_ documentation, other plugins_ or contact_.  

For your convenience here is also an inlined version of ``pytest_figleaf.py``:

.. sourcecode:: python

    """
    write and report coverage data with 'figleaf'. 
    
    """
    import py
    
    figleaf = py.test.importorskip("figleaf.annotate_html")
    
    def pytest_addoption(parser):
        group = parser.addgroup('figleaf options')
        group.addoption('-F', action='store_true', default=False,
                dest = 'figleaf',
                help=('trace python coverage with figleaf and write HTML '
                     'for files below the current working dir'))
        group.addoption('--figleaf-data', action='store', default='.figleaf',
                dest='figleafdata',
                help='path to coverage tracing file.')
        group.addoption('--figleaf-html', action='store', default='html',
                dest='figleafhtml', 
                help='path to the coverage html dir.')
    
    def pytest_configure(config):
        figleaf.start()
    
    def pytest_terminal_summary(terminalreporter):
        config = terminalreporter.config
        datafile = py.path.local(config.getvalue('figleafdata'))
        tw = terminalreporter._tw
        tw.sep('-', 'figleaf')
        tw.line('Writing figleaf data to %s' % (datafile))
        figleaf.stop()
        figleaf.write_coverage(str(datafile))
        coverage = get_coverage(datafile, config)
        reportdir = py.path.local(config.getvalue('figleafhtml'))
        tw.line('Writing figleaf html to file://%s' % (reportdir))
        figleaf.annotate_html.prepare_reportdir(str(reportdir))
        exclude = []
        figleaf.annotate_html.report_as_html(coverage, 
                str(reportdir), exclude, {})
    
    def get_coverage(datafile, config):
        # basepath = config.topdir
        basepath = py.path.local()
        data = figleaf.read_coverage(str(datafile))
        d = {}
        coverage = figleaf.combine_coverage(d, data)
        for path in coverage.keys():
            if not py.path.local(path).relto(basepath):
                del coverage[path]
        return coverage
    
    
    def test_functional(testdir):
        py.test.importorskip("figleaf")
        testdir.plugins.append("figleaf")
        testdir.makepyfile("""
            def f():    
                x = 42
            def test_whatever():
                pass
            """)
        result = testdir.runpytest('-F')
        assert result.ret == 0
        assert result.stdout.fnmatch_lines([
            '*figleaf html*'
            ])
        #print result.stdout.str()

.. _`pytest_figleaf.py`: http://bitbucket.org/hpk42/py-trunk/raw/3d511a58acc10477ff4f766df4a9224cfc3546af/py/test/plugin/pytest_figleaf.py
.. _`extend`: ../extend.html
.. _`plugins`: index.html
.. _`contact`: ../../contact.html
.. _`checkout the py.test development version`: ../../download.html#checkout