Pytest Fixtures

Faker includes a faker fixture for pytest.

def test_faker(faker):
    assert isinstance(faker.name(), str)

Out of the box, the faker fixture returns a session-scoped Faker instance to be used across all tests in your test suite. This instance defaults to the en-US locale, it is reseeded using a seed value of 0 prior to each test, and the .unique remembered generated values are cleared.

To change the default locale, you can define a session-scoped autouse faker_session_locale fixture in your top level conftest.py. To change the default seed value, you define a session-scoped autouse faker_seed fixture. For example, if you want to use the it_IT locale and a seed value of 12345, then all you need to do is to include the following in your top level conftest.py like so:

import pytest

@pytest.fixture(scope='session', autouse=True)
def faker_session_locale():
    return ['it_IT']

@pytest.fixture(scope='session', autouse=True)
def faker_seed():
    return 12345

If you need an instance with multiple locale support, then just return a list with multiple, unique, and valid locales:

import pytest

@pytest.fixture(scope='session', autouse=True)
def faker_session_locale():
    return ['it_IT', 'ja_JP', 'en_US']

Configuration options

As mentioned above, out of the box, a session-scoped Faker instance is returned for your use. This is done so by design in order to prevent unnecessary Faker instantiations for most use cases. Of course, there are some uncommon use cases where this approach is insufficient, which is why the faker fixture is actually a function-scoped fixture that can be configured to behave differently on demand.

Important

Configuring the faker fixture requires some basic understanding of how pytest handles fixtures (more specifically scoping, sharing, injection). If you are not familiar with the topic, it is highly recommended to read up on pytest fixtures before proceeding.

Locale configuration

If a faker_locale fixture is active for a test, the faker fixture will fallback to returning a new Faker instance for that test (function-scoped), so if you do not like to use the session-scoped Faker instance, just define and activate a faker_locale fixture in the appropriate place in accordance to how pytest handles fixtures.

For example, if you need to switch to a different locale only for certain tests, you may define an autouse faker_locale fixture with a non-session scope in a submodule’s conftest.py or in the test files themselves like so:

import pytest

@pytest.fixture(scope=any_non_session_scope, autouse=True)
def faker_locale():
    return ['it_IT']

When the faker fixture is used in the relevant tests, the fixture will automatically use new Faker instances:

def test_something(faker):
    # The faker fixture here will return a new instance, not the session-scoped instance
    pass

If you want to be more explicit or if you need finer control over which tests should use a new instance, you may drop autouse=True and use manual injection:

import pytest

@pytest.fixture()
def faker_locale():
    return ['it_IT']

def test_something(faker):
    # The faker fixture will return the session-scoped instance
    pass

def test_something_else(faker, faker_locale):
    # The faker fixture will return a new instance, not the session-scoped instance
    pass

Seeding configuration

On top of faker_locale, the faker fixture also checks if a faker_seed fixture is active for a test. If there is none, a seed value of 0 will be used, and if there is one, then the return value will be used as the seed. The important thing to remember here is this: any test that uses the faker fixture, whether it returns a session-scoped or a function-scoped Faker instance, is guaranteed a seeded instance. Seeding is performed independently of the instance selection logic.

Like briefly mentioned above, defining an autouse session-scoped faker_seed fixture will affect all relevant tests in the session, but if you want to use a certain seed for a specific set of tests and just like faker_locale, you will just need to define and activate a faker_seed fixture in the appropriate place in accordance to how pytest handles fixtures. For example, if you declare this in a submodule’s conftest.py, the faker fixture will return an instance seeded using 12345 for all relevant tests under that submodule.

import pytest

@pytest.fixture(scope=any_non_session_scope,  autouse=True)
def faker_seed():
    return 12345

If you want to be more explicit or if you need finer control over which tests should use a different seed, you may drop autouse=True and use manual injection just as you would for faker_locale:

import pytest

@pytest.fixture(scope=any_non_session_scope)
def faker_seed():
    return 12345

def test_something(faker):
    # The faker fixture will use the session seed value
    pass

def test_something_else(faker, faker_seed):
    # The faker fixture will use the seed value 12345
    pass

If you need multiple different seeds for each test, or if you need to reseed halfway inside a test, you may still explicitly call seed_instance as you normally would with any Faker instance. Doing so will not affect other tests because of the faker fixture’s seeding guarantee.

# Assume the active seed value is 54321 for these tests

def test_something_first(faker):
    # The faker fixture, at first, uses seed value 54321
    do_thing_a()

    # Explicit call to seed_instance
    faker.seed_instance(12345)

    # The faker fixture now uses seed value 12345
    do_thing_b()

def test_something_second(faker):
    # The faker fixture's seed value is still 54321, not 12345
    pass