test_ok1/doc/test/plugin/monkeypatch.txt

pytest_monkeypatch plugin
=========================

safely patch object attributes, dicts and environment variables.

.. contents::
  :local:

Usage
----------------

Use the `monkeypatch funcarg`_ to safely patch environment
variables, object attributes or dictionaries.  For example, if you want
to set the environment variable ``ENV1`` and patch the
``os.path.abspath`` function to return a particular value during a test
function execution you can write it down like this:

.. sourcecode:: python 

    def test_mytest(monkeypatch):
        monkeypatch.setenv('ENV1', 'myval')
        monkeypatch.setattr(os.path, 'abspath', lambda x: '/')
        ... # your test code 

The function argument will do the modifications and memorize the 
old state.  After the test function finished execution all 
modifications will be reverted.  See the `monkeypatch blog post`_ 
for an extensive discussion.  

To add to a possibly existing environment parameter you
can use this example: 

.. sourcecode:: python 

    def test_mypath_finding(monkeypatch):
        monkeypatch.setenv('PATH', 'x/y', prepend=":")
        #  x/y will be at the beginning of $PATH 

.. _`monkeypatch blog post`: http://tetamap.wordpress.com/2009/03/03/monkeypatching-in-unit-tests-done-right/

.. _`monkeypatch funcarg`:


the 'monkeypatch' test function argument
----------------------------------------

The returned ``monkeypatch`` funcarg provides three 
helper methods to modify objects, dictionaries or os.environ::

    monkeypatch.setattr(obj, name, value)  
    monkeypatch.setitem(mapping, name, value) 
    monkeypatch.setenv(name, value) 

All such modifications will be undone when the requesting 
test function finished its execution. 

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


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

Checkout customize_, other plugins_ or `get in contact`_. 

.. include:: links.txt