1.. _fixture: 2.. _fixtures: 3.. _`fixture functions`: 4 5pytest fixtures: explicit, modular, scalable 6======================================================== 7 8.. currentmodule:: _pytest.python 9 10 11 12.. _`xUnit`: http://en.wikipedia.org/wiki/XUnit 13.. _`purpose of test fixtures`: http://en.wikipedia.org/wiki/Test_fixture#Software 14.. _`Dependency injection`: http://en.wikipedia.org/wiki/Dependency_injection 15 16The `purpose of test fixtures`_ is to provide a fixed baseline 17upon which tests can reliably and repeatedly execute. pytest fixtures 18offer dramatic improvements over the classic xUnit style of setup/teardown 19functions: 20 21* fixtures have explicit names and are activated by declaring their use 22 from test functions, modules, classes or whole projects. 23 24* fixtures are implemented in a modular manner, as each fixture name 25 triggers a *fixture function* which can itself use other fixtures. 26 27* fixture management scales from simple unit to complex 28 functional testing, allowing to parametrize fixtures and tests according 29 to configuration and component options, or to re-use fixtures 30 across function, class, module or whole test session scopes. 31 32In addition, pytest continues to support :ref:`xunitsetup`. You can mix 33both styles, moving incrementally from classic to new style, as you 34prefer. You can also start out from existing :ref:`unittest.TestCase 35style <unittest.TestCase>` or :ref:`nose based <nosestyle>` projects. 36 37 38.. _`funcargs`: 39.. _`funcarg mechanism`: 40.. _`fixture function`: 41.. _`@pytest.fixture`: 42.. _`pytest.fixture`: 43 44Fixtures as Function arguments 45----------------------------------------- 46 47Test functions can receive fixture objects by naming them as an input 48argument. For each argument name, a fixture function with that name provides 49the fixture object. Fixture functions are registered by marking them with 50:py:func:`@pytest.fixture <_pytest.python.fixture>`. Let's look at a simple 51self-contained test module containing a fixture and a test function 52using it:: 53 54 # content of ./test_smtpsimple.py 55 import pytest 56 57 @pytest.fixture 58 def smtp_connection(): 59 import smtplib 60 return smtplib.SMTP("smtp.gmail.com", 587, timeout=5) 61 62 def test_ehlo(smtp_connection): 63 response, msg = smtp_connection.ehlo() 64 assert response == 250 65 assert 0 # for demo purposes 66 67Here, the ``test_ehlo`` needs the ``smtp_connection`` fixture value. pytest 68will discover and call the :py:func:`@pytest.fixture <_pytest.python.fixture>` 69marked ``smtp_connection`` fixture function. Running the test looks like this: 70 71.. code-block:: pytest 72 73 $ pytest test_smtpsimple.py 74 =========================== test session starts ============================ 75 platform linux -- Python 3.x.y, pytest-4.x.y, py-1.x.y, pluggy-0.x.y 76 cachedir: $PYTHON_PREFIX/.pytest_cache 77 rootdir: $REGENDOC_TMPDIR 78 collected 1 item 79 80 test_smtpsimple.py F [100%] 81 82 ================================= FAILURES ================================= 83 ________________________________ test_ehlo _________________________________ 84 85 smtp_connection = <smtplib.SMTP object at 0xdeadbeef> 86 87 def test_ehlo(smtp_connection): 88 response, msg = smtp_connection.ehlo() 89 assert response == 250 90 > assert 0 # for demo purposes 91 E assert 0 92 93 test_smtpsimple.py:11: AssertionError 94 ========================= 1 failed in 0.12 seconds ========================= 95 96In the failure traceback we see that the test function was called with a 97``smtp_connection`` argument, the ``smtplib.SMTP()`` instance created by the fixture 98function. The test function fails on our deliberate ``assert 0``. Here is 99the exact protocol used by ``pytest`` to call the test function this way: 100 1011. pytest :ref:`finds <test discovery>` the ``test_ehlo`` because 102 of the ``test_`` prefix. The test function needs a function argument 103 named ``smtp_connection``. A matching fixture function is discovered by 104 looking for a fixture-marked function named ``smtp_connection``. 105 1062. ``smtp_connection()`` is called to create an instance. 107 1083. ``test_ehlo(<smtp_connection instance>)`` is called and fails in the last 109 line of the test function. 110 111Note that if you misspell a function argument or want 112to use one that isn't available, you'll see an error 113with a list of available function arguments. 114 115.. note:: 116 117 You can always issue: 118 119 .. code-block:: bash 120 121 pytest --fixtures test_simplefactory.py 122 123 to see available fixtures (fixtures with leading ``_`` are only shown if you add the ``-v`` option). 124 125Fixtures: a prime example of dependency injection 126--------------------------------------------------- 127 128Fixtures allow test functions to easily receive and work 129against specific pre-initialized application objects without having 130to care about import/setup/cleanup details. 131It's a prime example of `dependency injection`_ where fixture 132functions take the role of the *injector* and test functions are the 133*consumers* of fixture objects. 134 135.. _`conftest.py`: 136.. _`conftest`: 137 138``conftest.py``: sharing fixture functions 139------------------------------------------ 140 141If during implementing your tests you realize that you 142want to use a fixture function from multiple test files you can move it 143to a ``conftest.py`` file. 144You don't need to import the fixture you want to use in a test, it 145automatically gets discovered by pytest. The discovery of 146fixture functions starts at test classes, then test modules, then 147``conftest.py`` files and finally builtin and third party plugins. 148 149You can also use the ``conftest.py`` file to implement 150:ref:`local per-directory plugins <conftest.py plugins>`. 151 152Sharing test data 153----------------- 154 155If you want to make test data from files available to your tests, a good way 156to do this is by loading these data in a fixture for use by your tests. 157This makes use of the automatic caching mechanisms of pytest. 158 159Another good approach is by adding the data files in the ``tests`` folder. 160There are also community plugins available to help managing this aspect of 161testing, e.g. `pytest-datadir <https://pypi.org/project/pytest-datadir/>`__ 162and `pytest-datafiles <https://pypi.org/project/pytest-datafiles/>`__. 163 164.. _smtpshared: 165 166Scope: sharing a fixture instance across tests in a class, module or session 167---------------------------------------------------------------------------- 168 169.. regendoc:wipe 170 171Fixtures requiring network access depend on connectivity and are 172usually time-expensive to create. Extending the previous example, we 173can add a ``scope="module"`` parameter to the 174:py:func:`@pytest.fixture <_pytest.python.fixture>` invocation 175to cause the decorated ``smtp_connection`` fixture function to only be invoked 176once per test *module* (the default is to invoke once per test *function*). 177Multiple test functions in a test module will thus 178each receive the same ``smtp_connection`` fixture instance, thus saving time. 179Possible values for ``scope`` are: ``function``, ``class``, ``module``, ``package`` or ``session``. 180 181The next example puts the fixture function into a separate ``conftest.py`` file 182so that tests from multiple test modules in the directory can 183access the fixture function:: 184 185 # content of conftest.py 186 import pytest 187 import smtplib 188 189 @pytest.fixture(scope="module") 190 def smtp_connection(): 191 return smtplib.SMTP("smtp.gmail.com", 587, timeout=5) 192 193The name of the fixture again is ``smtp_connection`` and you can access its 194result by listing the name ``smtp_connection`` as an input parameter in any 195test or fixture function (in or below the directory where ``conftest.py`` is 196located):: 197 198 # content of test_module.py 199 200 def test_ehlo(smtp_connection): 201 response, msg = smtp_connection.ehlo() 202 assert response == 250 203 assert b"smtp.gmail.com" in msg 204 assert 0 # for demo purposes 205 206 def test_noop(smtp_connection): 207 response, msg = smtp_connection.noop() 208 assert response == 250 209 assert 0 # for demo purposes 210 211We deliberately insert failing ``assert 0`` statements in order to 212inspect what is going on and can now run the tests: 213 214.. code-block:: pytest 215 216 $ pytest test_module.py 217 =========================== test session starts ============================ 218 platform linux -- Python 3.x.y, pytest-4.x.y, py-1.x.y, pluggy-0.x.y 219 cachedir: $PYTHON_PREFIX/.pytest_cache 220 rootdir: $REGENDOC_TMPDIR 221 collected 2 items 222 223 test_module.py FF [100%] 224 225 ================================= FAILURES ================================= 226 ________________________________ test_ehlo _________________________________ 227 228 smtp_connection = <smtplib.SMTP object at 0xdeadbeef> 229 230 def test_ehlo(smtp_connection): 231 response, msg = smtp_connection.ehlo() 232 assert response == 250 233 assert b"smtp.gmail.com" in msg 234 > assert 0 # for demo purposes 235 E assert 0 236 237 test_module.py:6: AssertionError 238 ________________________________ test_noop _________________________________ 239 240 smtp_connection = <smtplib.SMTP object at 0xdeadbeef> 241 242 def test_noop(smtp_connection): 243 response, msg = smtp_connection.noop() 244 assert response == 250 245 > assert 0 # for demo purposes 246 E assert 0 247 248 test_module.py:11: AssertionError 249 ========================= 2 failed in 0.12 seconds ========================= 250 251You see the two ``assert 0`` failing and more importantly you can also see 252that the same (module-scoped) ``smtp_connection`` object was passed into the 253two test functions because pytest shows the incoming argument values in the 254traceback. As a result, the two test functions using ``smtp_connection`` run 255as quick as a single one because they reuse the same instance. 256 257If you decide that you rather want to have a session-scoped ``smtp_connection`` 258instance, you can simply declare it: 259 260.. code-block:: python 261 262 @pytest.fixture(scope="session") 263 def smtp_connection(): 264 # the returned fixture value will be shared for 265 # all tests needing it 266 ... 267 268Finally, the ``class`` scope will invoke the fixture once per test *class*. 269 270.. note:: 271 272 Pytest will only cache one instance of a fixture at a time. 273 This means that when using a parametrized fixture, pytest may invoke a fixture more than once in the given scope. 274 275 276``package`` scope (experimental) 277^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 278 279 280 281In pytest 3.7 the ``package`` scope has been introduced. Package-scoped fixtures 282are finalized when the last test of a *package* finishes. 283 284.. warning:: 285 This functionality is considered **experimental** and may be removed in future 286 versions if hidden corner-cases or serious problems with this functionality 287 are discovered after it gets more usage in the wild. 288 289 Use this new feature sparingly and please make sure to report any issues you find. 290 291 292Higher-scoped fixtures are instantiated first 293--------------------------------------------- 294 295 296 297Within a function request for features, fixture of higher-scopes (such as ``session``) are instantiated first than 298lower-scoped fixtures (such as ``function`` or ``class``). The relative order of fixtures of same scope follows 299the declared order in the test function and honours dependencies between fixtures. 300 301Consider the code below: 302 303.. code-block:: python 304 305 @pytest.fixture(scope="session") 306 def s1(): 307 pass 308 309 310 @pytest.fixture(scope="module") 311 def m1(): 312 pass 313 314 315 @pytest.fixture 316 def f1(tmpdir): 317 pass 318 319 320 @pytest.fixture 321 def f2(): 322 pass 323 324 325 def test_foo(f1, m1, f2, s1): 326 ... 327 328 329The fixtures requested by ``test_foo`` will be instantiated in the following order: 330 3311. ``s1``: is the highest-scoped fixture (``session``). 3322. ``m1``: is the second highest-scoped fixture (``module``). 3333. ``tmpdir``: is a ``function``-scoped fixture, required by ``f1``: it needs to be instantiated at this point 334 because it is a dependency of ``f1``. 3354. ``f1``: is the first ``function``-scoped fixture in ``test_foo`` parameter list. 3365. ``f2``: is the last ``function``-scoped fixture in ``test_foo`` parameter list. 337 338 339.. _`finalization`: 340 341Fixture finalization / executing teardown code 342------------------------------------------------------------- 343 344pytest supports execution of fixture specific finalization code 345when the fixture goes out of scope. By using a ``yield`` statement instead of ``return``, all 346the code after the *yield* statement serves as the teardown code: 347 348.. code-block:: python 349 350 # content of conftest.py 351 352 import smtplib 353 import pytest 354 355 356 @pytest.fixture(scope="module") 357 def smtp_connection(): 358 smtp_connection = smtplib.SMTP("smtp.gmail.com", 587, timeout=5) 359 yield smtp_connection # provide the fixture value 360 print("teardown smtp") 361 smtp_connection.close() 362 363The ``print`` and ``smtp.close()`` statements will execute when the last test in 364the module has finished execution, regardless of the exception status of the 365tests. 366 367Let's execute it: 368 369.. code-block:: pytest 370 371 $ pytest -s -q --tb=no 372 FFteardown smtp 373 374 2 failed in 0.12 seconds 375 376We see that the ``smtp_connection`` instance is finalized after the two 377tests finished execution. Note that if we decorated our fixture 378function with ``scope='function'`` then fixture setup and cleanup would 379occur around each single test. In either case the test 380module itself does not need to change or know about these details 381of fixture setup. 382 383Note that we can also seamlessly use the ``yield`` syntax with ``with`` statements: 384 385.. code-block:: python 386 387 # content of test_yield2.py 388 389 import smtplib 390 import pytest 391 392 393 @pytest.fixture(scope="module") 394 def smtp_connection(): 395 with smtplib.SMTP("smtp.gmail.com", 587, timeout=5) as smtp_connection: 396 yield smtp_connection # provide the fixture value 397 398 399The ``smtp_connection`` connection will be closed after the test finished 400execution because the ``smtp_connection`` object automatically closes when 401the ``with`` statement ends. 402 403Note that if an exception happens during the *setup* code (before the ``yield`` keyword), the 404*teardown* code (after the ``yield``) will not be called. 405 406An alternative option for executing *teardown* code is to 407make use of the ``addfinalizer`` method of the `request-context`_ object to register 408finalization functions. 409 410Here's the ``smtp_connection`` fixture changed to use ``addfinalizer`` for cleanup: 411 412.. code-block:: python 413 414 # content of conftest.py 415 import smtplib 416 import pytest 417 418 419 @pytest.fixture(scope="module") 420 def smtp_connection(request): 421 smtp_connection = smtplib.SMTP("smtp.gmail.com", 587, timeout=5) 422 423 def fin(): 424 print("teardown smtp_connection") 425 smtp_connection.close() 426 427 request.addfinalizer(fin) 428 return smtp_connection # provide the fixture value 429 430 431Both ``yield`` and ``addfinalizer`` methods work similarly by calling their code after the test 432ends, but ``addfinalizer`` has two key differences over ``yield``: 433 4341. It is possible to register multiple finalizer functions. 435 4362. Finalizers will always be called regardless if the fixture *setup* code raises an exception. 437 This is handy to properly close all resources created by a fixture even if one of them 438 fails to be created/acquired:: 439 440 @pytest.fixture 441 def equipments(request): 442 r = [] 443 for port in ('C1', 'C3', 'C28'): 444 equip = connect(port) 445 request.addfinalizer(equip.disconnect) 446 r.append(equip) 447 return r 448 449 In the example above, if ``"C28"`` fails with an exception, ``"C1"`` and ``"C3"`` will still 450 be properly closed. Of course, if an exception happens before the finalize function is 451 registered then it will not be executed. 452 453 454.. _`request-context`: 455 456Fixtures can introspect the requesting test context 457------------------------------------------------------------- 458 459Fixture functions can accept the :py:class:`request <FixtureRequest>` object 460to introspect the "requesting" test function, class or module context. 461Further extending the previous ``smtp_connection`` fixture example, let's 462read an optional server URL from the test module which uses our fixture:: 463 464 # content of conftest.py 465 import pytest 466 import smtplib 467 468 @pytest.fixture(scope="module") 469 def smtp_connection(request): 470 server = getattr(request.module, "smtpserver", "smtp.gmail.com") 471 smtp_connection = smtplib.SMTP(server, 587, timeout=5) 472 yield smtp_connection 473 print("finalizing %s (%s)" % (smtp_connection, server)) 474 smtp_connection.close() 475 476We use the ``request.module`` attribute to optionally obtain an 477``smtpserver`` attribute from the test module. If we just execute 478again, nothing much has changed: 479 480.. code-block:: pytest 481 482 $ pytest -s -q --tb=no 483 FFfinalizing <smtplib.SMTP object at 0xdeadbeef> (smtp.gmail.com) 484 485 2 failed in 0.12 seconds 486 487Let's quickly create another test module that actually sets the 488server URL in its module namespace:: 489 490 # content of test_anothersmtp.py 491 492 smtpserver = "mail.python.org" # will be read by smtp fixture 493 494 def test_showhelo(smtp_connection): 495 assert 0, smtp_connection.helo() 496 497Running it: 498 499.. code-block:: pytest 500 501 $ pytest -qq --tb=short test_anothersmtp.py 502 F [100%] 503 ================================= FAILURES ================================= 504 ______________________________ test_showhelo _______________________________ 505 test_anothersmtp.py:5: in test_showhelo 506 assert 0, smtp_connection.helo() 507 E AssertionError: (250, b'mail.python.org') 508 E assert 0 509 ------------------------- Captured stdout teardown ------------------------- 510 finalizing <smtplib.SMTP object at 0xdeadbeef> (mail.python.org) 511 512voila! The ``smtp_connection`` fixture function picked up our mail server name 513from the module namespace. 514 515.. _`fixture-factory`: 516 517Factories as fixtures 518------------------------------------------------------------- 519 520The "factory as fixture" pattern can help in situations where the result 521of a fixture is needed multiple times in a single test. Instead of returning 522data directly, the fixture instead returns a function which generates the data. 523This function can then be called multiple times in the test. 524 525Factories can have have parameters as needed:: 526 527 @pytest.fixture 528 def make_customer_record(): 529 530 def _make_customer_record(name): 531 return { 532 "name": name, 533 "orders": [] 534 } 535 536 return _make_customer_record 537 538 539 def test_customer_records(make_customer_record): 540 customer_1 = make_customer_record("Lisa") 541 customer_2 = make_customer_record("Mike") 542 customer_3 = make_customer_record("Meredith") 543 544If the data created by the factory requires managing, the fixture can take care of that:: 545 546 @pytest.fixture 547 def make_customer_record(): 548 549 created_records = [] 550 551 def _make_customer_record(name): 552 record = models.Customer(name=name, orders=[]) 553 created_records.append(record) 554 return record 555 556 yield _make_customer_record 557 558 for record in created_records: 559 record.destroy() 560 561 562 def test_customer_records(make_customer_record): 563 customer_1 = make_customer_record("Lisa") 564 customer_2 = make_customer_record("Mike") 565 customer_3 = make_customer_record("Meredith") 566 567 568.. _`fixture-parametrize`: 569 570Parametrizing fixtures 571----------------------------------------------------------------- 572 573Fixture functions can be parametrized in which case they will be called 574multiple times, each time executing the set of dependent tests, i. e. the 575tests that depend on this fixture. Test functions usually do not need 576to be aware of their re-running. Fixture parametrization helps to 577write exhaustive functional tests for components which themselves can be 578configured in multiple ways. 579 580Extending the previous example, we can flag the fixture to create two 581``smtp_connection`` fixture instances which will cause all tests using the fixture 582to run twice. The fixture function gets access to each parameter 583through the special :py:class:`request <FixtureRequest>` object:: 584 585 # content of conftest.py 586 import pytest 587 import smtplib 588 589 @pytest.fixture(scope="module", 590 params=["smtp.gmail.com", "mail.python.org"]) 591 def smtp_connection(request): 592 smtp_connection = smtplib.SMTP(request.param, 587, timeout=5) 593 yield smtp_connection 594 print("finalizing %s" % smtp_connection) 595 smtp_connection.close() 596 597The main change is the declaration of ``params`` with 598:py:func:`@pytest.fixture <_pytest.python.fixture>`, a list of values 599for each of which the fixture function will execute and can access 600a value via ``request.param``. No test function code needs to change. 601So let's just do another run: 602 603.. code-block:: pytest 604 605 $ pytest -q test_module.py 606 FFFF [100%] 607 ================================= FAILURES ================================= 608 ________________________ test_ehlo[smtp.gmail.com] _________________________ 609 610 smtp_connection = <smtplib.SMTP object at 0xdeadbeef> 611 612 def test_ehlo(smtp_connection): 613 response, msg = smtp_connection.ehlo() 614 assert response == 250 615 assert b"smtp.gmail.com" in msg 616 > assert 0 # for demo purposes 617 E assert 0 618 619 test_module.py:6: AssertionError 620 ________________________ test_noop[smtp.gmail.com] _________________________ 621 622 smtp_connection = <smtplib.SMTP object at 0xdeadbeef> 623 624 def test_noop(smtp_connection): 625 response, msg = smtp_connection.noop() 626 assert response == 250 627 > assert 0 # for demo purposes 628 E assert 0 629 630 test_module.py:11: AssertionError 631 ________________________ test_ehlo[mail.python.org] ________________________ 632 633 smtp_connection = <smtplib.SMTP object at 0xdeadbeef> 634 635 def test_ehlo(smtp_connection): 636 response, msg = smtp_connection.ehlo() 637 assert response == 250 638 > assert b"smtp.gmail.com" in msg 639 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' 640 641 test_module.py:5: AssertionError 642 -------------------------- Captured stdout setup --------------------------- 643 finalizing <smtplib.SMTP object at 0xdeadbeef> 644 ________________________ test_noop[mail.python.org] ________________________ 645 646 smtp_connection = <smtplib.SMTP object at 0xdeadbeef> 647 648 def test_noop(smtp_connection): 649 response, msg = smtp_connection.noop() 650 assert response == 250 651 > assert 0 # for demo purposes 652 E assert 0 653 654 test_module.py:11: AssertionError 655 ------------------------- Captured stdout teardown ------------------------- 656 finalizing <smtplib.SMTP object at 0xdeadbeef> 657 4 failed in 0.12 seconds 658 659We see that our two test functions each ran twice, against the different 660``smtp_connection`` instances. Note also, that with the ``mail.python.org`` 661connection the second test fails in ``test_ehlo`` because a 662different server string is expected than what arrived. 663 664pytest will build a string that is the test ID for each fixture value 665in a parametrized fixture, e.g. ``test_ehlo[smtp.gmail.com]`` and 666``test_ehlo[mail.python.org]`` in the above examples. These IDs can 667be used with ``-k`` to select specific cases to run, and they will 668also identify the specific case when one is failing. Running pytest 669with ``--collect-only`` will show the generated IDs. 670 671Numbers, strings, booleans and None will have their usual string 672representation used in the test ID. For other objects, pytest will 673make a string based on the argument name. It is possible to customise 674the string used in a test ID for a certain fixture value by using the 675``ids`` keyword argument:: 676 677 # content of test_ids.py 678 import pytest 679 680 @pytest.fixture(params=[0, 1], ids=["spam", "ham"]) 681 def a(request): 682 return request.param 683 684 def test_a(a): 685 pass 686 687 def idfn(fixture_value): 688 if fixture_value == 0: 689 return "eggs" 690 else: 691 return None 692 693 @pytest.fixture(params=[0, 1], ids=idfn) 694 def b(request): 695 return request.param 696 697 def test_b(b): 698 pass 699 700The above shows how ``ids`` can be either a list of strings to use or 701a function which will be called with the fixture value and then 702has to return a string to use. In the latter case if the function 703return ``None`` then pytest's auto-generated ID will be used. 704 705Running the above tests results in the following test IDs being used: 706 707.. code-block:: pytest 708 709 $ pytest --collect-only 710 =========================== test session starts ============================ 711 platform linux -- Python 3.x.y, pytest-4.x.y, py-1.x.y, pluggy-0.x.y 712 cachedir: $PYTHON_PREFIX/.pytest_cache 713 rootdir: $REGENDOC_TMPDIR 714 collected 10 items 715 <Module test_anothersmtp.py> 716 <Function test_showhelo[smtp.gmail.com]> 717 <Function test_showhelo[mail.python.org]> 718 <Module test_ids.py> 719 <Function test_a[spam]> 720 <Function test_a[ham]> 721 <Function test_b[eggs]> 722 <Function test_b[1]> 723 <Module test_module.py> 724 <Function test_ehlo[smtp.gmail.com]> 725 <Function test_noop[smtp.gmail.com]> 726 <Function test_ehlo[mail.python.org]> 727 <Function test_noop[mail.python.org]> 728 729 ======================= no tests ran in 0.12 seconds ======================= 730 731.. _`fixture-parametrize-marks`: 732 733Using marks with parametrized fixtures 734-------------------------------------- 735 736:func:`pytest.param` can be used to apply marks in values sets of parametrized fixtures in the same way 737that they can be used with :ref:`@pytest.mark.parametrize <@pytest.mark.parametrize>`. 738 739Example:: 740 741 # content of test_fixture_marks.py 742 import pytest 743 @pytest.fixture(params=[0, 1, pytest.param(2, marks=pytest.mark.skip)]) 744 def data_set(request): 745 return request.param 746 747 def test_data(data_set): 748 pass 749 750Running this test will *skip* the invocation of ``data_set`` with value ``2``: 751 752.. code-block:: pytest 753 754 $ pytest test_fixture_marks.py -v 755 =========================== test session starts ============================ 756 platform linux -- Python 3.x.y, pytest-4.x.y, py-1.x.y, pluggy-0.x.y -- $PYTHON_PREFIX/bin/python 757 cachedir: $PYTHON_PREFIX/.pytest_cache 758 rootdir: $REGENDOC_TMPDIR 759 collecting ... collected 3 items 760 761 test_fixture_marks.py::test_data[0] PASSED [ 33%] 762 test_fixture_marks.py::test_data[1] PASSED [ 66%] 763 test_fixture_marks.py::test_data[2] SKIPPED [100%] 764 765 =================== 2 passed, 1 skipped in 0.12 seconds ==================== 766 767.. _`interdependent fixtures`: 768 769Modularity: using fixtures from a fixture function 770---------------------------------------------------------- 771 772You can not only use fixtures in test functions but fixture functions 773can use other fixtures themselves. This contributes to a modular design 774of your fixtures and allows re-use of framework-specific fixtures across 775many projects. As a simple example, we can extend the previous example 776and instantiate an object ``app`` where we stick the already defined 777``smtp_connection`` resource into it:: 778 779 # content of test_appsetup.py 780 781 import pytest 782 783 class App(object): 784 def __init__(self, smtp_connection): 785 self.smtp_connection = smtp_connection 786 787 @pytest.fixture(scope="module") 788 def app(smtp_connection): 789 return App(smtp_connection) 790 791 def test_smtp_connection_exists(app): 792 assert app.smtp_connection 793 794Here we declare an ``app`` fixture which receives the previously defined 795``smtp_connection`` fixture and instantiates an ``App`` object with it. Let's run it: 796 797.. code-block:: pytest 798 799 $ pytest -v test_appsetup.py 800 =========================== test session starts ============================ 801 platform linux -- Python 3.x.y, pytest-4.x.y, py-1.x.y, pluggy-0.x.y -- $PYTHON_PREFIX/bin/python 802 cachedir: $PYTHON_PREFIX/.pytest_cache 803 rootdir: $REGENDOC_TMPDIR 804 collecting ... collected 2 items 805 806 test_appsetup.py::test_smtp_connection_exists[smtp.gmail.com] PASSED [ 50%] 807 test_appsetup.py::test_smtp_connection_exists[mail.python.org] PASSED [100%] 808 809 ========================= 2 passed in 0.12 seconds ========================= 810 811Due to the parametrization of ``smtp_connection``, the test will run twice with two 812different ``App`` instances and respective smtp servers. There is no 813need for the ``app`` fixture to be aware of the ``smtp_connection`` 814parametrization because pytest will fully analyse the fixture dependency graph. 815 816Note that the ``app`` fixture has a scope of ``module`` and uses a 817module-scoped ``smtp_connection`` fixture. The example would still work if 818``smtp_connection`` was cached on a ``session`` scope: it is fine for fixtures to use 819"broader" scoped fixtures but not the other way round: 820A session-scoped fixture could not use a module-scoped one in a 821meaningful way. 822 823 824.. _`automatic per-resource grouping`: 825 826Automatic grouping of tests by fixture instances 827---------------------------------------------------------- 828 829.. regendoc: wipe 830 831pytest minimizes the number of active fixtures during test runs. 832If you have a parametrized fixture, then all the tests using it will 833first execute with one instance and then finalizers are called 834before the next fixture instance is created. Among other things, 835this eases testing of applications which create and use global state. 836 837The following example uses two parametrized fixtures, one of which is 838scoped on a per-module basis, and all the functions perform ``print`` calls 839to show the setup/teardown flow:: 840 841 # content of test_module.py 842 import pytest 843 844 @pytest.fixture(scope="module", params=["mod1", "mod2"]) 845 def modarg(request): 846 param = request.param 847 print(" SETUP modarg %s" % param) 848 yield param 849 print(" TEARDOWN modarg %s" % param) 850 851 @pytest.fixture(scope="function", params=[1,2]) 852 def otherarg(request): 853 param = request.param 854 print(" SETUP otherarg %s" % param) 855 yield param 856 print(" TEARDOWN otherarg %s" % param) 857 858 def test_0(otherarg): 859 print(" RUN test0 with otherarg %s" % otherarg) 860 def test_1(modarg): 861 print(" RUN test1 with modarg %s" % modarg) 862 def test_2(otherarg, modarg): 863 print(" RUN test2 with otherarg %s and modarg %s" % (otherarg, modarg)) 864 865 866Let's run the tests in verbose mode and with looking at the print-output: 867 868.. code-block:: pytest 869 870 $ pytest -v -s test_module.py 871 =========================== test session starts ============================ 872 platform linux -- Python 3.x.y, pytest-4.x.y, py-1.x.y, pluggy-0.x.y -- $PYTHON_PREFIX/bin/python 873 cachedir: $PYTHON_PREFIX/.pytest_cache 874 rootdir: $REGENDOC_TMPDIR 875 collecting ... collected 8 items 876 877 test_module.py::test_0[1] SETUP otherarg 1 878 RUN test0 with otherarg 1 879 PASSED TEARDOWN otherarg 1 880 881 test_module.py::test_0[2] SETUP otherarg 2 882 RUN test0 with otherarg 2 883 PASSED TEARDOWN otherarg 2 884 885 test_module.py::test_1[mod1] SETUP modarg mod1 886 RUN test1 with modarg mod1 887 PASSED 888 test_module.py::test_2[mod1-1] SETUP otherarg 1 889 RUN test2 with otherarg 1 and modarg mod1 890 PASSED TEARDOWN otherarg 1 891 892 test_module.py::test_2[mod1-2] SETUP otherarg 2 893 RUN test2 with otherarg 2 and modarg mod1 894 PASSED TEARDOWN otherarg 2 895 896 test_module.py::test_1[mod2] TEARDOWN modarg mod1 897 SETUP modarg mod2 898 RUN test1 with modarg mod2 899 PASSED 900 test_module.py::test_2[mod2-1] SETUP otherarg 1 901 RUN test2 with otherarg 1 and modarg mod2 902 PASSED TEARDOWN otherarg 1 903 904 test_module.py::test_2[mod2-2] SETUP otherarg 2 905 RUN test2 with otherarg 2 and modarg mod2 906 PASSED TEARDOWN otherarg 2 907 TEARDOWN modarg mod2 908 909 910 ========================= 8 passed in 0.12 seconds ========================= 911 912You can see that the parametrized module-scoped ``modarg`` resource caused an 913ordering of test execution that lead to the fewest possible "active" resources. 914The finalizer for the ``mod1`` parametrized resource was executed before the 915``mod2`` resource was setup. 916 917In particular notice that test_0 is completely independent and finishes first. 918Then test_1 is executed with ``mod1``, then test_2 with ``mod1``, then test_1 919with ``mod2`` and finally test_2 with ``mod2``. 920 921The ``otherarg`` parametrized resource (having function scope) was set up before 922and teared down after every test that used it. 923 924 925.. _`usefixtures`: 926 927Using fixtures from classes, modules or projects 928---------------------------------------------------------------------- 929 930.. regendoc:wipe 931 932Sometimes test functions do not directly need access to a fixture object. 933For example, tests may require to operate with an empty directory as the 934current working directory but otherwise do not care for the concrete 935directory. Here is how you can use the standard `tempfile 936<http://docs.python.org/library/tempfile.html>`_ and pytest fixtures to 937achieve it. We separate the creation of the fixture into a conftest.py 938file:: 939 940 # content of conftest.py 941 942 import pytest 943 import tempfile 944 import os 945 946 @pytest.fixture() 947 def cleandir(): 948 newpath = tempfile.mkdtemp() 949 os.chdir(newpath) 950 951and declare its use in a test module via a ``usefixtures`` marker:: 952 953 # content of test_setenv.py 954 import os 955 import pytest 956 957 @pytest.mark.usefixtures("cleandir") 958 class TestDirectoryInit(object): 959 def test_cwd_starts_empty(self): 960 assert os.listdir(os.getcwd()) == [] 961 with open("myfile", "w") as f: 962 f.write("hello") 963 964 def test_cwd_again_starts_empty(self): 965 assert os.listdir(os.getcwd()) == [] 966 967Due to the ``usefixtures`` marker, the ``cleandir`` fixture 968will be required for the execution of each test method, just as if 969you specified a "cleandir" function argument to each of them. Let's run it 970to verify our fixture is activated and the tests pass: 971 972.. code-block:: pytest 973 974 $ pytest -q 975 .. [100%] 976 2 passed in 0.12 seconds 977 978You can specify multiple fixtures like this: 979 980.. code-block:: python 981 982 @pytest.mark.usefixtures("cleandir", "anotherfixture") 983 def test(): 984 ... 985 986and you may specify fixture usage at the test module level, using 987a generic feature of the mark mechanism: 988 989.. code-block:: python 990 991 pytestmark = pytest.mark.usefixtures("cleandir") 992 993Note that the assigned variable *must* be called ``pytestmark``, assigning e.g. 994``foomark`` will not activate the fixtures. 995 996It is also possible to put fixtures required by all tests in your project 997into an ini-file: 998 999.. code-block:: ini 1000 1001 # content of pytest.ini 1002 [pytest] 1003 usefixtures = cleandir 1004 1005 1006.. warning:: 1007 1008 Note this mark has no effect in **fixture functions**. For example, 1009 this **will not work as expected**: 1010 1011 .. code-block:: python 1012 1013 @pytest.mark.usefixtures("my_other_fixture") 1014 @pytest.fixture 1015 def my_fixture_that_sadly_wont_use_my_other_fixture(): 1016 ... 1017 1018 Currently this will not generate any error or warning, but this is intended 1019 to be handled by `#3664 <https://github.com/pytest-dev/pytest/issues/3664>`_. 1020 1021 1022.. _`autouse`: 1023.. _`autouse fixtures`: 1024 1025Autouse fixtures (xUnit setup on steroids) 1026---------------------------------------------------------------------- 1027 1028.. regendoc:wipe 1029 1030Occasionally, you may want to have fixtures get invoked automatically 1031without declaring a function argument explicitly or a `usefixtures`_ decorator. 1032As a practical example, suppose we have a database fixture which has a 1033begin/rollback/commit architecture and we want to automatically surround 1034each test method by a transaction and a rollback. Here is a dummy 1035self-contained implementation of this idea:: 1036 1037 # content of test_db_transact.py 1038 1039 import pytest 1040 1041 class DB(object): 1042 def __init__(self): 1043 self.intransaction = [] 1044 def begin(self, name): 1045 self.intransaction.append(name) 1046 def rollback(self): 1047 self.intransaction.pop() 1048 1049 @pytest.fixture(scope="module") 1050 def db(): 1051 return DB() 1052 1053 class TestClass(object): 1054 @pytest.fixture(autouse=True) 1055 def transact(self, request, db): 1056 db.begin(request.function.__name__) 1057 yield 1058 db.rollback() 1059 1060 def test_method1(self, db): 1061 assert db.intransaction == ["test_method1"] 1062 1063 def test_method2(self, db): 1064 assert db.intransaction == ["test_method2"] 1065 1066The class-level ``transact`` fixture is marked with *autouse=true* 1067which implies that all test methods in the class will use this fixture 1068without a need to state it in the test function signature or with a 1069class-level ``usefixtures`` decorator. 1070 1071If we run it, we get two passing tests: 1072 1073.. code-block:: pytest 1074 1075 $ pytest -q 1076 .. [100%] 1077 2 passed in 0.12 seconds 1078 1079Here is how autouse fixtures work in other scopes: 1080 1081- autouse fixtures obey the ``scope=`` keyword-argument: if an autouse fixture 1082 has ``scope='session'`` it will only be run once, no matter where it is 1083 defined. ``scope='class'`` means it will be run once per class, etc. 1084 1085- if an autouse fixture is defined in a test module, all its test 1086 functions automatically use it. 1087 1088- if an autouse fixture is defined in a conftest.py file then all tests in 1089 all test modules below its directory will invoke the fixture. 1090 1091- lastly, and **please use that with care**: if you define an autouse 1092 fixture in a plugin, it will be invoked for all tests in all projects 1093 where the plugin is installed. This can be useful if a fixture only 1094 anyway works in the presence of certain settings e. g. in the ini-file. Such 1095 a global fixture should always quickly determine if it should do 1096 any work and avoid otherwise expensive imports or computation. 1097 1098Note that the above ``transact`` fixture may very well be a fixture that 1099you want to make available in your project without having it generally 1100active. The canonical way to do that is to put the transact definition 1101into a conftest.py file **without** using ``autouse``:: 1102 1103 # content of conftest.py 1104 @pytest.fixture 1105 def transact(request, db): 1106 db.begin() 1107 yield 1108 db.rollback() 1109 1110and then e.g. have a TestClass using it by declaring the need:: 1111 1112 @pytest.mark.usefixtures("transact") 1113 class TestClass(object): 1114 def test_method1(self): 1115 ... 1116 1117All test methods in this TestClass will use the transaction fixture while 1118other test classes or functions in the module will not use it unless 1119they also add a ``transact`` reference. 1120 1121Overriding fixtures on various levels 1122------------------------------------- 1123 1124In relatively large test suite, you most likely need to ``override`` a ``global`` or ``root`` fixture with a ``locally`` 1125defined one, keeping the test code readable and maintainable. 1126 1127Override a fixture on a folder (conftest) level 1128^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1129 1130Given the tests file structure is: 1131 1132:: 1133 1134 tests/ 1135 __init__.py 1136 1137 conftest.py 1138 # content of tests/conftest.py 1139 import pytest 1140 1141 @pytest.fixture 1142 def username(): 1143 return 'username' 1144 1145 test_something.py 1146 # content of tests/test_something.py 1147 def test_username(username): 1148 assert username == 'username' 1149 1150 subfolder/ 1151 __init__.py 1152 1153 conftest.py 1154 # content of tests/subfolder/conftest.py 1155 import pytest 1156 1157 @pytest.fixture 1158 def username(username): 1159 return 'overridden-' + username 1160 1161 test_something.py 1162 # content of tests/subfolder/test_something.py 1163 def test_username(username): 1164 assert username == 'overridden-username' 1165 1166As you can see, a fixture with the same name can be overridden for certain test folder level. 1167Note that the ``base`` or ``super`` fixture can be accessed from the ``overriding`` 1168fixture easily - used in the example above. 1169 1170Override a fixture on a test module level 1171^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1172 1173Given the tests file structure is: 1174 1175:: 1176 1177 tests/ 1178 __init__.py 1179 1180 conftest.py 1181 # content of tests/conftest.py 1182 import pytest 1183 1184 @pytest.fixture 1185 def username(): 1186 return 'username' 1187 1188 test_something.py 1189 # content of tests/test_something.py 1190 import pytest 1191 1192 @pytest.fixture 1193 def username(username): 1194 return 'overridden-' + username 1195 1196 def test_username(username): 1197 assert username == 'overridden-username' 1198 1199 test_something_else.py 1200 # content of tests/test_something_else.py 1201 import pytest 1202 1203 @pytest.fixture 1204 def username(username): 1205 return 'overridden-else-' + username 1206 1207 def test_username(username): 1208 assert username == 'overridden-else-username' 1209 1210In the example above, a fixture with the same name can be overridden for certain test module. 1211 1212 1213Override a fixture with direct test parametrization 1214^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1215 1216Given the tests file structure is: 1217 1218:: 1219 1220 tests/ 1221 __init__.py 1222 1223 conftest.py 1224 # content of tests/conftest.py 1225 import pytest 1226 1227 @pytest.fixture 1228 def username(): 1229 return 'username' 1230 1231 @pytest.fixture 1232 def other_username(username): 1233 return 'other-' + username 1234 1235 test_something.py 1236 # content of tests/test_something.py 1237 import pytest 1238 1239 @pytest.mark.parametrize('username', ['directly-overridden-username']) 1240 def test_username(username): 1241 assert username == 'directly-overridden-username' 1242 1243 @pytest.mark.parametrize('username', ['directly-overridden-username-other']) 1244 def test_username_other(other_username): 1245 assert other_username == 'other-directly-overridden-username-other' 1246 1247In the example above, a fixture value is overridden by the test parameter value. Note that the value of the fixture 1248can be overridden this way even if the test doesn't use it directly (doesn't mention it in the function prototype). 1249 1250 1251Override a parametrized fixture with non-parametrized one and vice versa 1252^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1253 1254Given the tests file structure is: 1255 1256:: 1257 1258 tests/ 1259 __init__.py 1260 1261 conftest.py 1262 # content of tests/conftest.py 1263 import pytest 1264 1265 @pytest.fixture(params=['one', 'two', 'three']) 1266 def parametrized_username(request): 1267 return request.param 1268 1269 @pytest.fixture 1270 def non_parametrized_username(request): 1271 return 'username' 1272 1273 test_something.py 1274 # content of tests/test_something.py 1275 import pytest 1276 1277 @pytest.fixture 1278 def parametrized_username(): 1279 return 'overridden-username' 1280 1281 @pytest.fixture(params=['one', 'two', 'three']) 1282 def non_parametrized_username(request): 1283 return request.param 1284 1285 def test_username(parametrized_username): 1286 assert parametrized_username == 'overridden-username' 1287 1288 def test_parametrized_username(non_parametrized_username): 1289 assert non_parametrized_username in ['one', 'two', 'three'] 1290 1291 test_something_else.py 1292 # content of tests/test_something_else.py 1293 def test_username(parametrized_username): 1294 assert parametrized_username in ['one', 'two', 'three'] 1295 1296 def test_username(non_parametrized_username): 1297 assert non_parametrized_username == 'username' 1298 1299In the example above, a parametrized fixture is overridden with a non-parametrized version, and 1300a non-parametrized fixture is overridden with a parametrized version for certain test module. 1301The same applies for the test folder level obviously. 1302