pytest fixtures nuts and bolts

I’d like to wrap up this recent series of pytest fixture posts by presenting my version of some sort of reference.
Since this post is running a bit long, here are some links to the content buried in here.

• Bare bones example
• Three ways to use a fixture
  • Name it, usefixtures, and autouse.
  • Usefixtures example
• Fixture features
  • Return value
  • Finalizer is teardown
  • Request object
  • Scope
  • Params
    • Toy example
    • Real example
  • Autouse
  • Multiple fixtures
  • Modularity: fixtures using other fixtures
• Experimental and still to cover
  • yield_fixture
  • ids

Since I’m planning on using this for my own reference, I’ll throw a couple more links in here at the top to stuff I find useful regarding pytest fixtures.

• pytest tutorial, my original introduction post. I still use it as a reference.
• pytest support for xunit style fixtures, setup/teardown for function, method, module, class. I still use this old style sometimes.
• pytest API, specifically, the fixtures and requests part

And… while I’m throwing links around, here are the other posts in the series:

• part 1: pytest fixtures
• part 2: xunit style pytest fixtures
• part 3: pytest fixtures easy example

I’m trying to keep the examples in this post kind of small-ish.
However, I do run the risk of being too terse. (or too verbose).
It’s also possible that the order I’ve laid things out is odd. I’ve done a lot of copy/paste from code editor and bash window to get this post put together.

Please let me know:

• if I’ve mucked up some copy/paste and there is something bizarre in here.
• if I’ve been too terse or unclear.
• if what I’m stating is completely wrong. Especially this one
• if you actually made it to the end without wanting to throw something at me.

Note about common code

For all the examples, the test file I’m running has this at the top:

`

from __future__ import print_function
import pytest

`

However, I’m not going to copy it into every code block below.
I’m also running each example with: `

$py.test -s file_name.py

`

Bare bones example

Here’s a super basic fixture, and a couple tests that use it. `

@pytest.fixture()
def before():
    print('\nbefore each test')
 
def test_1(before):
    print('test_1()')

def test_2(before):
    print('test_2()')

`

With the default parameters for ‘pytest.fixture()’, the fixture is going to be called for every test that names the fixture in it’s parameter list.
Output: `

before each test
test_1()
.
before each test
test_2()
.

`

Three ways to use a fixture

1. name it from the test.
   Just like the top example
2. usefixtures decorator
   You can mark a test or a test class with ‘pytest.mark.usefixtures()’ and include a list of fixtures to be used with the test or class of tests.
   This is especially convenient when dealing with test classes.
   It also is useful when converting unittest classes to use pytest fixtures.
   I’ll give an example shortly.
3. autouse
   Powerful, but possibly dangerous.
   Covered in the next section.

Usefixtures example

Here’s a quick example of the decorator.
The first example can be written like this: `

@pytest.mark.usefixtures("before") 
def test_1():
    print('test_1()')

@pytest.mark.usefixtures("before") 
def test_2():
    print('test_2()')

`

Or, this: `

class Test:
    @pytest.mark.usefixtures("before")
    def test_1(self):
        print('test_1()')

    @pytest.mark.usefixtures("before")
    def test_2(self):
        print('test_2()')

`

Or, this: `

@pytest.mark.usefixtures("before")
class Test:
    def test_1(self):
        print('test_1()')

    def test_2(self):
        print('test_2()')

`

All with the same effect.

Fixture features

If I fill in the default parameters for ‘pytest.fixture()’ and add a request param to my fixture, it looks like this, but doesn’t run any different. `

@pytest.fixture(scope='function', params=None, autouse=False)
def before(request):
    print('\nbefore()')
    return None

` Now lets take a look at these features.

• Return value
• Finalizer is teardown
• Request objects
• Scope
• Params
  • Toy example
  • Real example
• Autouse
• Multiple fixtures
• Modularity: fixtures using other fixtures

Return value

In the bare bones example, the fixture returns ‘None’.
That’s becuase it’s just some code I want to run before my test, like traditional setup functions from nose or unittest.

However, you can return anything you want from the fixture function.
If your fixture is setting up some data, or reading a file, or opening a connection to a database, then access to that data or resources is what you ought to return from the fixture.

Returning some data from a fixture. `

@pytest.fixture()
def some_data():
    data = {'foo':1, 'bar':2, 'baz':3}
    return data

def test_foo(some_data):
    assert some_data['foo'] == 1

`

Returning a database object: `

@pytest.fixture()
def cheese_db(request):
    print('\n[setup] cheese_db, connect to db')
    # code to connect to your db 
    a_dictionary_for_now = {'Brie': 'No.', 'Camenbert': 'Ah! We have Camenbert, yessir.'}
    def fin():
        print('\n[teardown] cheese_db finalizer, disconnect from db')
    request.addfinalizer(fin)
    return a_dictionary_for_now

def test_cheese_database(cheese_db):
    print('in test_cheese_database()')
    for variety in cheese_db.keys():
        print('%s : %s' % (variety, cheese_db[variety]))

def test_brie(cheese_db):
    print('in test_brie()')
    assert cheese_db['Brie'] == 'No.' 

def test_camenbert(cheese_db):
    print('in test_camenbert()')
    assert cheese_db['Camenbert'] != 'No.' 

`

Finalizer is teardown

In the previous code example, the ‘cheese_db’ fixture has this bit of code:

`

def cheese_db(request):
    ...
    def fin():
        print('\n[teardown] cheese_db finalizer, disconnect from db')
    request.addfinalizer(fin)
    ...

`

The ‘fin’ function is acting as the ‘teardown’ for the fixture.
There’s nothing special about the name.
You can name it ‘teardown’ or ‘cheese_db_teardown’ or ‘something_else’.
It doesn’t matter.

The finalizer is called after all of the tests that use the fixture.
If you’ve used parameterized fixtures, the finalizer is called between instances of the parameterized fixture changes.

Scope

Scope controls how often a fixture gets called. The default is “function”.
Here are the options for scope:

<td align="left">
  Run once per test
</td>

<td align="left">
  Run once per class of tests
</td>

<td align="left">
  Run once per module
</td>

<td align="left">
  Run once per session
</td>

Since the default scope is “function”, the cheese db example will open and close the db for every test. `

[setup] cheese_db, connect to db
in test_cheese_database()
Camenbert : Ah! We have Camenbert, yessir.
Brie : No.
.
[teardown] cheese_db finalizer, disconnect from db

[setup] cheese_db, connect to db
in test_brie()
.
[teardown] cheese_db finalizer, disconnect from db

[setup] cheese_db, connect to db
in test_camenbert()
.
[teardown] cheese_db finalizer, disconnect from db

`

This doesn’t really make sense. Especially if connecting is a time consuming operation.

Change the scope: `

@pytest.fixture(scope="module")
def cheese_db(request):
  ...

`

And let’s re-run it: `

[setup] cheese_db, connect to db
in test_cheese_database()
Camenbert : Ah! We have Camenbert, yessir.
Brie : No.
.in test_brie()
.in test_camenbert()
.
[teardown] cheese_db finalizer, disconnect from db

`

That’s better.

Request objects

In the cheese db example, the fixture includes a request parameter. You need the request parameter to a fixture to add a finilizer.

However, it has other uses too.

In the example below, I’m showing the use (well, printing stuff) of some of the items. See pytest API for a full list.

`

@pytest.fixture()
def my_fixture(request):
    print('\n-----------------')
    print('fixturename : %s' % request.fixturename)
    print('scope       : %s' % request.scope)
    print('function    : %s' % request.function.__name__)
    print('cls         : %s' % request.cls)
    print('module      : %s' % request.module.__name__)
    print('fspath      : %s' % request.fspath)
    print('-----------------')

    if request.function.__name__ == 'test_three':
        request.applymarker(pytest.mark.xfail)

def test_one(my_fixture):
    print('test_one():')

class TestClass():
    def test_two(self, my_fixture):
        print('test_two()')

def test_three(my_fixture):
    print('test_three()')
    assert False

`

Params

An optional parameter to the fixture decorator is ‘params’.
It defaults to ‘None’.

For each value in params, the fixture will be called with request.param filled in with that value.
Tests that use the fixture will be called once FOR EACH value in params.

Toy example

An example is in order here.

This first example is a silly one, but does show the mechanics, and the utility of both the -v flag and how well py.test deals with failures of parameterized tests.

`

@pytest.fixture( params=[1,2,3] )
def test_data(request):
    return request.param

def test_not_2(test_data):
    print('test_data: %s' % test_data)
    assert test_data != 2

`

This should run ‘test_not_2’ three times, and fail when 2 is passed in.
I’ll run it both without and with the -v flag `

> py.test test_params.py
============================= test session starts =============================
platform win32 -- Python 2.7.2 -- pytest-2.4.2
collected 3 items

test_params.py .F.

================================== FAILURES ===================================
________________________________ test_not_2[2] ________________________________

test_data = 2

    def test_not_2(test_data):
        print('test_data: %s' % test_data)
>       assert test_data != 2
E       assert 2 != 2

test_params.py:10: AssertionError
------------------------------- Captured stdout -------------------------------
test_data: 2
===================== 1 failed, 2 passed in 0.02 seconds ======================
> py.test -v test_params.py
============================= test session starts =============================
platform win32 -- Python 2.7.2 -- pytest-2.4.2 -- C:\Python27\python2.7.exe
collecting ... collected 3 items

test_params.py:8: test_not_2[1] PASSED
test_params.py:8: test_not_2[2] FAILED
test_params.py:8: test_not_2[3] PASSED

================================== FAILURES ===================================
________________________________ test_not_2[2] ________________________________

test_data = 2

    def test_not_2(test_data):
        print('test_data: %s' % test_data)
>       assert test_data != 2
E       assert 2 != 2

test_params.py:10: AssertionError
------------------------------- Captured stdout -------------------------------
test_data: 2
===================== 1 failed, 2 passed in 0.02 seconds ======================

`

Real example

Now for a more real world usage of parameterization, input and expected output.

Here’s a rewrite of the markdown test from the pytest introduction post.
The ‘run_markdown’ function is a software API adapter, which takes care of calling the markdown script on the command line.

`

from markdown_adapter import run_markdown
 
@pytest.fixture( params=[
    # tuple with (input, expectedOutput)
    ('regular text'   , 'regular text
'),
    ('*em tags*'      , '
em tags
'),
    ('**strong tags**', '
strong tags
')
    ])
def test_data(request):
    return request.param

def test_markdown(test_data):
    (the_input, the_expected_output) = test_data
    the_output = run_markdown(the_input)
    print('\ntest_markdown():')
    print('  input   : %s' % the_input)
    print('  output  : %s' % the_output)
    print('  expected: %s' % the_expected_output)
    assert the_output == the_expected_output

`

The output makes it clear that the one test ‘test_markdown’ is called 3 times.
Of course, the print statements are unnecessary.
I left them in for demo purposes.

`

> py.test -s  test_markdown.py
============================= test session starts =============================
platform win32 -- Python 2.7.2 -- pytest-2.4.2
collected 3 items

test_markdown.py
test_markdown():
  input   : regular text
  output  : regular text
  expected: regular text
.
test_markdown():
  input   : *em tags*
  output  : em tags
  expected: em tags
.
test_markdown():
  input   : **strong tags**
  output  : strong tags
  expected: strong tags
.

========================== 3 passed in 0.11 seconds ===========================

`

Normally, you don’t need the print statements to see what’s going on.

I’m going to take the print statements out, and change the ‘expected’ string of the last input value to show how py.test is quite helpful in pointing out the data set that fails.

`

@pytest.fixture( params=[
    # tuple with (input, expectedOutput)
    ('regular text'   , 'regular text
'),
    ('*em tags*'      , '
em tags
'),
    ('**strong tags**', '
strong tags
')
    ])
def test_data(request):
    return request.param

def test_markdown(test_data):
    (the_input, the_expected_output) = test_data
    the_output = run_markdown(the_input)
    assert the_output == the_expected_output

> py.test test_markdown2.py
============================= test session starts =============================
platform win32 -- Python 2.7.2 -- pytest-2.4.2
collected 3 items

test_markdown2.py ..F

================================== FAILURES ===================================
__________________________ test_markdown[test_data2] __________________________

test_data = ('**strong tags**', 'strong tags
')

    def test_markdown(test_data):
        (the_input, the_expected_output) = test_data
        the_output = run_markdown(the_input)
>       assert the_output == the_expected_output
E       assert '
s...
' == '
st...tags
'
E         - 
strong tags
E         ?                         ^^^^^^
E         + strong tags
E         ?                         ^^

test_markdown2.py:17: AssertionError
===================== 1 failed, 2 passed in 0.11 seconds ======================

@pytest.fixture(scope="module", autouse=True)
def mod_header(request):
    print('\n-----------------')
    print('user        : %s' % getpass.getuser())
    print('module      : %s' % request.module.__name__)
    print('-----------------')

@pytest.fixture(scope="function", autouse=True)
def func_header(request):
    print('\n-----------------')
    print('function    : %s' % request.function.__name__)
    print('time        : %s' % time.asctime())
    print('-----------------')

def test_one():
    print('in test_one()')

def test_two():
    print('in test_two()')

> py.test -s test_autouse.py
============================= test session starts =============================
platform win32 -- Python 2.7.2 -- pytest-2.4.2
collected 2 items

test_autouse.py
-----------------
user        : okken
module      : test_autouse
-----------------

-----------------
function    : test_one
time        : Tue Feb 04 17:31:20 2014
-----------------
in test_one()
.
-----------------
function    : test_two
time        : Tue Feb 04 17:31:20 2014
-----------------
in test_two()
.

========================== 2 passed in 0.02 seconds ===========================

@pytest.fixture(scope="module")
def foo(request):
    print('\nfoo setup - module fixture')
    def fin():
        print('foo teardown - module fixture')
    request.addfinalizer(fin)

@pytest.fixture()
def bar(request):
    print('bar setup - function fixture')
    def fin():
        print('bar teardown - function fixture')
    request.addfinalizer(fin)

@pytest.fixture()
def baz(request):
    print('baz setup - function fixture')
    def fin():
        print('baz teardown - function fixture')
    request.addfinalizer(fin)

def test_one(foo, bar, baz):
    print('in test_one()')

def test_two(foo, bar, baz):
    print('in test_two()')

> py.test -s test_multiple.py
============================= test session starts =============================
platform win32 -- Python 2.7.2 -- pytest-2.4.2
collected 2 items

test_multiple.py
foo setup - module fixture
bar setup - function fixture
baz setup - function fixture
in test_one()
.baz teardown - function fixture
bar teardown - function fixture
bar setup - function fixture
baz setup - function fixture
in test_two()
.baz teardown - function fixture
bar teardown - function fixture
foo teardown - module fixture

========================== 2 passed in 0.01 seconds ===========================

@pytest.fixture(scope="module")
def foo(request):
    print('\nfoo setup - module fixture')
    def fin():
        print('foo teardown - module fixture')
    request.addfinalizer(fin)

@pytest.fixture()
def bar(request, foo):
    print('bar setup - function fixture')
    def fin():
        print('bar teardown - function fixture')
    request.addfinalizer(fin)

@pytest.fixture()
def baz(request, bar):
    print('baz setup - function fixture')
    def fin():
        print('baz teardown - function fixture')
    request.addfinalizer(fin)

def test_one(baz):
    print('in test_one()')

def test_two(bar): # only use bar
    print('in test_two()')

> py.test -s test_modular.py
============================= test session starts =============================
platform win32 -- Python 2.7.2 -- pytest-2.4.2
collected 2 items

test_modular.py
foo setup - module fixture
bar setup - function fixture
baz setup - function fixture
in test_one()
.baz teardown - function fixture
bar teardown - function fixture
bar setup - function fixture
in test_two()
.bar teardown - function fixture
foo teardown - module fixture

========================== 2 passed in 0.02 seconds ===========================

@pytest.yield_fixture(scope="module")
def cheese_db():
    print('\n[setup] cheese_db, connect to db')
    a_dictionary_for_now = {'Brie': 'No.', 'Camenbert': 'Ah! We have Camenbert, yessir.'}
    yield a_dictionary_for_now
    print('\n[teardown] cheese_db finalizer, disconnect from db')

def test_brie(cheese_db):
    print('in test_brie()')
    assert cheese_db['Brie'] == 'No.' 

def test_camenbert(cheese_db):
    print('in test_camenbert()')
    assert cheese_db['Camenbert'] != 'No.' 
    

$ py.test -s pytestfixtures/test_yield.py 
====================== test session starts ======================
platform darwin -- Python 2.7.5 -- py-1.4.20 -- pytest-2.5.2
collected 2 items 

pytestfixtures/test_yield.py 
[setup] cheese_db, connect to db
in test_brie()
.in test_camenbert()
.
[teardown] cheese_db finalizer, disconnect from db

=================== 2 passed in 0.01 seconds ===================