The Tor Browser: comparison python/mock-1.0.0/docs/index.txt

--1:000000000000
+:33eda10c009e
+====================================
+Mock - Mocking and Testing Library
+====================================
+.. currentmodule:: mock
+:Author: `Michael Foord
+<http://www.voidspace.org.uk/python/weblog/index.shtml>`_
+:Version: |release|
+:Date: 2012/10/07
+:Homepage: `Mock Homepage`_
+:Download: `Mock on PyPI`_
+:Documentation: `PDF Documentation
+<http://www.voidspace.org.uk/downloads/mock-1.0.0.pdf>`_
+:License: `BSD License`_
+:Support: `Mailing list (testing-in-python@lists.idyll.org)
+<http://lists.idyll.org/listinfo/testing-in-python>`_
+:Issue tracker: `Google code project
+<http://code.google.com/p/mock/issues/list>`_
+.. _Mock Homepage: http://www.voidspace.org.uk/python/mock/
+.. _BSD License: http://www.voidspace.org.uk/python/license.shtml
+.. currentmodule:: mock
+.. module:: mock
+:synopsis: Mock object and testing library.
+.. index:: introduction
+mock is a library for testing in Python. It allows you to replace parts of
+your system under test with mock objects and make assertions about how they
+have been used.
+mock is now part of the Python standard library, available as `unittest.mock
+<http://docs.python.org/py3k/library/unittest.mock.html#module-unittest.mock>`_
+in Python 3.3 onwards.
+mock provides a core :class:`Mock` class removing the need to create a host
+of stubs throughout your test suite. After performing an action, you can make
+assertions about which methods / attributes were used and arguments they were
+called with. You can also specify return values and set needed attributes in
+the normal way.
+Additionally, mock provides a :func:`patch` decorator that handles patching
+module and class level attributes within the scope of a test, along with
+:const:`sentinel` for creating unique objects. See the `quick guide`_ for
+some examples of how to use :class:`Mock`, :class:`MagicMock` and
+:func:`patch`.
+Mock is very easy to use and is designed for use with
+`unittest <http://pypi.python.org/pypi/unittest2>`_. Mock is based on
+the 'action -> assertion' pattern instead of `'record -> replay'` used by many
+mocking frameworks.
+mock is tested on Python versions 2.4-2.7, Python 3 plus the latest versions of
+Jython and PyPy.
+.. testsetup::
+class ProductionClass(object):
+def method(self, *args):
+pass
+module = sys.modules['module'] = ProductionClass
+ProductionClass.ClassName1 = ProductionClass
+ProductionClass.ClassName2 = ProductionClass
+API Documentation
+=================
+.. toctree::
+:maxdepth: 2
+mock
+patch
+helpers
+sentinel
+magicmock
+User Guide
+==========
+.. toctree::
+:maxdepth: 2
+getting-started
+examples
+compare
+changelog
+.. index:: installing
+Installing
+==========
+The current version is |release|. Mock is stable and widely used. If you do
+find any bugs, or have suggestions for improvements / extensions
+then please contact us.
+* `mock on PyPI <http://pypi.python.org/pypi/mock>`_
+* `mock documentation as PDF
+<http://www.voidspace.org.uk/downloads/mock-1.0.0.pdf>`_
+* `Google Code Home & Mercurial Repository <http://code.google.com/p/mock/>`_
+.. index:: repository
+.. index:: hg
+You can checkout the latest development version from the Google Code Mercurial
+repository with the following command:
+``hg clone https://mock.googlecode.com/hg/ mock``
+.. index:: pip
+.. index:: easy_install
+.. index:: setuptools
+If you have pip, setuptools or distribute you can install mock with:
+| ``easy_install -U mock``
+| ``pip install -U mock``
+Alternatively you can download the mock distribution from PyPI and after
+unpacking run:
+``python setup.py install``
+Quick Guide
+===========
+:class:`Mock` and :class:`MagicMock` objects create all attributes and
+methods as you access them and store details of how they have been used. You
+can configure them, to specify return values or limit what attributes are
+available, and then make assertions about how they have been used:
+.. doctest::
+>>> from mock import MagicMock
+>>> thing = ProductionClass()
+>>> thing.method = MagicMock(return_value=3)
+>>> thing.method(3, 4, 5, key='value')
+3
+>>> thing.method.assert_called_with(3, 4, 5, key='value')
+:attr:`side_effect` allows you to perform side effects, including raising an
+exception when a mock is called:
+.. doctest::
+>>> mock = Mock(side_effect=KeyError('foo'))
+>>> mock()
+Traceback (most recent call last):
+...
+KeyError: 'foo'
+>>> values = {'a': 1, 'b': 2, 'c': 3}
+>>> def side_effect(arg):
+...     return values[arg]
+...
+>>> mock.side_effect = side_effect
+>>> mock('a'), mock('b'), mock('c')
+(1, 2, 3)
+>>> mock.side_effect = [5, 4, 3, 2, 1]
+>>> mock(), mock(), mock()
+(5, 4, 3)
+Mock has many other ways you can configure it and control its behaviour. For
+example the `spec` argument configures the mock to take its specification
+from another object. Attempting to access attributes or methods on the mock
+that don't exist on the spec will fail with an `AttributeError`.
+The :func:`patch` decorator / context manager makes it easy to mock classes or
+objects in a module under test. The object you specify will be replaced with a
+mock (or other object) during the test and restored when the test ends:
+.. doctest::
+>>> from mock import patch
+>>> @patch('module.ClassName2')
+... @patch('module.ClassName1')
+... def test(MockClass1, MockClass2):
+...     module.ClassName1()
+...     module.ClassName2()
+...     assert MockClass1 is module.ClassName1
+...     assert MockClass2 is module.ClassName2
+...     assert MockClass1.called
+...     assert MockClass2.called
+...
+>>> test()
+.. note::
+When you nest patch decorators the mocks are passed in to the decorated
+function in the same order they applied (the normal *python* order that
+decorators are applied). This means from the bottom up, so in the example
+above the mock for `module.ClassName1` is passed in first.
+With `patch` it matters that you patch objects in the namespace where they
+are looked up. This is normally straightforward, but for a quick guide
+read :ref:`where to patch <where-to-patch>`.
+As well as a decorator `patch` can be used as a context manager in a with
+statement:
+.. doctest::
+>>> with patch.object(ProductionClass, 'method', return_value=None) as mock_method:
+...     thing = ProductionClass()
+...     thing.method(1, 2, 3)
+...
+>>> mock_method.assert_called_once_with(1, 2, 3)
+There is also :func:`patch.dict` for setting values in a dictionary just
+during a scope and restoring the dictionary to its original state when the test
+ends:
+.. doctest::
+>>> foo = {'key': 'value'}
+>>> original = foo.copy()
+>>> with patch.dict(foo, {'newkey': 'newvalue'}, clear=True):
+...     assert foo == {'newkey': 'newvalue'}
+...
+>>> assert foo == original
+Mock supports the mocking of Python :ref:`magic methods <magic-methods>`. The
+easiest way of using magic methods is with the :class:`MagicMock` class. It
+allows you to do things like:
+.. doctest::
+>>> mock = MagicMock()
+>>> mock.__str__.return_value = 'foobarbaz'
+>>> str(mock)
+'foobarbaz'
+>>> mock.__str__.assert_called_with()
+Mock allows you to assign functions (or other Mock instances) to magic methods
+and they will be called appropriately. The `MagicMock` class is just a Mock
+variant that has all of the magic methods pre-created for you (well, all the
+useful ones anyway).
+The following is an example of using magic methods with the ordinary Mock
+class:
+.. doctest::
+>>> mock = Mock()
+>>> mock.__str__ = Mock(return_value='wheeeeee')
+>>> str(mock)
+'wheeeeee'
+For ensuring that the mock objects in your tests have the same api as the
+objects they are replacing, you can use :ref:`auto-speccing <auto-speccing>`.
+Auto-speccing can be done through the `autospec` argument to patch, or the
+:func:`create_autospec` function. Auto-speccing creates mock objects that
+have the same attributes and methods as the objects they are replacing, and
+any functions and methods (including constructors) have the same call
+signature as the real object.
+This ensures that your mocks will fail in the same way as your production
+code if they are used incorrectly:
+.. doctest::
+>>> from mock import create_autospec
+>>> def function(a, b, c):
+...     pass
+...
+>>> mock_function = create_autospec(function, return_value='fishy')
+>>> mock_function(1, 2, 3)
+'fishy'
+>>> mock_function.assert_called_once_with(1, 2, 3)
+>>> mock_function('wrong arguments')
+Traceback (most recent call last):
+...
+TypeError: <lambda>() takes exactly 3 arguments (1 given)
+`create_autospec` can also be used on classes, where it copies the signature of
+the `__init__` method, and on callable objects where it copies the signature of
+the `__call__` method.
+.. index:: references
+.. index:: articles
+References
+==========
+Articles, blog entries and other stuff related to testing with Mock:
+* `Imposing a No DB Discipline on Django unit tests
+<https://github.com/carljm/django-testing-slides/blob/master/models/30_no_database.md>`_
+* `mock-django: tools for mocking the Django ORM and models
+<https://github.com/dcramer/mock-django>`_
+* `PyCon 2011 Video: Testing with mock <https://blip.tv/file/4881513>`_
+* `Mock objects in Python
+<http://noopenblockers.com/2012/01/06/mock-objects-in-python/>`_
+* `Python: Injecting Mock Objects for Powerful Testing
+<http://blueprintforge.com/blog/2012/01/08/python-injecting-mock-objects-for-powerful-testing/>`_
+* `Python Mock: How to assert a substring of logger output
+<http://www.michaelpollmeier.com/python-mock-how-to-assert-a-substring-of-logger-output/>`_
+* `Mocking Django <http://www.mattjmorrison.com/2011/09/mocking-django.html>`_
+* `Mocking dates and other classes that can't be modified
+<http://williamjohnbert.com/2011/07/how-to-unit-testing-in-django-with-mocking-and-patching/>`_
+* `Mock recipes <http://konryd.blogspot.com/2010/06/mock-recipies.html>`_
+* `Mockity mock mock - some love for the mock module
+<http://konryd.blogspot.com/2010/05/mockity-mock-mock-some-love-for-mock.html>`_
+* `Coverage and Mock (with django)
+<http://mattsnider.com/python/mock-and-coverage/>`_
+* `Python Unit Testing with Mock <http://www.insomnihack.com/?p=194>`_
+* `Getting started with Python Mock
+<http://myadventuresincoding.wordpress.com/2011/02/26/python-python-mock-cheat-sheet/>`_
+* `Smart Parameter Checks with mock
+<http://tobyho.com/2011/03/24/smart-parameter-checks-in/>`_
+* `Python mock testing techniques and tools
+<http://agiletesting.blogspot.com/2009/07/python-mock-testing-techniques-and.html>`_
+* `How To Test Django Template Tags
+<http://techblog.ironfroggy.com/2008/10/how-to-test.html>`_
+* `A presentation on Unit Testing with Mock
+<http://pypap.blogspot.com/2008/10/newbie-nugget-unit-testing-with-mock.html>`_
+* `Mocking with Django and Google AppEngine
+<http://michael-a-nelson.blogspot.com/2008/09/mocking-with-django-and-google-app.html>`_
+.. index:: tests
+.. index:: unittest2
+Tests
+=====
+Mock uses `unittest2 <http://pypi.python.org/pypi/unittest2>`_ for its own
+test suite. In order to run it, use the `unit2` script that comes with
+`unittest2` module on a checkout of the source repository:
+`unit2 discover`
+If you have `setuptools <http://pypi.python.org/pypi/distribute>`_ as well as
+unittest2 you can run:
+``python setup.py test``
+On Python 3.2 you can use ``unittest`` module from the standard library.
+``python3.2 -m unittest discover``
+.. index:: Python 3
+On Python 3 the tests for unicode are skipped as they are not relevant. On
+Python 2.4 tests that use the with statements are skipped as the with statement
+is invalid syntax on Python 2.4.
+.. index:: older versions
+Older Versions
+==============
+Documentation for older versions of mock:
+* `mock 0.8 <http://www.voidspace.org.uk/python/mock/0.8/>`_
+* `mock 0.7 <http://www.voidspace.org.uk/python/mock/0.7/>`_
+* `mock 0.6 <http://www.voidspace.org.uk/python/mock/0.6.0/>`_
+Docs from the in-development version of `mock` can be found at
+`mock.readthedocs.org <http://mock.readthedocs.org>`_.
+Terminology
+===========
+Terminology for objects used to replace other ones can be confusing. Terms
+like double, fake, mock, stub, and spy are all used with varying meanings.
+In `classic mock terminology
+<http://xunitpatterns.com/Mocks,%20Fakes,%20Stubs%20and%20Dummies.html>`_
+:class:`mock.Mock` is a `spy <http://xunitpatterns.com/Test%20Spy.html>`_ that
+allows for *post-mortem* examination. This is what I call the "action ->
+assertion" [#]_ pattern of testing.
+I'm not however a fan of this "statically typed mocking terminology"
+promulgated by `Martin Fowler
+<http://martinfowler.com/articles/mocksArentStubs.html>`_. It confuses usage
+patterns with implementation and prevents you from using natural terminology
+when discussing mocking.
+I much prefer duck typing, if an object used in your test suite looks like a
+mock object and quacks like a mock object then it's fine to call it a mock, no
+matter what the implementation looks like.
+This terminology is perhaps more useful in less capable languages where
+different usage patterns will *require* different implementations.
+`mock.Mock()` is capable of being used in most of the different roles
+described by Fowler, except (annoyingly / frustratingly / ironically) a Mock
+itself!
+How about a simpler definition: a "mock object" is an object used to replace a
+real one in a system under test.
+.. [#] This pattern is called "AAA" by some members of the testing community;
+"Arrange - Act - Assert".

The Tor Browser / file comparison

comparison: python/mock-1.0.0/docs/index.txt

python/mock-1.0.0/docs/index.txt