https://github.com/doist/resources
A fixture lifecycle management library
https://github.com/doist/resources
Last synced: over 1 year ago
JSON representation
A fixture lifecycle management library
- Host: GitHub
- URL: https://github.com/doist/resources
- Owner: Doist
- Created: 2013-01-19T08:11:17.000Z (over 13 years ago)
- Default Branch: master
- Last Pushed: 2024-04-02T20:57:51.000Z (over 2 years ago)
- Last Synced: 2025-03-28T10:21:37.852Z (over 1 year ago)
- Language: Python
- Size: 14.6 KB
- Stars: 17
- Watchers: 5
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.rst
Awesome Lists containing this project
README
Resources. A fixture lifecycle management for your tests
========================================================
.. image:: https://secure.travis-ci.org/Doist/resources.png?branch=master
:alt: Build Status
:target: https://secure.travis-ci.org/Doist/resources
Why do we need this library
--------------------------------------------------
We are not satisfied with classical xUnit way of setup and teardown. We prefer
concise approach of py.test over the verbosity of standard unittest.
We found ourselves copying and pasting the same boilerplate code from one test
to another or creating extensive structure of test class hierarchy.
py.test fixtures, injected in test functions as parameter names, is
different approach for fixture management. It's neither worse nor better,
but we found it to be not as flexible as we need.
Some questions, that we wanted to solve often, looked like:
- I have a py.test fixture which creates a new user with default set of
properties. Is there a way I can create a user with different name by the same
fixture?
- Is there a way to create two users in one test case with the same fixture?
- Is there an easy recipe to create a user first, and then, say, a todo item for
this particular user in another, separate, fixture?
Sure enough, we can handle or work around all these issues somehow with xUnit
setups and teardowns or py.test fixtures, but we wanted something more flexible,
easy and convenient to use. That's why we created ``resources`` library.
How do we use it
----------------
First, we define functions which we call "resource makers". These makers are
responsible for creating and destroying resources. It's like setup and teardown
in one callable.
.. code-block:: python
from resources import resources
@resources.register_func
def user(email='joe@example.com', password='password', username='Joe'):
user = User.objects.create(email=email, password=password, username=username)
try:
yield user
finally:
user.delete()
The flow is simple: we create, we yield, we destroy.
We get a number of resource makers, and we group them into modules, like
`tests/resources_core.py`, `tests/resources_users.py`, etc.
Then, in a test file, where we plan to use resources, we import the same global
object, load resource modules we need, and activate them in tests.
.. code-block:: python
from resources import resources
resources.register_mod('tests.resources_core')
resources.register_mod('tests.resources_users')
def test_user_properties():
with resources.user_ctx() as user:
assert user.username == 'Joe'
This is where a little bit of magic happens. Once you define and register the
resource maker with name ``foo``, a context manager ``foo_ctx`` is created for
your convenience. This context manager creates a new resource instance with the
corresponding maker function, and destroys the object the way you defined, once
the code flow abandons a wrapping "with"-context.
When it shines
---------------
At this point and maybe not so exciting. Yeah, everyone can write the code like
this, the difference is that we actually *did it* :-). We also have a bunch
of nifty features making the whole stuff more interesting.
Feature 1. Customizeable resources
----------------------------------
Contexts are better than py.test fixtures, because they are customizeable.
Provide everything you need to context manager, and it will be passed to
resource maker function as an arguments.
.. code-block:: python
def test_user_properties():
with resources.user_ctx(name='Mary') as user:
assert user.username == 'Mary'
Feature 2. Global object scope and dependent resources
------------------------------------------------------
We need to have access to resources at different stages of our tests: to get
access to object's properties and methods, to initiate another, dependent
fixture instance, and finally to tear down everything.
As soon as you enter the context with ``resources.foo_ctx()`` a variable
``resources.foo`` will be created and will be available from everywhere,
including your test function, and other resource makers.
The latter fact is especially important, because it's the way we manage
dependent resources. Yet we need some conventions, which resource is created
first, and so on.
.. code-block:: python
@resources.register_func
def todo_item(content='Foo'):
item = TodoItem.objects.create(user=resources.user, content=content)
We agreed that we create user resource first, and todo item afterwards, and
created a new resource maker, taking advantage of this convention.
We use it like this:
.. code-block:: python
def test_todo_item_properties():
with resources.user_ctx(), resources.todo_item_ctx():
assert resources.todo_item.content == 'Foo'
By the way, if you are still stuck with python2.6, several context managers in
the same "with" expression aren't available for you yet. Use ``contextlib.nested``
to avoid deep indentation.
Feature 3. Several resources of the same class, and tuneable resource names
---------------------------------------------------------------------------
Sometimes we need to create a couple of resources of the same type, instead of
just one instance. It's not a problem, if you don't want to use global
namespace to get access to them. Otherwise you must create a unique identifier
for every resource.
Actually, it's trivial. All you should do is provide a special `_name` attribute
to context manager constructor. This attribute won't be passed to your resource
maker function.
.. code-block:: python
def test_a_couple_of_users():
with resources.user_ctx(username='Adam', _name='adam'), \
resurces.user_ctx(username='Eve', _name='eve'):
assert resources.adam.username == 'Adam'
assert resources.eve.username == 'Eve'
Feature 4. Function decorators
------------------------------
Context manager can work as a decorator too. When we use it like this, an extra
argument will be passed to the function.
.. code-block:: python
@resources.user_ctx()
def test_user_properties(user):
assert user.username == 'Joe'
We should say that usually it works, but to make it work along with py.test
which performs deep introspection of function signatures, we made in with some
"dirty hacks" inside, and you may find out that in some cases the chain of
decorators dies with a misleading exception. We'd recommend to use context
managers instead of decorators, wherever possible.
Feature 5. Resource managers
----------------------------
Yes, we do use setup and teardown methods too. If every function in your test
suite uses the same set of resources, it would be counterproductive to write
the same chain of decorators or context managers over and over again.
In this case we use another concept: resource managers. Every resource maker
``foo`` creates the ``resources.foo_mgr`` instance, having `start` and
`stop` methods. The `start` method accepts all arguments which
the `foo_ctx` function does, including special `_name` argument.
The `stop` method has only one optional `_name` argument, and is used to
destroy previously created instance.
Here is a py.test example
.. code-block:: python
def setup_function(func):
resources.user_mgr.start(username='Mary')
def test_user_properties():
assert resources.user.username == 'Mary'
def teardown_function(func):
resources.user_mgr.stop()
Feature 6. Built-in console and debugger
----------------------------------------
Sometimes it's nice to take a look on what's going on within test function and
get access at some point to python console or debugger.
Usually you probably do something like
.. code-block:: python
import pdb; pdb.set_trace()
Or, if you need to get shell and have IPython installed
.. code-block:: python
from IPython import embed; embed()
As it happens often, we added to resources two functions, launching either
debugger or python console inside your test function.
.. code-block:: python
from resources import resources
def test_something():
resources.pdb() # to launch debugger
resources.shell() # to launch Python REPL
If you install IPython and ipdb (`pip install IPython ipdb`), you get more
friendly versions of consoles, otherwise resources fall back to built-in python
console and debugger.
Launch `py.test` with `-s` switch to be able to fall into interactive console.
It's especially cool that resources object is autocomplete-friendly and it
works well in IPython
.. code-block:: python
In [1]: resources.
resources.john resources.pdb resources.register_mod
resources.mary resources.register_func resources.shell
In [1]: resources.mary
Out[1]: {'name': 'Mary Moe'}
In [2]: resources.user_mgr.start()
Out[2]: {'name': 'John Doe'}
In [3]: resources.todo
resources.todo_item_ctx resources.todo_item_mgr
In [3]: resources.todo_item_mgr.start()
Out[3]: {'text': 'Do something', 'user': {'name': 'John Doe'}}
In [4]: resources.todo
resources.todo_item resources.todo_item_ctx resources.todo_item_mgr
In [4]: resources.todo_item
Out[4]: {'text': 'Do something', 'user': {'name': 'John Doe'}}
Feature 7. Globally accessible storage of constants
---------------------------------------------------
This feature is not something unique to `resources` module. Pretty much every
object can act this way, but it is handy to have a convention about the
way you store your test-related constants.
It may work like this.
.. code-block::
resources.TEST_DIRECTORY = '/tmp/foo'
resources.DOMAIN_NAME = 'example.com'
resources.SECRET_KEY = 'foobar'
And then, in the test file.
.. code-block::
from resources import resources
resoures.register_mod('')
def test_constants():
assert resources.TEST_DIRECTORY == '/tmp/foo'
assert resources.DOMAIN_NAME == 'example.com'
assert resources.SECRET_KEY == 'foobar'
Conclusion
----------
The `resources` library works for us in py.test environment. We don't see any
reasons why it shouldn't work the same way with nose or classic unitttests.
It works for python versions 2.6, 2.7 and 3.3.
Please bear in mind that the library *is not thread safe*, as we are happy with
single threaded tests at this time.
And after all... Seven extra features to improve your test suites for free! What
are you waiting for? It's already improved the quailty of our lives in
`Doist Inc `_, and we do hope it will do the same for your
projects.