1 """

     2 Copyright (c) 2007  Gustavo Niemeyer <gustavo@niemeyer.net>

     3 

     4 Graceful platform for test doubles in Python (mocks, stubs, fakes, and dummies).

     5 """

     6 import __builtin__

     7 import tempfile

     8 import unittest

     9 import inspect

    10 import shutil

    11 import types

    12 import sys

    13 import os

    14 import gc

    15 

    16 

    17 if sys.version_info < (2, 4):

    18     from sets import Set as set # pragma: nocover

    19 

    20 

    21 __all__ = ["Mocker", "expect", "IS", "CONTAINS", "IN", "MATCH",

    22            "ANY", "ARGS", "KWARGS"]

    23 

    24 

    25 __author__ = "Gustavo Niemeyer <gustavo@niemeyer.net>"

    26 __license__ = "PSF License"

    27 __version__ = "0.10.1"

    28 

    29 

    30 ERROR_PREFIX = "[Mocker] "

    31 

    32 

    33 # --------------------------------------------------------------------

    34 # Exceptions

    35 

    36 class MatchError(AssertionError):

    37     """Raised when an unknown expression is seen in playback mode."""

    38 

    39 

    40 # --------------------------------------------------------------------

    41 # Helper for chained-style calling.

    42 

    43 class expect(object):

    44     """This is a simple helper that allows a different call-style.

    45 

    46     With this class one can comfortably do chaining of calls to the

    47     mocker object responsible by the object being handled. For instance::

    48 

    49         expect(obj.attr).result(3).count(1, 2)

    50 

    51     Is the same as::

    52 

    53         obj.attr

    54         mocker.result(3)

    55         mocker.count(1, 2)

    56 

    57     """

    58 

    59     def __init__(self, mock, attr=None):

    60         self._mock = mock

    61         self._attr = attr

    62 

    63     def __getattr__(self, attr):

    64         return self.__class__(self._mock, attr)

    65 

    66     def __call__(self, *args, **kwargs):

    67         getattr(self._mock.__mocker__, self._attr)(*args, **kwargs)

    68         return self

    69 

    70 

    71 # --------------------------------------------------------------------

    72 # Extensions to Python's unittest.

    73 

    74 class MockerTestCase(unittest.TestCase):

    75     """unittest.TestCase subclass with Mocker support.

    76 

    77     @ivar mocker: The mocker instance.

    78 

    79     This is a convenience only.  Mocker may easily be used with the

    80     standard C{unittest.TestCase} class if wanted.

    81 

    82     Test methods have a Mocker instance available on C{self.mocker}.

    83     At the end of each test method, expectations of the mocker will

    84     be verified, and any requested changes made to the environment

    85     will be restored.

    86 

    87     In addition to the integration with Mocker, this class provides

    88     a few additional helper methods.

    89     """

    90 

    91     expect = expect

    92 

    93     def __init__(self, methodName="runTest"):

    94         # So here is the trick: we take the real test method, wrap it on

    95         # a function that do the job we have to do, and insert it in the

    96         # *instance* dictionary, so that getattr() will return our

    97         # replacement rather than the class method.

    98         test_method = getattr(self, methodName, None)

    99         if test_method is not None:

   100             def test_method_wrapper():

   101                 try:

   102                     result = test_method()

   103                 except:

   104                     raise

   105                 else:

   106                     if (self.mocker.is_recording() and

   107                         self.mocker.get_events()):

   108                         raise RuntimeError("Mocker must be put in replay "

   109                                            "mode with self.mocker.replay()")

   110                     if (hasattr(result, "addCallback") and

   111                         hasattr(result, "addErrback")):

   112                         def verify(result):

   113                             self.mocker.verify()

   114                             return result

   115                         result.addCallback(verify)

   116                     else:

   117                         self.mocker.verify()

   118                     return result

   119             # Copy all attributes from the original method..

   120             for attr in dir(test_method):

   121                 # .. unless they're present in our wrapper already.

   122                 if not hasattr(test_method_wrapper, attr) or attr == "__doc__":

   123                     setattr(test_method_wrapper, attr,

   124                             getattr(test_method, attr))

   125             setattr(self, methodName, test_method_wrapper)

   126 

   127         # We could overload run() normally, but other well-known testing

   128         # frameworks do it as well, and some of them won't call the super,

   129         # which might mean that cleanup wouldn't happen.  With that in mind,

   130         # we make integration easier by using the following trick.

   131         run_method = self.run

   132         def run_wrapper(*args, **kwargs):

   133             try:

   134                 return run_method(*args, **kwargs)

   135             finally:

   136                 self.__cleanup()

   137         self.run = run_wrapper

   138 

   139         self.mocker = Mocker()

   140 

   141         self.__cleanup_funcs = []

   142         self.__cleanup_paths = []

   143 

   144         super(MockerTestCase, self).__init__(methodName)

   145 

   146     def __cleanup(self):

   147         for path in self.__cleanup_paths:

   148             if os.path.isfile(path):

   149                 os.unlink(path)

   150             elif os.path.isdir(path):

   151                 shutil.rmtree(path)

   152         self.mocker.restore()

   153         for func, args, kwargs in self.__cleanup_funcs:

   154             func(*args, **kwargs)

   155 

   156     def addCleanup(self, func, *args, **kwargs):

   157         self.__cleanup_funcs.append((func, args, kwargs))

   158 

   159     def makeFile(self, content=None, suffix="", prefix="tmp", basename=None,

   160                  dirname=None, path=None):

   161         """Create a temporary file and return the path to it.

   162 

   163         @param content: Initial content for the file.

   164         @param suffix: Suffix to be given to the file's basename.

   165         @param prefix: Prefix to be given to the file's basename.

   166         @param basename: Full basename for the file.

   167         @param dirname: Put file inside this directory.

   168 

   169         The file is removed after the test runs.

   170         """

   171         if path is not None:

   172             self.__cleanup_paths.append(path)

   173         elif basename is not None:

   174             if dirname is None:

   175                 dirname = tempfile.mkdtemp()

   176                 self.__cleanup_paths.append(dirname)

   177             path = os.path.join(dirname, basename)

   178         else:

   179             fd, path = tempfile.mkstemp(suffix, prefix, dirname)

   180             self.__cleanup_paths.append(path)

   181             os.close(fd)

   182             if content is None:

   183                 os.unlink(path)

   184         if content is not None:

   185             file = open(path, "w")

   186             file.write(content)

   187             file.close()

   188         return path

   189 

   190     def makeDir(self, suffix="", prefix="tmp", dirname=None, path=None):

   191         """Create a temporary directory and return the path to it.

   192 

   193         @param suffix: Suffix to be given to the file's basename.

   194         @param prefix: Prefix to be given to the file's basename.

   195         @param dirname: Put directory inside this parent directory.

   196 

   197         The directory is removed after the test runs.

   198         """

   199         if path is not None:

   200             os.makedirs(path)

   201         else:

   202             path = tempfile.mkdtemp(suffix, prefix, dirname)

   203         self.__cleanup_paths.append(path)

   204         return path

   205 

   206     def failUnlessIs(self, first, second, msg=None):

   207         """Assert that C{first} is the same object as C{second}."""

   208         if first is not second:

   209             raise self.failureException(msg or "%r is not %r" % (first, second))

   210 

   211     def failIfIs(self, first, second, msg=None):

   212         """Assert that C{first} is not the same object as C{second}."""

   213         if first is second:

   214             raise self.failureException(msg or "%r is %r" % (first, second))

   215 

   216     def failUnlessIn(self, first, second, msg=None):

   217         """Assert that C{first} is contained in C{second}."""

   218         if first not in second:

   219             raise self.failureException(msg or "%r not in %r" % (first, second))

   220 

   221     def failUnlessStartsWith(self, first, second, msg=None):

   222         """Assert that C{first} starts with C{second}."""

   223         if first[:len(second)] != second:

   224             raise self.failureException(msg or "%r doesn't start with %r" %

   225                                                (first, second))

   226 

   227     def failIfStartsWith(self, first, second, msg=None):

   228         """Assert that C{first} doesn't start with C{second}."""

   229         if first[:len(second)] == second:

   230             raise self.failureException(msg or "%r starts with %r" %

   231                                                (first, second))

   232 

   233     def failUnlessEndsWith(self, first, second, msg=None):

   234         """Assert that C{first} starts with C{second}."""

   235         if first[len(first)-len(second):] != second:

   236             raise self.failureException(msg or "%r doesn't end with %r" %

   237                                                (first, second))

   238 

   239     def failIfEndsWith(self, first, second, msg=None):

   240         """Assert that C{first} doesn't start with C{second}."""

   241         if first[len(first)-len(second):] == second:

   242             raise self.failureException(msg or "%r ends with %r" %

   243                                                (first, second))

   244 

   245     def failIfIn(self, first, second, msg=None):

   246         """Assert that C{first} is not contained in C{second}."""

   247         if first in second:

   248             raise self.failureException(msg or "%r in %r" % (first, second))

   249 

   250     def failUnlessApproximates(self, first, second, tolerance, msg=None):

   251         """Assert that C{first} is near C{second} by at most C{tolerance}."""

   252         if abs(first - second) > tolerance:

   253             raise self.failureException(msg or "abs(%r - %r) > %r" %

   254                                         (first, second, tolerance))

   255 

   256     def failIfApproximates(self, first, second, tolerance, msg=None):

   257         """Assert that C{first} is far from C{second} by at least C{tolerance}.

   258         """

   259         if abs(first - second) <= tolerance:

   260             raise self.failureException(msg or "abs(%r - %r) <= %r" %

   261                                         (first, second, tolerance))

   262 

   263     def failUnlessMethodsMatch(self, first, second):

   264         """Assert that public methods in C{first} are present in C{second}.

   265 

   266         This method asserts that all public methods found in C{first} are also

   267         present in C{second} and accept the same arguments.  C{first} may

   268         have its own private methods, though, and may not have all methods

   269         found in C{second}.  Note that if a private method in C{first} matches

   270         the name of one in C{second}, their specification is still compared.

   271 

   272         This is useful to verify if a fake or stub class have the same API as

   273         the real class being simulated.

   274         """

   275         first_methods = dict(inspect.getmembers(first, inspect.ismethod))

   276         second_methods = dict(inspect.getmembers(second, inspect.ismethod))

   277         for name, first_method in first_methods.items():

   278             first_argspec = inspect.getargspec(first_method)

   279             first_formatted = inspect.formatargspec(*first_argspec)

   280 

   281             second_method = second_methods.get(name)

   282             if second_method is None:

   283                 if name[:1] == "_":

   284                     continue # First may have its own private methods.

   285                 raise self.failureException("%s.%s%s not present in %s" %

   286                     (first.__name__, name, first_formatted, second.__name__))

   287 

   288             second_argspec = inspect.getargspec(second_method)

   289             if first_argspec != second_argspec:

   290                 second_formatted = inspect.formatargspec(*second_argspec)

   291                 raise self.failureException("%s.%s%s != %s.%s%s" %

   292                     (first.__name__, name, first_formatted,

   293                      second.__name__, name, second_formatted))

   294 

   295 

   296     assertIs = failUnlessIs

   297     assertIsNot = failIfIs

   298     assertIn = failUnlessIn

   299     assertNotIn = failIfIn

   300     assertStartsWith = failUnlessStartsWith

   301     assertNotStartsWith = failIfStartsWith

   302     assertEndsWith = failUnlessEndsWith

   303     assertNotEndsWith = failIfEndsWith

   304     assertApproximates = failUnlessApproximates

   305     assertNotApproximates = failIfApproximates

   306     assertMethodsMatch = failUnlessMethodsMatch

   307 

   308     # The following are missing in Python < 2.4.

   309     assertTrue = unittest.TestCase.failUnless

   310     assertFalse = unittest.TestCase.failIf

   311 

   312     # The following is provided for compatibility with Twisted's trial.

   313     assertIdentical = assertIs

   314     assertNotIdentical = assertIsNot

   315     failUnlessIdentical = failUnlessIs

   316     failIfIdentical = failIfIs

   317 

   318 

   319 # --------------------------------------------------------------------

   320 # Mocker.

   321 

   322 class classinstancemethod(object):

   323 

   324     def __init__(self, method):

   325         self.method = method

   326 

   327     def __get__(self, obj, cls=None):

   328         def bound_method(*args, **kwargs):

   329             return self.method(cls, obj, *args, **kwargs)

   330         return bound_method

   331 

   332 

   333 class MockerBase(object):

   334     """Controller of mock objects.

   335 

   336     A mocker instance is used to command recording and replay of

   337     expectations on any number of mock objects.

   338 

   339     Expectations should be expressed for the mock object while in

   340     record mode (the initial one) by using the mock object itself,

   341     and using the mocker (and/or C{expect()} as a helper) to define

   342     additional behavior for each event.  For instance::

   343 

   344         mock = mocker.mock()

   345         mock.hello()

   346         mocker.result("Hi!")

   347         mocker.replay()

   348         assert mock.hello() == "Hi!"

   349         mock.restore()

   350         mock.verify()

   351 

   352     In this short excerpt a mock object is being created, then an

   353     expectation of a call to the C{hello()} method was recorded, and

   354     when called the method should return the value C{10}.  Then, the

   355     mocker is put in replay mode, and the expectation is satisfied by

   356     calling the C{hello()} method, which indeed returns 10.  Finally,

   357     a call to the L{restore()} method is performed to undo any needed

   358     changes made in the environment, and the L{verify()} method is

   359     called to ensure that all defined expectations were met.

   360 

   361     The same logic can be expressed more elegantly using the

   362     C{with mocker:} statement, as follows::

   363 

   364         mock = mocker.mock()

   365         mock.hello()

   366         mocker.result("Hi!")

   367         with mocker:

   368             assert mock.hello() == "Hi!"

   369 

   370     Also, the MockerTestCase class, which integrates the mocker on

   371     a unittest.TestCase subclass, may be used to reduce the overhead

   372     of controlling the mocker.  A test could be written as follows::

   373 

   374         class SampleTest(MockerTestCase):

   375 

   376             def test_hello(self):

   377                 mock = self.mocker.mock()

   378                 mock.hello()

   379                 self.mocker.result("Hi!")

   380                 self.mocker.replay()

   381                 self.assertEquals(mock.hello(), "Hi!")

   382     """

   383 

   384     _recorders = []

   385 

   386     # For convenience only.

   387     on = expect

   388 

   389     class __metaclass__(type):

   390         def __init__(self, name, bases, dict):

   391             # Make independent lists on each subclass, inheriting from parent.

   392             self._recorders = list(getattr(self, "_recorders", ()))

   393 

   394     def __init__(self):

   395         self._recorders = self._recorders[:]

   396         self._events = []

   397         self._recording = True

   398         self._ordering = False

   399         self._last_orderer = None

   400 

   401     def is_recording(self):

   402         """Return True if in recording mode, False if in replay mode.

   403 

   404         Recording is the initial state.

   405         """

   406         return self._recording

   407 

   408     def replay(self):

   409         """Change to replay mode, where recorded events are reproduced.

   410 

   411         If already in replay mode, the mocker will be restored, with all

   412         expectations reset, and then put again in replay mode.

   413 

   414         An alternative and more comfortable way to replay changes is

   415         using the 'with' statement, as follows::

   416 

   417             mocker = Mocker()

   418             <record events>

   419             with mocker:

   420                 <reproduce events>

   421 

   422         The 'with' statement will automatically put mocker in replay

   423         mode, and will also verify if all events were correctly reproduced

   424         at the end (using L{verify()}), and also restore any changes done

   425         in the environment (with L{restore()}).

   426 

   427         Also check the MockerTestCase class, which integrates the

   428         unittest.TestCase class with mocker.

   429         """

   430         if not self._recording:

   431             for event in self._events:

   432                 event.restore()

   433         else:

   434             self._recording = False

   435         for event in self._events:

   436             event.replay()

   437 

   438     def restore(self):

   439         """Restore changes in the environment, and return to recording mode.

   440 

   441         This should always be called after the test is complete (succeeding

   442         or not).  There are ways to call this method automatically on

   443         completion (e.g. using a C{with mocker:} statement, or using the

   444         L{MockerTestCase} class.

   445         """

   446         if not self._recording:

   447             self._recording = True

   448             for event in self._events:

   449                 event.restore()

   450 

   451     def reset(self):

   452         """Reset the mocker state.

   453 

   454         This will restore environment changes, if currently in replay

   455         mode, and then remove all events previously recorded.

   456         """

   457         if not self._recording:

   458             self.restore()

   459         self.unorder()

   460         del self._events[:]

   461 

   462     def get_events(self):

   463         """Return all recorded events."""

   464         return self._events[:]

   465 

   466     def add_event(self, event):

   467         """Add an event.

   468 

   469         This method is used internally by the implementation, and

   470         shouldn't be needed on normal mocker usage.

   471         """

   472         self._events.append(event)

   473         if self._ordering:

   474             orderer = event.add_task(Orderer(event.path))

   475             if self._last_orderer:

   476                 orderer.add_dependency(self._last_orderer)

   477             self._last_orderer = orderer

   478         return event

   479 

   480     def verify(self):

   481         """Check if all expectations were met, and raise AssertionError if not.

   482 

   483         The exception message will include a nice description of which

   484         expectations were not met, and why.

   485         """

   486         errors = []

   487         for event in self._events:

   488             try:

   489                 event.verify()

   490             except AssertionError, e:

   491                 error = str(e)

   492                 if not error:

   493                     raise RuntimeError("Empty error message from %r"

   494                                        % event)

   495                 errors.append(error)

   496         if errors:

   497             message = [ERROR_PREFIX + "Unmet expectations:", ""]

   498             for error in errors:

   499                 lines = error.splitlines()

   500                 message.append("=> " + lines.pop(0))

   501                 message.extend([" " + line for line in lines])

   502                 message.append("")

   503             raise AssertionError(os.linesep.join(message))

   504 

   505     def mock(self, spec_and_type=None, spec=None, type=None,

   506              name=None, count=True):

   507         """Return a new mock object.

   508 

   509         @param spec_and_type: Handy positional argument which sets both

   510                      spec and type.

   511         @param spec: Method calls will be checked for correctness against

   512                      the given class.

   513         @param type: If set, the Mock's __class__ attribute will return

   514                      the given type.  This will make C{isinstance()} calls

   515                      on the object work.

   516         @param name: Name for the mock object, used in the representation of

   517                      expressions.  The name is rarely needed, as it's usually

   518                      guessed correctly from the variable name used.

   519         @param count: If set to false, expressions may be executed any number

   520                      of times, unless an expectation is explicitly set using

   521                      the L{count()} method.  By default, expressions are

   522                      expected once.

   523         """

   524         if spec_and_type is not None:

   525             spec = type = spec_and_type

   526         return Mock(self, spec=spec, type=type, name=name, count=count)

   527 

   528     def proxy(self, object, spec=True, type=True, name=None, count=True,

   529               passthrough=True):

   530         """Return a new mock object which proxies to the given object.

   531  

   532         Proxies are useful when only part of the behavior of an object

   533         is to be mocked.  Unknown expressions may be passed through to

   534         the real implementation implicitly (if the C{passthrough} argument

   535         is True), or explicitly (using the L{passthrough()} method

   536         on the event).

   537 

   538         @param object: Real object to be proxied, and replaced by the mock

   539                        on replay mode.  It may also be an "import path",

   540                        such as C{"time.time"}, in which case the object

   541                        will be the C{time} function from the C{time} module.

   542         @param spec: Method calls will be checked for correctness against

   543                      the given object, which may be a class or an instance

   544                      where attributes will be looked up.  Defaults to the

   545                      the C{object} parameter.  May be set to None explicitly,

   546                      in which case spec checking is disabled.  Checks may

   547                      also be disabled explicitly on a per-event basis with

   548                      the L{nospec()} method.

   549         @param type: If set, the Mock's __class__ attribute will return

   550                      the given type.  This will make C{isinstance()} calls

   551                      on the object work.  Defaults to the type of the

   552                      C{object} parameter.  May be set to None explicitly.

   553         @param name: Name for the mock object, used in the representation of

   554                      expressions.  The name is rarely needed, as it's usually

   555                      guessed correctly from the variable name used.

   556         @param count: If set to false, expressions may be executed any number

   557                      of times, unless an expectation is explicitly set using

   558                      the L{count()} method.  By default, expressions are

   559                      expected once.

   560         @param passthrough: If set to False, passthrough of actions on the

   561                             proxy to the real object will only happen when

   562                             explicitly requested via the L{passthrough()}

   563                             method.

   564         """

   565         if isinstance(object, basestring):

   566             if name is None:

   567                 name = object

   568             import_stack = object.split(".")

   569             attr_stack = []

   570             while import_stack:

   571                 module_path = ".".join(import_stack)

   572                 try:

   573                     object = __import__(module_path, {}, {}, [""])

   574                 except ImportError:

   575                     attr_stack.insert(0, import_stack.pop())

   576                     if not import_stack:

   577                         raise

   578                     continue

   579                 else:

   580                     for attr in attr_stack:

   581                         object = getattr(object, attr)

   582                     break

   583         if spec is True:

   584             spec = object

   585         if type is True:

   586             type = __builtin__.type(object)

   587         return Mock(self, spec=spec, type=type, object=object,

   588                     name=name, count=count, passthrough=passthrough)

   589 

   590     def replace(self, object, spec=True, type=True, name=None, count=True,

   591                 passthrough=True):

   592         """Create a proxy, and replace the original object with the mock.

   593 

   594         On replay, the original object will be replaced by the returned

   595         proxy in all dictionaries found in the running interpreter via

   596         the garbage collecting system.  This should cover module

   597         namespaces, class namespaces, instance namespaces, and so on.

   598 

   599         @param object: Real object to be proxied, and replaced by the mock

   600                        on replay mode.  It may also be an "import path",

   601                        such as C{"time.time"}, in which case the object

   602                        will be the C{time} function from the C{time} module.

   603         @param spec: Method calls will be checked for correctness against

   604                      the given object, which may be a class or an instance

   605                      where attributes will be looked up.  Defaults to the

   606                      the C{object} parameter.  May be set to None explicitly,

   607                      in which case spec checking is disabled.  Checks may

   608                      also be disabled explicitly on a per-event basis with

   609                      the L{nospec()} method.

   610         @param type: If set, the Mock's __class__ attribute will return

   611                      the given type.  This will make C{isinstance()} calls

   612                      on the object work.  Defaults to the type of the

   613                      C{object} parameter.  May be set to None explicitly.

   614         @param name: Name for the mock object, used in the representation of

   615                      expressions.  The name is rarely needed, as it's usually

   616                      guessed correctly from the variable name used.

   617         @param passthrough: If set to False, passthrough of actions on the

   618                             proxy to the real object will only happen when

   619                             explicitly requested via the L{passthrough()}

   620                             method.

   621         """

   622         mock = self.proxy(object, spec, type, name, count, passthrough)

   623         event = self._get_replay_restore_event()

   624         event.add_task(ProxyReplacer(mock))

   625         return mock

   626 

   627     def patch(self, object, spec=True):

   628         """Patch an existing object to reproduce recorded events.

   629 

   630         @param object: Class or instance to be patched.

   631         @param spec: Method calls will be checked for correctness against

   632                      the given object, which may be a class or an instance

   633                      where attributes will be looked up.  Defaults to the

   634                      the C{object} parameter.  May be set to None explicitly,

   635                      in which case spec checking is disabled.  Checks may

   636                      also be disabled explicitly on a per-event basis with

   637                      the L{nospec()} method.

   638 

   639         The result of this method is still a mock object, which can be

   640         used like any other mock object to record events.  The difference

   641         is that when the mocker is put on replay mode, the *real* object

   642         will be modified to behave according to recorded expectations.

   643 

   644         Patching works in individual instances, and also in classes.

   645         When an instance is patched, recorded events will only be

   646         considered on this specific instance, and other instances should

   647         behave normally.  When a class is patched, the reproduction of

   648         events will be considered on any instance of this class once

   649         created (collectively).

   650 

   651         Observe that, unlike with proxies which catch only events done

   652         through the mock object, *all* accesses to recorded expectations

   653         will be considered;  even these coming from the object itself

   654         (e.g. C{self.hello()} is considered if this method was patched).

   655         While this is a very powerful feature, and many times the reason

   656         to use patches in the first place, it's important to keep this

   657         behavior in mind.

   658 

   659         Patching of the original object only takes place when the mocker

   660         is put on replay mode, and the patched object will be restored

   661         to its original state once the L{restore()} method is called

   662         (explicitly, or implicitly with alternative conventions, such as

   663         a C{with mocker:} block, or a MockerTestCase class).

   664         """

   665         if spec is True:

   666             spec = object

   667         patcher = Patcher()

   668         event = self._get_replay_restore_event()

   669         event.add_task(patcher)

   670         mock = Mock(self, object=object, patcher=patcher,

   671                     passthrough=True, spec=spec)

   672         object.__mocker_mock__ = mock

   673         return mock

   674 

   675     def act(self, path):

   676         """This is called by mock objects whenever something happens to them.

   677 

   678         This method is part of the implementation between the mocker

   679         and mock objects.

   680         """

   681         if self._recording:

   682             event = self.add_event(Event(path))

   683             for recorder in self._recorders:

   684                 recorder(self, event)

   685             return Mock(self, path)

   686         else:

   687             # First run events that may run, then run unsatisfied events, then

   688             # ones not previously run. We put the index in the ordering tuple

   689             # instead of the actual event because we want a stable sort

   690             # (ordering between 2 events is undefined).

   691             events = self._events

   692             order = [(events[i].satisfied()*2 + events[i].has_run(), i)

   693                      for i in range(len(events))]

   694             order.sort()

   695             postponed = None

   696             for weight, i in order:

   697                 event = events[i]

   698                 if event.matches(path):

   699                     if event.may_run(path):

   700                         return event.run(path)

   701                     elif postponed is None:

   702                         postponed = event

   703             if postponed is not None:

   704                 return postponed.run(path)

   705             raise MatchError(ERROR_PREFIX + "Unexpected expression: %s" % path)

   706 

   707     def get_recorders(cls, self):

   708         """Return recorders associated with this mocker class or instance.

   709 

   710         This method may be called on mocker instances and also on mocker

   711         classes.  See the L{add_recorder()} method for more information.

   712         """

   713         return (self or cls)._recorders[:]

   714     get_recorders = classinstancemethod(get_recorders)

   715 

   716     def add_recorder(cls, self, recorder):

   717         """Add a recorder to this mocker class or instance.

   718 

   719         @param recorder: Callable accepting C{(mocker, event)} as parameters.

   720 

   721         This is part of the implementation of mocker.

   722 

   723         All registered recorders are called for translating events that

   724         happen during recording into expectations to be met once the state

   725         is switched to replay mode.

   726 

   727         This method may be called on mocker instances and also on mocker

   728         classes.  When called on a class, the recorder will be used by

   729         all instances, and also inherited on subclassing.  When called on

   730         instances, the recorder is added only to the given instance.

   731         """

   732         (self or cls)._recorders.append(recorder)

   733         return recorder

   734     add_recorder = classinstancemethod(add_recorder)

   735 

   736     def remove_recorder(cls, self, recorder):

   737         """Remove the given recorder from this mocker class or instance.

   738 

   739         This method may be called on mocker classes and also on mocker

   740         instances.  See the L{add_recorder()} method for more information.

   741         """

   742         (self or cls)._recorders.remove(recorder)

   743     remove_recorder = classinstancemethod(remove_recorder)

   744 

   745     def result(self, value):

   746         """Make the last recorded event return the given value on replay.

   747         

   748         @param value: Object to be returned when the event is replayed.

   749         """

   750         self.call(lambda *args, **kwargs: value)

   751 

   752     def generate(self, sequence):

   753         """Last recorded event will return a generator with the given sequence.

   754 

   755         @param sequence: Sequence of values to be generated.

   756         """

   757         def generate(*args, **kwargs):

   758             for value in sequence:

   759                 yield value

   760         self.call(generate)

   761 

   762     def throw(self, exception):

   763         """Make the last recorded event raise the given exception on replay.

   764 

   765         @param exception: Class or instance of exception to be raised.

   766         """

   767         def raise_exception(*args, **kwargs):

   768             raise exception

   769         self.call(raise_exception)

   770 

   771     def call(self, func):

   772         """Make the last recorded event cause the given function to be called.

   773 

   774         @param func: Function to be called.

   775 

   776         The result of the function will be used as the event result.

   777         """

   778         self._events[-1].add_task(FunctionRunner(func))

   779 

   780     def count(self, min, max=False):

   781         """Last recorded event must be replayed between min and max times.

   782 

   783         @param min: Minimum number of times that the event must happen.

   784         @param max: Maximum number of times that the event must happen.  If

   785                     not given, it defaults to the same value of the C{min}

   786                     parameter.  If set to None, there is no upper limit, and

   787                     the expectation is met as long as it happens at least

   788                     C{min} times.

   789         """

   790         event = self._events[-1]

   791         for task in event.get_tasks():

   792             if isinstance(task, RunCounter):

   793                 event.remove_task(task)

   794         event.add_task(RunCounter(min, max))

   795 

   796     def is_ordering(self):

   797         """Return true if all events are being ordered.

   798 

   799         See the L{order()} method.

   800         """

   801         return self._ordering

   802 

   803     def unorder(self):

   804         """Disable the ordered mode.

   805         

   806         See the L{order()} method for more information.

   807         """

   808         self._ordering = False

   809         self._last_orderer = None

   810 

   811     def order(self, *path_holders):

   812         """Create an expectation of order between two or more events.

   813 

   814         @param path_holders: Objects returned as the result of recorded events.

   815 

   816         By default, mocker won't force events to happen precisely in

   817         the order they were recorded.  Calling this method will change

   818         this behavior so that events will only match if reproduced in

   819         the correct order.

   820 

   821         There are two ways in which this method may be used.  Which one

   822         is used in a given occasion depends only on convenience.

   823 

   824         If no arguments are passed, the mocker will be put in a mode where

   825         all the recorded events following the method call will only be met

   826         if they happen in order.  When that's used, the mocker may be put

   827         back in unordered mode by calling the L{unorder()} method, or by

   828         using a 'with' block, like so::

   829 

   830             with mocker.ordered():

   831                 <record events>

   832 

   833         In this case, only expressions in <record events> will be ordered,

   834         and the mocker will be back in unordered mode after the 'with' block.

   835 

   836         The second way to use it is by specifying precisely which events

   837         should be ordered.  As an example::

   838 

   839             mock = mocker.mock()

   840             expr1 = mock.hello()

   841             expr2 = mock.world

   842             expr3 = mock.x.y.z

   843             mocker.order(expr1, expr2, expr3)

   844 

   845         This method of ordering only works when the expression returns

   846         another object.

   847 

   848         Also check the L{after()} and L{before()} methods, which are

   849         alternative ways to perform this.

   850         """

   851         if not path_holders:

   852             self._ordering = True

   853             return OrderedContext(self)

   854 

   855         last_orderer = None

   856         for path_holder in path_holders:

   857             if type(path_holder) is Path:

   858                 path = path_holder

   859             else:

   860                 path = path_holder.__mocker_path__

   861             for event in self._events:

   862                 if event.path is path:

   863                     for task in event.get_tasks():

   864                         if isinstance(task, Orderer):

   865                             orderer = task

   866                             break

   867                     else:

   868                         orderer = Orderer(path)

   869                         event.add_task(orderer)

   870                     if last_orderer:

   871                         orderer.add_dependency(last_orderer)

   872                     last_orderer = orderer

   873                     break

   874 

   875     def after(self, *path_holders):

   876         """Last recorded event must happen after events referred to.

   877 

   878         @param path_holders: Objects returned as the result of recorded events

   879                              which should happen before the last recorded event

   880 

   881         As an example, the idiom::

   882 

   883             expect(mock.x).after(mock.y, mock.z)

   884 

   885         is an alternative way to say::

   886 

   887             expr_x = mock.x

   888             expr_y = mock.y

   889             expr_z = mock.z

   890             mocker.order(expr_y, expr_x)

   891             mocker.order(expr_z, expr_x)

   892 

   893         See L{order()} for more information.

   894         """

   895         last_path = self._events[-1].path

   896         for path_holder in path_holders:

   897             self.order(path_holder, last_path)

   898 

   899     def before(self, *path_holders):

   900         """Last recorded event must happen before events referred to.

   901 

   902         @param path_holders: Objects returned as the result of recorded events

   903                              which should happen after the last recorded event

   904 

   905         As an example, the idiom::

   906 

   907             expect(mock.x).before(mock.y, mock.z)

   908 

   909         is an alternative way to say::

   910 

   911             expr_x = mock.x

   912             expr_y = mock.y

   913             expr_z = mock.z

   914             mocker.order(expr_x, expr_y)

   915             mocker.order(expr_x, expr_z)

   916 

   917         See L{order()} for more information.

   918         """

   919         last_path = self._events[-1].path

   920         for path_holder in path_holders:

   921             self.order(last_path, path_holder)

   922 

   923     def nospec(self):

   924         """Don't check method specification of real object on last event.

   925 

   926         By default, when using a mock created as the result of a call to

   927         L{proxy()}, L{replace()}, and C{patch()}, or when passing the spec

   928         attribute to the L{mock()} method, method calls on the given object

   929         are checked for correctness against the specification of the real

   930         object (or the explicitly provided spec).

   931 

   932         This method will disable that check specifically for the last

   933         recorded event.

   934         """

   935         event = self._events[-1]

   936         for task in event.get_tasks():

   937             if isinstance(task, SpecChecker):

   938                 event.remove_task(task)

   939 

   940     def passthrough(self, result_callback=None):

   941         """Make the last recorded event run on the real object once seen.

   942 

   943         @param result_callback: If given, this function will be called with

   944             the result of the *real* method call as the only argument.

   945 

   946         This can only be used on proxies, as returned by the L{proxy()}

   947         and L{replace()} methods, or on mocks representing patched objects,

   948         as returned by the L{patch()} method.

   949         """

   950         event = self._events[-1]

   951         if event.path.root_object is None:

   952             raise TypeError("Mock object isn't a proxy")

   953         event.add_task(PathExecuter(result_callback))

   954 

   955     def __enter__(self):

   956         """Enter in a 'with' context.  This will run replay()."""

   957         self.replay()

   958         return self

   959 

   960     def __exit__(self, type, value, traceback):

   961         """Exit from a 'with' context.

   962 

   963         This will run restore() at all times, but will only run verify()

   964         if the 'with' block itself hasn't raised an exception.  Exceptions

   965         in that block are never swallowed.

   966         """

   967         self.restore()

   968         if type is None:

   969             self.verify()

   970         return False

   971 

   972     def _get_replay_restore_event(self):

   973         """Return unique L{ReplayRestoreEvent}, creating if needed.

   974 

   975         Some tasks only want to replay/restore.  When that's the case,

   976         they shouldn't act on other events during replay.  Also, they

   977         can all be put in a single event when that's the case.  Thus,

   978         we add a single L{ReplayRestoreEvent} as the first element of

   979         the list.

   980         """

   981         if not self._events or type(self._events[0]) != ReplayRestoreEvent:

   982             self._events.insert(0, ReplayRestoreEvent())

   983         return self._events[0]

   984 

   985 

   986 class OrderedContext(object):

   987 

   988     def __init__(self, mocker):

   989         self._mocker = mocker

   990 

   991     def __enter__(self):

   992         return None

   993 

   994     def __exit__(self, type, value, traceback):

   995         self._mocker.unorder()

   996 

   997 

   998 class Mocker(MockerBase):

   999     __doc__ = MockerBase.__doc__

  1000 

  1001 # Decorator to add recorders on the standard Mocker class.

  1002 recorder = Mocker.add_recorder

  1003 

  1004 

  1005 # --------------------------------------------------------------------

  1006 # Mock object.

  1007 

  1008 class Mock(object):

  1009 

  1010     def __init__(self, mocker, path=None, name=None, spec=None, type=None,

  1011                  object=None, passthrough=False, patcher=None, count=True):

  1012         self.__mocker__ = mocker

  1013         self.__mocker_path__ = path or Path(self, object)

  1014         self.__mocker_name__ = name

  1015         self.__mocker_spec__ = spec

  1016         self.__mocker_object__ = object

  1017         self.__mocker_passthrough__ = passthrough

  1018         self.__mocker_patcher__ = patcher

  1019         self.__mocker_replace__ = False

  1020         self.__mocker_type__ = type

  1021         self.__mocker_count__ = count

  1022 

  1023     def __mocker_act__(self, kind, args=(), kwargs={}, object=None):

  1024         if self.__mocker_name__ is None:

  1025             self.__mocker_name__ = find_object_name(self, 2)

  1026         action = Action(kind, args, kwargs, self.__mocker_path__)

  1027         path = self.__mocker_path__ + action

  1028         if object is not None:

  1029             path.root_object = object

  1030         try:

  1031             return self.__mocker__.act(path)

  1032         except MatchError, exception:

  1033             root_mock = path.root_mock

  1034             if (path.root_object is not None and

  1035                 root_mock.__mocker_passthrough__):

  1036                 return path.execute(path.root_object)

  1037             # Reinstantiate to show raise statement on traceback, and

  1038             # also to make the traceback shown shorter.

  1039             raise MatchError(str(exception))

  1040         except AssertionError, e:

  1041             lines = str(e).splitlines()

  1042             message = [ERROR_PREFIX + "Unmet expectation:", ""]

  1043             message.append("=> " + lines.pop(0))

  1044             message.extend([" " + line for line in lines])

  1045             message.append("")

  1046             raise AssertionError(os.linesep.join(message))

  1047 

  1048     def __getattribute__(self, name):

  1049         if name.startswith("__mocker_"):

  1050             return super(Mock, self).__getattribute__(name)

  1051         if name == "__class__":

  1052             if self.__mocker__.is_recording() or self.__mocker_type__ is None:

  1053                 return type(self)

  1054             return self.__mocker_type__

  1055         return self.__mocker_act__("getattr", (name,))

  1056 

  1057     def __setattr__(self, name, value):

  1058         if name.startswith("__mocker_"):

  1059             return super(Mock, self).__setattr__(name, value)

  1060         return self.__mocker_act__("setattr", (name, value))

  1061 

  1062     def __delattr__(self, name):

  1063         return self.__mocker_act__("delattr", (name,))

  1064 

  1065     def __call__(self, *args, **kwargs):

  1066         return self.__mocker_act__("call", args, kwargs)

  1067 

  1068     def __contains__(self, value):

  1069         return self.__mocker_act__("contains", (value,))

  1070 

  1071     def __getitem__(self, key):

  1072         return self.__mocker_act__("getitem", (key,))

  1073 

  1074     def __setitem__(self, key, value):

  1075         return self.__mocker_act__("setitem", (key, value))

  1076 

  1077     def __delitem__(self, key):

  1078         return self.__mocker_act__("delitem", (key,))

  1079 

  1080     def __len__(self):

  1081         # MatchError is turned on an AttributeError so that list() and

  1082         # friends act properly when trying to get length hints on

  1083         # something that doesn't offer them.

  1084         try:

  1085             result = self.__mocker_act__("len")

  1086         except MatchError, e:

  1087             raise AttributeError(str(e))

  1088         if type(result) is Mock:

  1089             return 0

  1090         return result

  1091 

  1092     def __nonzero__(self):

  1093         try:

  1094             return self.__mocker_act__("nonzero")

  1095         except MatchError, e:

  1096             return True

  1097 

  1098     def __iter__(self):

  1099         # XXX On py3k, when next() becomes __next__(), we'll be able

  1100         #     to return the mock itself because it will be considered

  1101         #     an iterator (we'll be mocking __next__ as well, which we

  1102         #     can't now).

  1103         result = self.__mocker_act__("iter")

  1104         if type(result) is Mock:

  1105             return iter([])

  1106         return result

  1107 

  1108     # When adding a new action kind here, also add support for it on

  1109     # Action.execute() and Path.__str__().

  1110 

  1111 

  1112 def find_object_name(obj, depth=0):

  1113     """Try to detect how the object is named on a previous scope."""

  1114     try:

  1115         frame = sys._getframe(depth+1)

  1116     except:

  1117         return None

  1118     for name, frame_obj in frame.f_locals.iteritems():

  1119         if frame_obj is obj:

  1120             return name

  1121     self = frame.f_locals.get("self")

  1122     if self is not None:

  1123         try:

  1124             items = list(self.__dict__.iteritems())

  1125         except:

  1126             pass

  1127         else:

  1128             for name, self_obj in items:

  1129                 if self_obj is obj:

  1130                     return name

  1131     return None

  1132 

  1133 

  1134 # --------------------------------------------------------------------

  1135 # Action and path.

  1136