test_ok2/doc/test/plugin/recwarn.txt

pytest_recwarn plugin
=====================

helpers for asserting deprecation and other warnings.

.. contents::
  :local:

Example usage 
---------------------

You can use the ``recwarn`` funcarg to track 
warnings within a test function:

.. sourcecode:: python

    def test_hello(recwarn):
        from warnings import warn
        warn("hello", DeprecationWarning)
        w = recwarn.pop(DeprecationWarning)
        assert issubclass(w.category, DeprecationWarning)
        assert 'hello' in str(w.message)
        assert w.filename
        assert w.lineno

You can also call a global helper for checking
taht a certain function call yields a Deprecation
warning:

.. sourcecode:: python

    import py
            
    def test_global():
        py.test.deprecated_call(myfunction, 17)

.. _`recwarn funcarg`:


the 'recwarn' test function argument
------------------------------------

Return a WarningsRecorder instance that provides these methods:

* ``pop(category=None)``: return last warning matching the category.
* ``clear()``: clear list of warnings 

Start improving this plugin in 30 seconds
=========================================


Do you find the above documentation or the plugin itself lacking? 

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

Further information: extend_ documentation, other plugins_ or contact_.  

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