safely patch object attributes, dicts and environment variables.
================================================================


.. contents::
  :local:

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

Use the `monkeypatch funcarg`_ to tweak your global test environment
for running a particular test.  You can safely set/del an attribute,
dictionary item or environment variable by respective methods
on the monkeypatch funcarg.  If you want e.g. to set an ENV1 variable
and have os.path.expanduser return a particular directory, you can
write it down like this:

.. sourcecode:: python

    def test_mytest(monkeypatch):
        monkeypatch.setenv('ENV1', 'myval')
        monkeypatch.setattr(os.path, 'expanduser', lambda x: '/tmp/xyz')
        ... # your test code that uses those patched values implicitely

After the test function finished all modifications will be undone,
because the ``monkeypatch.undo()`` method is registered as a finalizer.

``monkeypatch.setattr/delattr/delitem/delenv()`` all
by default raise an Exception if the target does not exist.
Pass ``raising=False`` if you want to skip this check.

prepending to PATH or other environment variables
---------------------------------------------------------

To prepend a value to an already existing environment parameter:

.. sourcecode:: python

    def test_mypath_finding(monkeypatch):
        monkeypatch.setenv('PATH', 'x/y', prepend=":")
        # in bash language: export PATH=x/y:$PATH

calling "undo" finalization explicitely
-----------------------------------------

At the end of function execution py.test invokes
a teardown hook which undoes all monkeypatch changes.
If you do not want to wait that long you can call
finalization explicitely::

    monkeypatch.undo()

This will undo previous changes.  This call consumes the
undo stack.  Calling it a second time has no effect unless
you  start monkeypatching after the undo call.

.. _`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 these
helper methods to modify objects, dictionaries or os.environ::

    monkeypatch.setattr(obj, name, value, raising=True)
    monkeypatch.delattr(obj, name, raising=True)
    monkeypatch.setitem(mapping, name, value)
    monkeypatch.delitem(obj, name, raising=True)
    monkeypatch.setenv(name, value, prepend=False)
    monkeypatch.delenv(name, value, raising=True)
    monkeypatch.syspath_prepend(path)

All modifications will be undone when the requesting
test function finished its execution.  The ``raising``
parameter determines if a KeyError or AttributeError
will be raised if the set/deletion operation has no target.

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