
Monkeypatching/mocking modules and environments
***********************************************

Sometimes tests need to invoke functionality which depends on global
settings or which invokes code which cannot be easily tested such as
network access.  The "monkeypatch" function argument helps you to
safely set/delete an attribute, dictionary item or environment
variable or to modify "sys.path" for importing. See the monkeypatch
blog post for some introduction material and a discussion of its
motivation.


Simple example: monkeypatching functions
========================================

If you want to pretend that "os.expanduser" returns a certain
directory, you can use the "monkeypatch.setattr()" method to patch
this function before calling into a function which uses it:

   # content of test_module.py
   import os.path
   def getssh(): # pseudo application code
       return os.path.join(os.path.expanduser("~admin"), '.ssh')

   def test_mytest(monkeypatch):
       def mockreturn(path):
           return '/abc'
       monkeypatch.setattr(os.path, 'expanduser', mockreturn)
       x = getssh()
       assert x == '/abc/.ssh'

Here our test function monkeypatches "os.path.expanduser" and then
calls into an function that calls it.  After the test function
finishes the "os.path.expanduser" modification will be undone.


Method reference of the monkeypatch function argument
=====================================================

"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.
