.. _how-to-fixtures: How to use fixtures ==================== .. seealso:: :ref:`about-fixtures` .. seealso:: :ref:`Fixtures reference ` "Requesting" fixtures --------------------- At a basic level, test functions request fixtures they require by declaring them as arguments. When pytest goes to run a test, it looks at the parameters in that test function's signature, and then searches for fixtures that have the same names as those parameters. Once pytest finds them, it runs those fixtures, captures what they returned (if anything), and passes those objects into the test function as arguments. Quick example ^^^^^^^^^^^^^ .. code-block:: python import pytest class Fruit: def __init__(self, name): self.name = name self.cubed = False def cube(self): self.cubed = True class FruitSalad: def __init__(self, *fruit_bowl): self.fruit = fruit_bowl self._cube_fruit() def _cube_fruit(self): for fruit in self.fruit: fruit.cube() # Arrange @pytest.fixture def fruit_bowl(): return [Fruit("apple"), Fruit("banana")] def test_fruit_salad(fruit_bowl): # Act fruit_salad = FruitSalad(*fruit_bowl) # Assert assert all(fruit.cubed for fruit in fruit_salad.fruit) In this example, ``test_fruit_salad`` "**requests**" ``fruit_bowl`` (i.e. ``def test_fruit_salad(fruit_bowl):``), and when pytest sees this, it will execute the ``fruit_bowl`` fixture function and pass the object it returns into ``test_fruit_salad`` as the ``fruit_bowl`` argument. Here's roughly what's happening if we were to do it by hand: .. code-block:: python def fruit_bowl(): return [Fruit("apple"), Fruit("banana")] def test_fruit_salad(fruit_bowl): # Act fruit_salad = FruitSalad(*fruit_bowl) # Assert assert all(fruit.cubed for fruit in fruit_salad.fruit) # Arrange bowl = fruit_bowl() test_fruit_salad(fruit_bowl=bowl) Fixtures can **request** other fixtures ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ One of pytest's greatest strengths is its extremely flexible fixture system. It allows us to boil down complex requirements for tests into more simple and organized functions, where we only need to have each one describe the things they are dependent on. We'll get more into this further down, but for now, here's a quick example to demonstrate how fixtures can use other fixtures: .. code-block:: python # contents of test_append.py import pytest # Arrange @pytest.fixture def first_entry(): return "a" # Arrange @pytest.fixture def order(first_entry): return [first_entry] def test_string(order): # Act order.append("b") # Assert assert order == ["a", "b"] Notice that this is the same example from above, but very little changed. The fixtures in pytest **request** fixtures just like tests. All the same **requesting** rules apply to fixtures that do for tests. Here's how this example would work if we did it by hand: .. code-block:: python def first_entry(): return "a" def order(first_entry): return [first_entry] def test_string(order): # Act order.append("b") # Assert assert order == ["a", "b"] entry = first_entry() the_list = order(first_entry=entry) test_string(order=the_list) Fixtures are reusable ^^^^^^^^^^^^^^^^^^^^^ One of the things that makes pytest's fixture system so powerful, is that it gives us the ability to define a generic setup step that can be reused over and over, just like a normal function would be used. Two different tests can request the same fixture and have pytest give each test their own result from that fixture. This is extremely useful for making sure tests aren't affected by each other. We can use this system to make sure each test gets its own fresh batch of data and is starting from a clean state so it can provide consistent, repeatable results. Here's an example of how this can come in handy: .. code-block:: python # contents of test_append.py import pytest # Arrange @pytest.fixture def first_entry(): return "a" # Arrange @pytest.fixture def order(first_entry): return [first_entry] def test_string(order): # Act order.append("b") # Assert assert order == ["a", "b"] def test_int(order): # Act order.append(2) # Assert assert order == ["a", 2] Each test here is being given its own copy of that ``list`` object, which means the ``order`` fixture is getting executed twice (the same is true for the ``first_entry`` fixture). If we were to do this by hand as well, it would look something like this: .. code-block:: python def first_entry(): return "a" def order(first_entry): return [first_entry] def test_string(order): # Act order.append("b") # Assert assert order == ["a", "b"] def test_int(order): # Act order.append(2) # Assert assert order == ["a", 2] entry = first_entry() the_list = order(first_entry=entry) test_string(order=the_list) entry = first_entry() the_list = order(first_entry=entry) test_int(order=the_list) A test/fixture can **request** more than one fixture at a time ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Tests and fixtures aren't limited to **requesting** a single fixture at a time. They can request as many as they like. Here's another quick example to demonstrate: .. code-block:: python # contents of test_append.py import pytest # Arrange @pytest.fixture def first_entry(): return "a" # Arrange @pytest.fixture def second_entry(): return 2 # Arrange @pytest.fixture def order(first_entry, second_entry): return [first_entry, second_entry] # Arrange @pytest.fixture def expected_list(): return ["a", 2, 3.0] def test_string(order, expected_list): # Act order.append(3.0) # Assert assert order == expected_list Fixtures can be **requested** more than once per test (return values are cached) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Fixtures can also be **requested** more than once during the same test, and pytest won't execute them again for that test. This means we can **request** fixtures in multiple fixtures that are dependent on them (and even again in the test itself) without those fixtures being executed more than once. .. code-block:: python # contents of test_append.py import pytest # Arrange @pytest.fixture def first_entry(): return "a" # Arrange @pytest.fixture def order(): return [] # Act @pytest.fixture def append_first(order, first_entry): return order.append(first_entry) def test_string_only(append_first, order, first_entry): # Assert assert order == [first_entry] If a **requested** fixture was executed once for every time it was **requested** during a test, then this test would fail because both ``append_first`` and ``test_string_only`` would see ``order`` as an empty list (i.e. ``[]``), but since the return value of ``order`` was cached (along with any side effects executing it may have had) after the first time it was called, both the test and ``append_first`` were referencing the same object, and the test saw the effect ``append_first`` had on that object. .. _`autouse`: .. _`autouse fixtures`: Autouse fixtures (fixtures you don't have to request) ----------------------------------------------------- Sometimes you may want to have a fixture (or even several) that you know all your tests will depend on. "Autouse" fixtures are a convenient way to make all tests automatically **request** them. This can cut out a lot of redundant **requests**, and can even provide more advanced fixture usage (more on that further down). We can make a fixture an autouse fixture by passing in ``autouse=True`` to the fixture's decorator. Here's a simple example for how they can be used: .. code-block:: python # contents of test_append.py import pytest @pytest.fixture def first_entry(): return "a" @pytest.fixture def order(first_entry): return [] @pytest.fixture(autouse=True) def append_first(order, first_entry): return order.append(first_entry) def test_string_only(order, first_entry): assert order == [first_entry] def test_string_and_int(order, first_entry): order.append(2) assert order == [first_entry, 2] In this example, the ``append_first`` fixture is an autouse fixture. Because it happens automatically, both tests are affected by it, even though neither test **requested** it. That doesn't mean they *can't* be **requested** though; just that it isn't *necessary*. .. _smtpshared: Scope: sharing fixtures across classes, modules, packages or session -------------------------------------------------------------------- .. regendoc:wipe Fixtures requiring network access depend on connectivity and are usually time-expensive to create. Extending the previous example, we can add a ``scope="module"`` parameter to the :py:func:`@pytest.fixture ` invocation to cause a ``smtp_connection`` fixture function, responsible to create a connection to a preexisting SMTP server, to only be invoked once per test *module* (the default is to invoke once per test *function*). Multiple test functions in a test module will thus each receive the same ``smtp_connection`` fixture instance, thus saving time. Possible values for ``scope`` are: ``function``, ``class``, ``module``, ``package`` or ``session``. The next example puts the fixture function into a separate ``conftest.py`` file so that tests from multiple test modules in the directory can access the fixture function: .. code-block:: python # content of conftest.py import smtplib import pytest @pytest.fixture(scope="module") def smtp_connection(): return smtplib.SMTP("smtp.gmail.com", 587, timeout=5) .. code-block:: python # content of test_module.py def test_ehlo(smtp_connection): response, msg = smtp_connection.ehlo() assert response == 250 assert b"smtp.gmail.com" in msg assert 0 # for demo purposes def test_noop(smtp_connection): response, msg = smtp_connection.noop() assert response == 250 assert 0 # for demo purposes Here, the ``test_ehlo`` needs the ``smtp_connection`` fixture value. pytest will discover and call the :py:func:`@pytest.fixture ` marked ``smtp_connection`` fixture function. Running the test looks like this: .. code-block:: pytest $ pytest test_module.py =========================== test session starts ============================ platform linux -- Python 3.x.y, pytest-8.x.y, pluggy-1.x.y rootdir: /home/sweet/project collected 2 items test_module.py FF [100%] ================================= FAILURES ================================= ________________________________ test_ehlo _________________________________ smtp_connection = def test_ehlo(smtp_connection): response, msg = smtp_connection.ehlo() assert response == 250 assert b"smtp.gmail.com" in msg > assert 0 # for demo purposes E assert 0 test_module.py:7: AssertionError ________________________________ test_noop _________________________________ smtp_connection = def test_noop(smtp_connection): response, msg = smtp_connection.noop() assert response == 250 > assert 0 # for demo purposes E assert 0 test_module.py:13: AssertionError ========================= short test summary info ========================== FAILED test_module.py::test_ehlo - assert 0 FAILED test_module.py::test_noop - assert 0 ============================ 2 failed in 0.12s ============================= You see the two ``assert 0`` failing and more importantly you can also see that the **exactly same** ``smtp_connection`` object was passed into the two test functions because pytest shows the incoming argument values in the traceback. As a result, the two test functions using ``smtp_connection`` run as quick as a single one because they reuse the same instance. If you decide that you rather want to have a session-scoped ``smtp_connection`` instance, you can simply declare it: .. code-block:: python @pytest.fixture(scope="session") def smtp_connection(): # the returned fixture value will be shared for # all tests requesting it ... Fixture scopes ^^^^^^^^^^^^^^ Fixtures are created when first requested by a test, and are destroyed based on their ``scope``: * ``function``: the default scope, the fixture is destroyed at the end of the test. * ``class``: the fixture is destroyed during teardown of the last test in the class. * ``module``: the fixture is destroyed during teardown of the last test in the module. * ``package``: the fixture is destroyed during teardown of the last test in the package where the fixture is defined, including sub-packages and sub-directories within it. * ``session``: the fixture is destroyed at the end of the test session. .. note:: Pytest only caches one instance of a fixture at a time, which means that when using a parametrized fixture, pytest may invoke a fixture more than once in the given scope. .. _dynamic scope: Dynamic scope ^^^^^^^^^^^^^ .. versionadded:: 5.2 In some cases, you might want to change the scope of the fixture without changing the code. To do that, pass a callable to ``scope``. The callable must return a string with a valid scope and will be executed only once - during the fixture definition. It will be called with two keyword arguments - ``fixture_name`` as a string and ``config`` with a configuration object. This can be especially useful when dealing with fixtures that need time for setup, like spawning a docker container. You can use the command-line argument to control the scope of the spawned containers for different environments. See the example below. .. code-block:: python def determine_scope(fixture_name, config): if config.getoption("--keep-containers", None): return "session" return "function" @pytest.fixture(scope=determine_scope) def docker_container(): yield spawn_container() .. _`finalization`: Teardown/Cleanup (AKA Fixture finalization) ------------------------------------------- When we run our tests, we'll want to make sure they clean up after themselves so they don't mess with any other tests (and also so that we don't leave behind a mountain of test data to bloat the system). Fixtures in pytest offer a very useful teardown system, which allows us to define the specific steps necessary for each fixture to clean up after itself. This system can be leveraged in two ways. .. _`yield fixtures`: 1. ``yield`` fixtures (recommended) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. regendoc: wipe "Yield" fixtures ``yield`` instead of ``return``. With these fixtures, we can run some code and pass an object back to the requesting fixture/test, just like with the other fixtures. The only differences are: 1. ``return`` is swapped out for ``yield``. 2. Any teardown code for that fixture is placed *after* the ``yield``. Once pytest figures out a linear order for the fixtures, it will run each one up until it returns or yields, and then move on to the next fixture in the list to do the same thing. Once the test is finished, pytest will go back down the list of fixtures, but in the *reverse order*, taking each one that yielded, and running the code inside it that was *after* the ``yield`` statement. As a simple example, consider this basic email module: .. code-block:: python # content of emaillib.py class MailAdminClient: def create_user(self): return MailUser() def delete_user(self, user): # do some cleanup pass class MailUser: def __init__(self): self.inbox = [] def send_email(self, email, other): other.inbox.append(email) def clear_mailbox(self): self.inbox.clear() class Email: def __init__(self, subject, body): self.subject = subject self.body = body Let's say we want to test sending email from one user to another. We'll have to first make each user, then send the email from one user to the other, and finally assert that the other user received that message in their inbox. If we want to clean up after the test runs, we'll likely have to make sure the other user's mailbox is emptied before deleting that user, otherwise the system may complain. Here's what that might look like: .. code-block:: python # content of test_emaillib.py from emaillib import Email, MailAdminClient import pytest @pytest.fixture def mail_admin(): return MailAdminClient() @pytest.fixture def sending_user(mail_admin): user = mail_admin.create_user() yield user mail_admin.delete_user(user) @pytest.fixture def receiving_user(mail_admin): user = mail_admin.create_user() yield user user.clear_mailbox() mail_admin.delete_user(user) def test_email_received(sending_user, receiving_user): email = Email(subject="Hey!", body="How's it going?") sending_user.send_email(email, receiving_user) assert email in receiving_user.inbox Because ``receiving_user`` is the last fixture to run during setup, it's the first to run during teardown. There is a risk that even having the order right on the teardown side of things doesn't guarantee a safe cleanup. That's covered in a bit more detail in :ref:`safe teardowns`. .. code-block:: pytest $ pytest -q test_emaillib.py . [100%] 1 passed in 0.12s Handling errors for yield fixture """"""""""""""""""""""""""""""""" If a yield fixture raises an exception before yielding, pytest won't try to run the teardown code after that yield fixture's ``yield`` statement. But, for every fixture that has already run successfully for that test, pytest will still attempt to tear them down as it normally would. 2. Adding finalizers directly ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ While yield fixtures are considered to be the cleaner and more straightforward option, there is another choice, and that is to add "finalizer" functions directly to the test's `request-context`_ object. It brings a similar result as yield fixtures, but requires a bit more verbosity. In order to use this approach, we have to request the `request-context`_ object (just like we would request another fixture) in the fixture we need to add teardown code for, and then pass a callable, containing that teardown code, to its ``addfinalizer`` method. We have to be careful though, because pytest will run that finalizer once it's been added, even if that fixture raises an exception after adding the finalizer. So to make sure we don't run the finalizer code when we wouldn't need to, we would only add the finalizer once the fixture would have done something that we'd need to teardown. Here's how the previous example would look using the ``addfinalizer`` method: .. code-block:: python # content of test_emaillib.py from emaillib import Email, MailAdminClient import pytest @pytest.fixture def mail_admin(): return MailAdminClient() @pytest.fixture def sending_user(mail_admin): user = mail_admin.create_user() yield user mail_admin.delete_user(user) @pytest.fixture def receiving_user(mail_admin, request): user = mail_admin.create_user() def delete_user(): mail_admin.delete_user(user) request.addfinalizer(delete_user) return user @pytest.fixture def email(sending_user, receiving_user, request): _email = Email(subject="Hey!", body="How's it going?") sending_user.send_email(_email, receiving_user) def empty_mailbox(): receiving_user.clear_mailbox() request.addfinalizer(empty_mailbox) return _email def test_email_received(receiving_user, email): assert email in receiving_user.inbox It's a bit longer than yield fixtures and a bit more complex, but it does offer some nuances for when you're in a pinch. .. code-block:: pytest $ pytest -q test_emaillib.py . [100%] 1 passed in 0.12s Note on finalizer order """""""""""""""""""""""" Finalizers are executed in a first-in-last-out order. For yield fixtures, the first teardown code to run is from the right-most fixture, i.e. the last test parameter. .. code-block:: python # content of test_finalizers.py import pytest def test_bar(fix_w_yield1, fix_w_yield2): print("test_bar") @pytest.fixture def fix_w_yield1(): yield print("after_yield_1") @pytest.fixture def fix_w_yield2(): yield print("after_yield_2") .. code-block:: pytest $ pytest -s test_finalizers.py =========================== test session starts ============================ platform linux -- Python 3.x.y, pytest-8.x.y, pluggy-1.x.y rootdir: /home/sweet/project collected 1 item test_finalizers.py test_bar .after_yield_2 after_yield_1 ============================ 1 passed in 0.12s ============================= For finalizers, the first fixture to run is last call to `request.addfinalizer`. .. code-block:: python # content of test_finalizers.py from functools import partial import pytest @pytest.fixture def fix_w_finalizers(request): request.addfinalizer(partial(print, "finalizer_2")) request.addfinalizer(partial(print, "finalizer_1")) def test_bar(fix_w_finalizers): print("test_bar") .. code-block:: pytest $ pytest -s test_finalizers.py =========================== test session starts ============================ platform linux -- Python 3.x.y, pytest-8.x.y, pluggy-1.x.y rootdir: /home/sweet/project collected 1 item test_finalizers.py test_bar .finalizer_1 finalizer_2 ============================ 1 passed in 0.12s ============================= This is so because yield fixtures use `addfinalizer` behind the scenes: when the fixture executes, `addfinalizer` registers a function that resumes the generator, which in turn calls the teardown code. .. _`safe teardowns`: Safe teardowns -------------- The fixture system of pytest is *very* powerful, but it's still being run by a computer, so it isn't able to figure out how to safely teardown everything we throw at it. If we aren't careful, an error in the wrong spot might leave stuff from our tests behind, and that can cause further issues pretty quickly. For example, consider the following tests (based off of the mail example from above): .. code-block:: python # content of test_emaillib.py from emaillib import Email, MailAdminClient import pytest @pytest.fixture def setup(): mail_admin = MailAdminClient() sending_user = mail_admin.create_user() receiving_user = mail_admin.create_user() email = Email(subject="Hey!", body="How's it going?") sending_user.send_email(email, receiving_user) yield receiving_user, email receiving_user.clear_mailbox() mail_admin.delete_user(sending_user) mail_admin.delete_user(receiving_user) def test_email_received(setup): receiving_user, email = setup assert email in receiving_user.inbox This version is a lot more compact, but it's also harder to read, doesn't have a very descriptive fixture name, and none of the fixtures can be reused easily. There's also a more serious issue, which is that if any of those steps in the setup raise an exception, none of the teardown code will run. One option might be to go with the ``addfinalizer`` method instead of yield fixtures, but that might get pretty complex and difficult to maintain (and it wouldn't be compact anymore). .. code-block:: pytest $ pytest -q test_emaillib.py . [100%] 1 passed in 0.12s .. _`safe fixture structure`: Safe fixture structure ^^^^^^^^^^^^^^^^^^^^^^ The safest and simplest fixture structure requires limiting fixtures to only making one state-changing action each, and then bundling them together with their teardown code, as :ref:`the email examples above ` showed. The chance that a state-changing operation can fail but still modify state is negligible, as most of these operations tend to be `transaction `_-based (at least at the level of testing where state could be left behind). So if we make sure that any successful state-changing action gets torn down by moving it to a separate fixture function and separating it from other, potentially failing state-changing actions, then our tests will stand the best chance at leaving the test environment the way they found it. For an example, let's say we have a website with a login page, and we have access to an admin API where we can generate users. For our test, we want to: 1. Create a user through that admin API 2. Launch a browser using Selenium 3. Go to the login page of our site 4. Log in as the user we created 5. Assert that their name is in the header of the landing page We wouldn't want to leave that user in the system, nor would we want to leave that browser session running, so we'll want to make sure the fixtures that create those things clean up after themselves. Here's what that might look like: .. note:: For this example, certain fixtures (i.e. ``base_url`` and ``admin_credentials``) are implied to exist elsewhere. So for now, let's assume they exist, and we're just not looking at them. .. code-block:: python from uuid import uuid4 from urllib.parse import urljoin from selenium.webdriver import Chrome import pytest from src.utils.pages import LoginPage, LandingPage from src.utils import AdminApiClient from src.utils.data_types import User @pytest.fixture def admin_client(base_url, admin_credentials): return AdminApiClient(base_url, **admin_credentials) @pytest.fixture def user(admin_client): _user = User(name="Susan", username=f"testuser-{uuid4()}", password="P4$$word") admin_client.create_user(_user) yield _user admin_client.delete_user(_user) @pytest.fixture def driver(): _driver = Chrome() yield _driver _driver.quit() @pytest.fixture def login(driver, base_url, user): driver.get(urljoin(base_url, "/login")) page = LoginPage(driver) page.login(user) @pytest.fixture def landing_page(driver, login): return LandingPage(driver) def test_name_on_landing_page_after_login(landing_page, user): assert landing_page.header == f"Welcome, {user.name}!" The way the dependencies are laid out means it's unclear if the ``user`` fixture would execute before the ``driver`` fixture. But that's ok, because those are atomic operations, and so it doesn't matter which one runs first because the sequence of events for the test is still `linearizable `_. But what *does* matter is that, no matter which one runs first, if the one raises an exception while the other would not have, neither will have left anything behind. If ``driver`` executes before ``user``, and ``user`` raises an exception, the driver will still quit, and the user was never made. And if ``driver`` was the one to raise the exception, then the driver would never have been started and the user would never have been made. .. note: While the ``user`` fixture doesn't *actually* need to happen before the ``driver`` fixture, if we made ``driver`` request ``user``, it might save some time in the event that making the user raises an exception, since it won't bother trying to start the driver, which is a fairly expensive operation. Running multiple ``assert`` statements safely --------------------------------------------- Sometimes you may want to run multiple asserts after doing all that setup, which makes sense as, in more complex systems, a single action can kick off multiple behaviors. pytest has a convenient way of handling this and it combines a bunch of what we've gone over so far. All that's needed is stepping up to a larger scope, then having the **act** step defined as an autouse fixture, and finally, making sure all the fixtures are targeting that higher level scope. Let's pull :ref:`an example from above `, and tweak it a bit. Let's say that in addition to checking for a welcome message in the header, we also want to check for a sign out button, and a link to the user's profile. Let's take a look at how we can structure that so we can run multiple asserts without having to repeat all those steps again. .. note:: For this example, certain fixtures (i.e. ``base_url`` and ``admin_credentials``) are implied to exist elsewhere. So for now, let's assume they exist, and we're just not looking at them. .. code-block:: python # contents of tests/end_to_end/test_login.py from uuid import uuid4 from urllib.parse import urljoin from selenium.webdriver import Chrome import pytest from src.utils.pages import LoginPage, LandingPage from src.utils import AdminApiClient from src.utils.data_types import User @pytest.fixture(scope="class") def admin_client(base_url, admin_credentials): return AdminApiClient(base_url, **admin_credentials) @pytest.fixture(scope="class") def user(admin_client): _user = User(name="Susan", username=f"testuser-{uuid4()}", password="P4$$word") admin_client.create_user(_user) yield _user admin_client.delete_user(_user) @pytest.fixture(scope="class") def driver(): _driver = Chrome() yield _driver _driver.quit() @pytest.fixture(scope="class") def landing_page(driver, login): return LandingPage(driver) class TestLandingPageSuccess: @pytest.fixture(scope="class", autouse=True) def login(self, driver, base_url, user): driver.get(urljoin(base_url, "/login")) page = LoginPage(driver) page.login(user) def test_name_in_header(self, landing_page, user): assert landing_page.header == f"Welcome, {user.name}!" def test_sign_out_button(self, landing_page): assert landing_page.sign_out_button.is_displayed() def test_profile_link(self, landing_page, user): profile_href = urljoin(base_url, f"/profile?id={user.profile_id}") assert landing_page.profile_link.get_attribute("href") == profile_href Notice that the methods are only referencing ``self`` in the signature as a formality. No state is tied to the actual test class as it might be in the ``unittest.TestCase`` framework. Everything is managed by the pytest fixture system. Each method only has to request the fixtures that it actually needs without worrying about order. This is because the **act** fixture is an autouse fixture, and it made sure all the other fixtures executed before it. There's no more changes of state that need to take place, so the tests are free to make as many non-state-changing queries as they want without risking stepping on the toes of the other tests. The ``login`` fixture is defined inside the class as well, because not every one of the other tests in the module will be expecting a successful login, and the **act** may need to be handled a little differently for another test class. For example, if we wanted to write another test scenario around submitting bad credentials, we could handle it by adding something like this to the test file: .. note: It's assumed that the page object for this (i.e. ``LoginPage``) raises a custom exception, ``BadCredentialsException``, when it recognizes text signifying that on the login form after attempting to log in. .. code-block:: python class TestLandingPageBadCredentials: @pytest.fixture(scope="class") def faux_user(self, user): _user = deepcopy(user) _user.password = "badpass" return _user def test_raises_bad_credentials_exception(self, login_page, faux_user): with pytest.raises(BadCredentialsException): login_page.login(faux_user) .. _`request-context`: Fixtures can introspect the requesting test context ------------------------------------------------------------- Fixture functions can accept the :py:class:`request <_pytest.fixtures.FixtureRequest>` object to introspect the "requesting" test function, class or module context. Further extending the previous ``smtp_connection`` fixture example, let's read an optional server URL from the test module which uses our fixture: .. code-block:: python # content of conftest.py import smtplib import pytest @pytest.fixture(scope="module") def smtp_connection(request): server = getattr(request.module, "smtpserver", "smtp.gmail.com") smtp_connection = smtplib.SMTP(server, 587, timeout=5) yield smtp_connection print(f"finalizing {smtp_connection} ({server})") smtp_connection.close() We use the ``request.module`` attribute to optionally obtain an ``smtpserver`` attribute from the test module. If we just execute again, nothing much has changed: .. code-block:: pytest $ pytest -s -q --tb=no test_module.py FFfinalizing (smtp.gmail.com) ========================= short test summary info ========================== FAILED test_module.py::test_ehlo - assert 0 FAILED test_module.py::test_noop - assert 0 2 failed in 0.12s Let's quickly create another test module that actually sets the server URL in its module namespace: .. code-block:: python # content of test_anothersmtp.py smtpserver = "mail.python.org" # will be read by smtp fixture def test_showhelo(smtp_connection): assert 0, smtp_connection.helo() Running it: .. code-block:: pytest $ pytest -qq --tb=short test_anothersmtp.py F [100%] ================================= FAILURES ================================= ______________________________ test_showhelo _______________________________ test_anothersmtp.py:6: in test_showhelo assert 0, smtp_connection.helo() E AssertionError: (250, b'mail.python.org') E assert 0 ------------------------- Captured stdout teardown ------------------------- finalizing (mail.python.org) ========================= short test summary info ========================== FAILED test_anothersmtp.py::test_showhelo - AssertionError: (250, b'mail.... voila! The ``smtp_connection`` fixture function picked up our mail server name from the module namespace. .. _`using-markers`: Using markers to pass data to fixtures ------------------------------------------------------------- Using the :py:class:`request <_pytest.fixtures.FixtureRequest>` object, a fixture can also access markers which are applied to a test function. This can be useful to pass data into a fixture from a test: .. code-block:: python import pytest @pytest.fixture def fixt(request): marker = request.node.get_closest_marker("fixt_data") if marker is None: # Handle missing marker in some way... data = None else: data = marker.args[0] # Do something with the data return data @pytest.mark.fixt_data(42) def test_fixt(fixt): assert fixt == 42 .. _`fixture-factory`: Factories as fixtures ------------------------------------------------------------- The "factory as fixture" pattern can help in situations where the result of a fixture is needed multiple times in a single test. Instead of returning data directly, the fixture instead returns a function which generates the data. This function can then be called multiple times in the test. Factories can have parameters as needed: .. code-block:: python @pytest.fixture def make_customer_record(): def _make_customer_record(name): return {"name": name, "orders": []} return _make_customer_record def test_customer_records(make_customer_record): customer_1 = make_customer_record("Lisa") customer_2 = make_customer_record("Mike") customer_3 = make_customer_record("Meredith") If the data created by the factory requires managing, the fixture can take care of that: .. code-block:: python @pytest.fixture def make_customer_record(): created_records = [] def _make_customer_record(name): record = models.Customer(name=name, orders=[]) created_records.append(record) return record yield _make_customer_record for record in created_records: record.destroy() def test_customer_records(make_customer_record): customer_1 = make_customer_record("Lisa") customer_2 = make_customer_record("Mike") customer_3 = make_customer_record("Meredith") .. _`fixture-parametrize`: Parametrizing fixtures ----------------------------------------------------------------- Fixture functions can be parametrized in which case they will be called multiple times, each time executing the set of dependent tests, i.e. the tests that depend on this fixture. Test functions usually do not need to be aware of their re-running. Fixture parametrization helps to write exhaustive functional tests for components which themselves can be configured in multiple ways. Extending the previous example, we can flag the fixture to create two ``smtp_connection`` fixture instances which will cause all tests using the fixture to run twice. The fixture function gets access to each parameter through the special :py:class:`request ` object: .. code-block:: python # content of conftest.py import smtplib import pytest @pytest.fixture(scope="module", params=["smtp.gmail.com", "mail.python.org"]) def smtp_connection(request): smtp_connection = smtplib.SMTP(request.param, 587, timeout=5) yield smtp_connection print(f"finalizing {smtp_connection}") smtp_connection.close() The main change is the declaration of ``params`` with :py:func:`@pytest.fixture `, a list of values for each of which the fixture function will execute and can access a value via ``request.param``. No test function code needs to change. So let's just do another run: .. code-block:: pytest $ pytest -q test_module.py FFFF [100%] ================================= FAILURES ================================= ________________________ test_ehlo[smtp.gmail.com] _________________________ smtp_connection = def test_ehlo(smtp_connection): response, msg = smtp_connection.ehlo() assert response == 250 assert b"smtp.gmail.com" in msg > assert 0 # for demo purposes E assert 0 test_module.py:7: AssertionError ________________________ test_noop[smtp.gmail.com] _________________________ smtp_connection = def test_noop(smtp_connection): response, msg = smtp_connection.noop() assert response == 250 > assert 0 # for demo purposes E assert 0 test_module.py:13: AssertionError ________________________ test_ehlo[mail.python.org] ________________________ smtp_connection = def test_ehlo(smtp_connection): response, msg = smtp_connection.ehlo() assert response == 250 > assert b"smtp.gmail.com" in msg E AssertionError: assert b'smtp.gmail.com' in b'mail.python.org\nPIPELINING\nSIZE 51200000\nETRN\nSTARTTLS\nAUTH DIGEST-MD5 NTLM CRAM-MD5\nENHANCEDSTATUSCODES\n8BITMIME\nDSN\nSMTPUTF8\nCHUNKING' test_module.py:6: AssertionError -------------------------- Captured stdout setup --------------------------- finalizing ________________________ test_noop[mail.python.org] ________________________ smtp_connection = def test_noop(smtp_connection): response, msg = smtp_connection.noop() assert response == 250 > assert 0 # for demo purposes E assert 0 test_module.py:13: AssertionError ------------------------- Captured stdout teardown ------------------------- finalizing ========================= short test summary info ========================== FAILED test_module.py::test_ehlo[smtp.gmail.com] - assert 0 FAILED test_module.py::test_noop[smtp.gmail.com] - assert 0 FAILED test_module.py::test_ehlo[mail.python.org] - AssertionError: asser... FAILED test_module.py::test_noop[mail.python.org] - assert 0 4 failed in 0.12s We see that our two test functions each ran twice, against the different ``smtp_connection`` instances. Note also, that with the ``mail.python.org`` connection the second test fails in ``test_ehlo`` because a different server string is expected than what arrived. pytest will build a string that is the test ID for each fixture value in a parametrized fixture, e.g. ``test_ehlo[smtp.gmail.com]`` and ``test_ehlo[mail.python.org]`` in the above examples. These IDs can be used with ``-k`` to select specific cases to run, and they will also identify the specific case when one is failing. Running pytest with ``--collect-only`` will show the generated IDs. Numbers, strings, booleans and ``None`` will have their usual string representation used in the test ID. For other objects, pytest will make a string based on the argument name. It is possible to customise the string used in a test ID for a certain fixture value by using the ``ids`` keyword argument: .. code-block:: python # content of test_ids.py import pytest @pytest.fixture(params=[0, 1], ids=["spam", "ham"]) def a(request): return request.param def test_a(a): pass def idfn(fixture_value): if fixture_value == 0: return "eggs" else: return None @pytest.fixture(params=[0, 1], ids=idfn) def b(request): return request.param def test_b(b): pass The above shows how ``ids`` can be either a list of strings to use or a function which will be called with the fixture value and then has to return a string to use. In the latter case if the function returns ``None`` then pytest's auto-generated ID will be used. Running the above tests results in the following test IDs being used: .. code-block:: pytest $ pytest --collect-only =========================== test session starts ============================ platform linux -- Python 3.x.y, pytest-8.x.y, pluggy-1.x.y rootdir: /home/sweet/project collected 12 items ======================= 12 tests collected in 0.12s ======================== .. _`fixture-parametrize-marks`: Using marks with parametrized fixtures -------------------------------------- :func:`pytest.param` can be used to apply marks in values sets of parametrized fixtures in the same way that they can be used with :ref:`@pytest.mark.parametrize <@pytest.mark.parametrize>`. Example: .. code-block:: python # content of test_fixture_marks.py import pytest @pytest.fixture(params=[0, 1, pytest.param(2, marks=pytest.mark.skip)]) def data_set(request): return request.param def test_data(data_set): pass Running this test will *skip* the invocation of ``data_set`` with value ``2``: .. code-block:: pytest $ pytest test_fixture_marks.py -v =========================== test session starts ============================ platform linux -- Python 3.x.y, pytest-8.x.y, pluggy-1.x.y -- $PYTHON_PREFIX/bin/python cachedir: .pytest_cache rootdir: /home/sweet/project collecting ... collected 3 items test_fixture_marks.py::test_data[0] PASSED [ 33%] test_fixture_marks.py::test_data[1] PASSED [ 66%] test_fixture_marks.py::test_data[2] SKIPPED (unconditional skip) [100%] ======================= 2 passed, 1 skipped in 0.12s ======================= .. _`interdependent fixtures`: Modularity: using fixtures from a fixture function ---------------------------------------------------------- In addition to using fixtures in test functions, fixture functions can use other fixtures themselves. This contributes to a modular design of your fixtures and allows re-use of framework-specific fixtures across many projects. As a simple example, we can extend the previous example and instantiate an object ``app`` where we stick the already defined ``smtp_connection`` resource into it: .. code-block:: python # content of test_appsetup.py import pytest class App: def __init__(self, smtp_connection): self.smtp_connection = smtp_connection @pytest.fixture(scope="module") def app(smtp_connection): return App(smtp_connection) def test_smtp_connection_exists(app): assert app.smtp_connection Here we declare an ``app`` fixture which receives the previously defined ``smtp_connection`` fixture and instantiates an ``App`` object with it. Let's run it: .. code-block:: pytest $ pytest -v test_appsetup.py =========================== test session starts ============================ platform linux -- Python 3.x.y, pytest-8.x.y, pluggy-1.x.y -- $PYTHON_PREFIX/bin/python cachedir: .pytest_cache rootdir: /home/sweet/project collecting ... collected 2 items test_appsetup.py::test_smtp_connection_exists[smtp.gmail.com] PASSED [ 50%] test_appsetup.py::test_smtp_connection_exists[mail.python.org] PASSED [100%] ============================ 2 passed in 0.12s ============================= Due to the parametrization of ``smtp_connection``, the test will run twice with two different ``App`` instances and respective smtp servers. There is no need for the ``app`` fixture to be aware of the ``smtp_connection`` parametrization because pytest will fully analyse the fixture dependency graph. Note that the ``app`` fixture has a scope of ``module`` and uses a module-scoped ``smtp_connection`` fixture. The example would still work if ``smtp_connection`` was cached on a ``session`` scope: it is fine for fixtures to use "broader" scoped fixtures but not the other way round: A session-scoped fixture could not use a module-scoped one in a meaningful way. .. _`automatic per-resource grouping`: Automatic grouping of tests by fixture instances ---------------------------------------------------------- .. regendoc: wipe pytest minimizes the number of active fixtures during test runs. If you have a parametrized fixture, then all the tests using it will first execute with one instance and then finalizers are called before the next fixture instance is created. Among other things, this eases testing of applications which create and use global state. The following example uses two parametrized fixtures, one of which is scoped on a per-module basis, and all the functions perform ``print`` calls to show the setup/teardown flow: .. code-block:: python # content of test_module.py import pytest @pytest.fixture(scope="module", params=["mod1", "mod2"]) def modarg(request): param = request.param print(" SETUP modarg", param) yield param print(" TEARDOWN modarg", param) @pytest.fixture(scope="function", params=[1, 2]) def otherarg(request): param = request.param print(" SETUP otherarg", param) yield param print(" TEARDOWN otherarg", param) def test_0(otherarg): print(" RUN test0 with otherarg", otherarg) def test_1(modarg): print(" RUN test1 with modarg", modarg) def test_2(otherarg, modarg): print(f" RUN test2 with otherarg {otherarg} and modarg {modarg}") Let's run the tests in verbose mode and with looking at the print-output: .. code-block:: pytest $ pytest -v -s test_module.py =========================== test session starts ============================ platform linux -- Python 3.x.y, pytest-8.x.y, pluggy-1.x.y -- $PYTHON_PREFIX/bin/python cachedir: .pytest_cache rootdir: /home/sweet/project collecting ... collected 8 items test_module.py::test_0[1] SETUP otherarg 1 RUN test0 with otherarg 1 PASSED TEARDOWN otherarg 1 test_module.py::test_0[2] SETUP otherarg 2 RUN test0 with otherarg 2 PASSED TEARDOWN otherarg 2 test_module.py::test_1[mod1] SETUP modarg mod1 RUN test1 with modarg mod1 PASSED test_module.py::test_2[mod1-1] SETUP otherarg 1 RUN test2 with otherarg 1 and modarg mod1 PASSED TEARDOWN otherarg 1 test_module.py::test_2[mod1-2] SETUP otherarg 2 RUN test2 with otherarg 2 and modarg mod1 PASSED TEARDOWN otherarg 2 test_module.py::test_1[mod2] TEARDOWN modarg mod1 SETUP modarg mod2 RUN test1 with modarg mod2 PASSED test_module.py::test_2[mod2-1] SETUP otherarg 1 RUN test2 with otherarg 1 and modarg mod2 PASSED TEARDOWN otherarg 1 test_module.py::test_2[mod2-2] SETUP otherarg 2 RUN test2 with otherarg 2 and modarg mod2 PASSED TEARDOWN otherarg 2 TEARDOWN modarg mod2 ============================ 8 passed in 0.12s ============================= You can see that the parametrized module-scoped ``modarg`` resource caused an ordering of test execution that lead to the fewest possible "active" resources. The finalizer for the ``mod1`` parametrized resource was executed before the ``mod2`` resource was setup. In particular notice that test_0 is completely independent and finishes first. Then test_1 is executed with ``mod1``, then test_2 with ``mod1``, then test_1 with ``mod2`` and finally test_2 with ``mod2``. The ``otherarg`` parametrized resource (having function scope) was set up before and teared down after every test that used it. .. _`usefixtures`: Use fixtures in classes and modules with ``usefixtures`` -------------------------------------------------------- .. regendoc:wipe Sometimes test functions do not directly need access to a fixture object. For example, tests may require to operate with an empty directory as the current working directory but otherwise do not care for the concrete directory. Here is how you can use the standard :mod:`tempfile` and pytest fixtures to achieve it. We separate the creation of the fixture into a :file:`conftest.py` file: .. code-block:: python # content of conftest.py import os import tempfile import pytest @pytest.fixture def cleandir(): with tempfile.TemporaryDirectory() as newpath: old_cwd = os.getcwd() os.chdir(newpath) yield os.chdir(old_cwd) and declare its use in a test module via a ``usefixtures`` marker: .. code-block:: python # content of test_setenv.py import os import pytest @pytest.mark.usefixtures("cleandir") class TestDirectoryInit: def test_cwd_starts_empty(self): assert os.listdir(os.getcwd()) == [] with open("myfile", "w", encoding="utf-8") as f: f.write("hello") def test_cwd_again_starts_empty(self): assert os.listdir(os.getcwd()) == [] Due to the ``usefixtures`` marker, the ``cleandir`` fixture will be required for the execution of each test method, just as if you specified a "cleandir" function argument to each of them. Let's run it to verify our fixture is activated and the tests pass: .. code-block:: pytest $ pytest -q .. [100%] 2 passed in 0.12s You can specify multiple fixtures like this: .. code-block:: python @pytest.mark.usefixtures("cleandir", "anotherfixture") def test(): ... and you may specify fixture usage at the test module level using :globalvar:`pytestmark`: .. code-block:: python pytestmark = pytest.mark.usefixtures("cleandir") It is also possible to put fixtures required by all tests in your project into an ini-file: .. code-block:: ini # content of pytest.ini [pytest] usefixtures = cleandir .. warning:: Note this mark has no effect in **fixture functions**. For example, this **will not work as expected**: .. code-block:: python @pytest.mark.usefixtures("my_other_fixture") @pytest.fixture def my_fixture_that_sadly_wont_use_my_other_fixture(): ... This generates a deprecation warning, and will become an error in Pytest 8. .. _`override fixtures`: Overriding fixtures on various levels ------------------------------------- In relatively large test suite, you most likely need to ``override`` a ``global`` or ``root`` fixture with a ``locally`` defined one, keeping the test code readable and maintainable. Override a fixture on a folder (conftest) level ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Given the tests file structure is: :: tests/ conftest.py # content of tests/conftest.py import pytest @pytest.fixture def username(): return 'username' test_something.py # content of tests/test_something.py def test_username(username): assert username == 'username' subfolder/ conftest.py # content of tests/subfolder/conftest.py import pytest @pytest.fixture def username(username): return 'overridden-' + username test_something_else.py # content of tests/subfolder/test_something_else.py def test_username(username): assert username == 'overridden-username' As you can see, a fixture with the same name can be overridden for certain test folder level. Note that the ``base`` or ``super`` fixture can be accessed from the ``overriding`` fixture easily - used in the example above. Override a fixture on a test module level ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Given the tests file structure is: :: tests/ conftest.py # content of tests/conftest.py import pytest @pytest.fixture def username(): return 'username' test_something.py # content of tests/test_something.py import pytest @pytest.fixture def username(username): return 'overridden-' + username def test_username(username): assert username == 'overridden-username' test_something_else.py # content of tests/test_something_else.py import pytest @pytest.fixture def username(username): return 'overridden-else-' + username def test_username(username): assert username == 'overridden-else-username' In the example above, a fixture with the same name can be overridden for certain test module. Override a fixture with direct test parametrization ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Given the tests file structure is: :: tests/ conftest.py # content of tests/conftest.py import pytest @pytest.fixture def username(): return 'username' @pytest.fixture def other_username(username): return 'other-' + username test_something.py # content of tests/test_something.py import pytest @pytest.mark.parametrize('username', ['directly-overridden-username']) def test_username(username): assert username == 'directly-overridden-username' @pytest.mark.parametrize('username', ['directly-overridden-username-other']) def test_username_other(other_username): assert other_username == 'other-directly-overridden-username-other' In the example above, a fixture value is overridden by the test parameter value. Note that the value of the fixture can be overridden this way even if the test doesn't use it directly (doesn't mention it in the function prototype). Override a parametrized fixture with non-parametrized one and vice versa ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Given the tests file structure is: :: tests/ conftest.py # content of tests/conftest.py import pytest @pytest.fixture(params=['one', 'two', 'three']) def parametrized_username(request): return request.param @pytest.fixture def non_parametrized_username(request): return 'username' test_something.py # content of tests/test_something.py import pytest @pytest.fixture def parametrized_username(): return 'overridden-username' @pytest.fixture(params=['one', 'two', 'three']) def non_parametrized_username(request): return request.param def test_username(parametrized_username): assert parametrized_username == 'overridden-username' def test_parametrized_username(non_parametrized_username): assert non_parametrized_username in ['one', 'two', 'three'] test_something_else.py # content of tests/test_something_else.py def test_username(parametrized_username): assert parametrized_username in ['one', 'two', 'three'] def test_username(non_parametrized_username): assert non_parametrized_username == 'username' In the example above, a parametrized fixture is overridden with a non-parametrized version, and a non-parametrized fixture is overridden with a parametrized version for certain test module. The same applies for the test folder level obviously. Using fixtures from other projects ---------------------------------- Usually projects that provide pytest support will use :ref:`entry points `, so just installing those projects into an environment will make those fixtures available for use. In case you want to use fixtures from a project that does not use entry points, you can define :globalvar:`pytest_plugins` in your top ``conftest.py`` file to register that module as a plugin. Suppose you have some fixtures in ``mylibrary.fixtures`` and you want to reuse them into your ``app/tests`` directory. All you need to do is to define :globalvar:`pytest_plugins` in ``app/tests/conftest.py`` pointing to that module. .. code-block:: python pytest_plugins = "mylibrary.fixtures" This effectively registers ``mylibrary.fixtures`` as a plugin, making all its fixtures and hooks available to tests in ``app/tests``. .. note:: Sometimes users will *import* fixtures from other projects for use, however this is not recommended: importing fixtures into a module will register them in pytest as *defined* in that module. This has minor consequences, such as appearing multiple times in ``pytest --help``, but it is not **recommended** because this behavior might change/stop working in future versions.