1.. _`reference`: 2 3API Reference 4============= 5 6This page contains the full reference to pytest's API. 7 8.. contents:: 9 :depth: 3 10 :local: 11 12Functions 13--------- 14 15pytest.approx 16~~~~~~~~~~~~~ 17 18.. autofunction:: pytest.approx 19 20pytest.fail 21~~~~~~~~~~~ 22 23**Tutorial**: :ref:`skipping` 24 25.. autofunction:: pytest.fail 26 27pytest.skip 28~~~~~~~~~~~ 29 30.. autofunction:: pytest.skip(msg, [allow_module_level=False]) 31 32.. _`pytest.importorskip ref`: 33 34pytest.importorskip 35~~~~~~~~~~~~~~~~~~~ 36 37.. autofunction:: pytest.importorskip 38 39pytest.xfail 40~~~~~~~~~~~~ 41 42.. autofunction:: pytest.xfail 43 44pytest.exit 45~~~~~~~~~~~ 46 47.. autofunction:: pytest.exit 48 49pytest.main 50~~~~~~~~~~~ 51 52.. autofunction:: pytest.main 53 54pytest.param 55~~~~~~~~~~~~ 56 57.. autofunction:: pytest.param(*values, [id], [marks]) 58 59pytest.raises 60~~~~~~~~~~~~~ 61 62**Tutorial**: :ref:`assertraises`. 63 64.. autofunction:: pytest.raises(expected_exception: Exception [, *, match]) 65 :with: excinfo 66 67pytest.deprecated_call 68~~~~~~~~~~~~~~~~~~~~~~ 69 70**Tutorial**: :ref:`ensuring_function_triggers`. 71 72.. autofunction:: pytest.deprecated_call() 73 :with: 74 75pytest.register_assert_rewrite 76~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 77 78**Tutorial**: :ref:`assertion-rewriting`. 79 80.. autofunction:: pytest.register_assert_rewrite 81 82pytest.warns 83~~~~~~~~~~~~ 84 85**Tutorial**: :ref:`assertwarnings` 86 87.. autofunction:: pytest.warns(expected_warning: Exception, [match]) 88 :with: 89 90pytest.freeze_includes 91~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 92 93**Tutorial**: :ref:`freezing-pytest`. 94 95.. autofunction:: pytest.freeze_includes 96 97.. _`marks ref`: 98 99Marks 100----- 101 102Marks can be used apply meta data to *test functions* (but not fixtures), which can then be accessed by 103fixtures or plugins. 104 105 106 107 108.. _`pytest.mark.filterwarnings ref`: 109 110pytest.mark.filterwarnings 111~~~~~~~~~~~~~~~~~~~~~~~~~~ 112 113**Tutorial**: :ref:`filterwarnings`. 114 115Add warning filters to marked test items. 116 117.. py:function:: pytest.mark.filterwarnings(filter) 118 119 :keyword str filter: 120 A *warning specification string*, which is composed of contents of the tuple ``(action, message, category, module, lineno)`` 121 as specified in `The Warnings filter <https://docs.python.org/3/library/warnings.html#warning-filter>`_ section of 122 the Python documentation, separated by ``":"``. Optional fields can be omitted. 123 Module names passed for filtering are not regex-escaped. 124 125 For example: 126 127 .. code-block:: python 128 129 @pytest.mark.filterwarnings("ignore:.*usage will be deprecated.*:DeprecationWarning") 130 def test_foo(): 131 ... 132 133 134.. _`pytest.mark.parametrize ref`: 135 136pytest.mark.parametrize 137~~~~~~~~~~~~~~~~~~~~~~~ 138 139**Tutorial**: :doc:`parametrize`. 140 141This mark has the same signature as :py:meth:`_pytest.python.Metafunc.parametrize`; see there. 142 143 144.. _`pytest.mark.skip ref`: 145 146pytest.mark.skip 147~~~~~~~~~~~~~~~~ 148 149**Tutorial**: :ref:`skip`. 150 151Unconditionally skip a test function. 152 153.. py:function:: pytest.mark.skip(*, reason=None) 154 155 :keyword str reason: Reason why the test function is being skipped. 156 157 158.. _`pytest.mark.skipif ref`: 159 160pytest.mark.skipif 161~~~~~~~~~~~~~~~~~~ 162 163**Tutorial**: :ref:`skipif`. 164 165Skip a test function if a condition is ``True``. 166 167.. py:function:: pytest.mark.skipif(condition, *, reason=None) 168 169 :type condition: bool or str 170 :param condition: ``True/False`` if the condition should be skipped or a :ref:`condition string <string conditions>`. 171 :keyword str reason: Reason why the test function is being skipped. 172 173 174.. _`pytest.mark.usefixtures ref`: 175 176pytest.mark.usefixtures 177~~~~~~~~~~~~~~~~~~~~~~~ 178 179**Tutorial**: :ref:`usefixtures`. 180 181Mark a test function as using the given fixture names. 182 183.. py:function:: pytest.mark.usefixtures(*names) 184 185 :param args: The names of the fixture to use, as strings. 186 187.. note:: 188 189 When using `usefixtures` in hooks, it can only load fixtures when applied to a test function before test setup 190 (for example in the `pytest_collection_modifyitems` hook). 191 192 Also not that his mark has no effect when applied to **fixtures**. 193 194 195 196.. _`pytest.mark.xfail ref`: 197 198pytest.mark.xfail 199~~~~~~~~~~~~~~~~~~ 200 201**Tutorial**: :ref:`xfail`. 202 203Marks a test function as *expected to fail*. 204 205.. py:function:: pytest.mark.xfail(condition=None, *, reason=None, raises=None, run=True, strict=False) 206 207 :type condition: bool or str 208 :param condition: 209 Condition for marking the test function as xfail (``True/False`` or a 210 :ref:`condition string <string conditions>`). If a bool, you also have 211 to specify ``reason`` (see :ref:`condition string <string conditions>`). 212 :keyword str reason: 213 Reason why the test function is marked as xfail. 214 :keyword Type[Exception] raises: 215 Exception subclass expected to be raised by the test function; other exceptions will fail the test. 216 :keyword bool run: 217 If the test function should actually be executed. If ``False``, the function will always xfail and will 218 not be executed (useful if a function is segfaulting). 219 :keyword bool strict: 220 * If ``False`` (the default) the function will be shown in the terminal output as ``xfailed`` if it fails 221 and as ``xpass`` if it passes. In both cases this will not cause the test suite to fail as a whole. This 222 is particularly useful to mark *flaky* tests (tests that fail at random) to be tackled later. 223 * If ``True``, the function will be shown in the terminal output as ``xfailed`` if it fails, but if it 224 unexpectedly passes then it will **fail** the test suite. This is particularly useful to mark functions 225 that are always failing and there should be a clear indication if they unexpectedly start to pass (for example 226 a new release of a library fixes a known bug). 227 228 229Custom marks 230~~~~~~~~~~~~ 231 232Marks are created dynamically using the factory object ``pytest.mark`` and applied as a decorator. 233 234For example: 235 236.. code-block:: python 237 238 @pytest.mark.timeout(10, "slow", method="thread") 239 def test_function(): 240 ... 241 242Will create and attach a :class:`Mark <_pytest.mark.structures.Mark>` object to the collected 243:class:`Item <pytest.Item>`, which can then be accessed by fixtures or hooks with 244:meth:`Node.iter_markers <_pytest.nodes.Node.iter_markers>`. The ``mark`` object will have the following attributes: 245 246.. code-block:: python 247 248 mark.args == (10, "slow") 249 mark.kwargs == {"method": "thread"} 250 251 252.. _`fixtures-api`: 253 254Fixtures 255-------- 256 257**Tutorial**: :ref:`fixture`. 258 259Fixtures are requested by test functions or other fixtures by declaring them as argument names. 260 261 262Example of a test requiring a fixture: 263 264.. code-block:: python 265 266 def test_output(capsys): 267 print("hello") 268 out, err = capsys.readouterr() 269 assert out == "hello\n" 270 271 272Example of a fixture requiring another fixture: 273 274.. code-block:: python 275 276 @pytest.fixture 277 def db_session(tmpdir): 278 fn = tmpdir / "db.file" 279 return connect(str(fn)) 280 281For more details, consult the full :ref:`fixtures docs <fixture>`. 282 283 284.. _`pytest.fixture-api`: 285 286@pytest.fixture 287~~~~~~~~~~~~~~~ 288 289.. autofunction:: pytest.fixture 290 :decorator: 291 292 293.. fixture:: cache 294 295config.cache 296~~~~~~~~~~~~ 297 298**Tutorial**: :ref:`cache`. 299 300The ``config.cache`` object allows other plugins and fixtures 301to store and retrieve values across test runs. To access it from fixtures 302request ``pytestconfig`` into your fixture and get it with ``pytestconfig.cache``. 303 304Under the hood, the cache plugin uses the simple 305``dumps``/``loads`` API of the :py:mod:`json` stdlib module. 306 307.. currentmodule:: _pytest.cacheprovider 308 309.. automethod:: Cache.get 310.. automethod:: Cache.set 311.. automethod:: Cache.makedir 312 313 314.. fixture:: capsys 315 316capsys 317~~~~~~ 318 319**Tutorial**: :doc:`capture`. 320 321.. currentmodule:: _pytest.capture 322 323.. autofunction:: capsys() 324 :no-auto-options: 325 326 Returns an instance of :py:class:`CaptureFixture`. 327 328 Example: 329 330 .. code-block:: python 331 332 def test_output(capsys): 333 print("hello") 334 captured = capsys.readouterr() 335 assert captured.out == "hello\n" 336 337.. autoclass:: CaptureFixture() 338 :members: 339 340 341.. fixture:: capsysbinary 342 343capsysbinary 344~~~~~~~~~~~~ 345 346**Tutorial**: :doc:`capture`. 347 348.. autofunction:: capsysbinary() 349 :no-auto-options: 350 351 Returns an instance of :py:class:`CaptureFixture`. 352 353 Example: 354 355 .. code-block:: python 356 357 def test_output(capsysbinary): 358 print("hello") 359 captured = capsysbinary.readouterr() 360 assert captured.out == b"hello\n" 361 362 363.. fixture:: capfd 364 365capfd 366~~~~~~ 367 368**Tutorial**: :doc:`capture`. 369 370.. autofunction:: capfd() 371 :no-auto-options: 372 373 Returns an instance of :py:class:`CaptureFixture`. 374 375 Example: 376 377 .. code-block:: python 378 379 def test_system_echo(capfd): 380 os.system('echo "hello"') 381 captured = capfd.readouterr() 382 assert captured.out == "hello\n" 383 384 385.. fixture:: capfdbinary 386 387capfdbinary 388~~~~~~~~~~~~ 389 390**Tutorial**: :doc:`capture`. 391 392.. autofunction:: capfdbinary() 393 :no-auto-options: 394 395 Returns an instance of :py:class:`CaptureFixture`. 396 397 Example: 398 399 .. code-block:: python 400 401 def test_system_echo(capfdbinary): 402 os.system('echo "hello"') 403 captured = capfdbinary.readouterr() 404 assert captured.out == b"hello\n" 405 406 407.. fixture:: doctest_namespace 408 409doctest_namespace 410~~~~~~~~~~~~~~~~~ 411 412**Tutorial**: :doc:`doctest`. 413 414.. autofunction:: _pytest.doctest.doctest_namespace() 415 416 Usually this fixture is used in conjunction with another ``autouse`` fixture: 417 418 .. code-block:: python 419 420 @pytest.fixture(autouse=True) 421 def add_np(doctest_namespace): 422 doctest_namespace["np"] = numpy 423 424 For more details: :ref:`doctest_namespace`. 425 426 427.. fixture:: request 428 429request 430~~~~~~~ 431 432**Tutorial**: :ref:`request example`. 433 434The ``request`` fixture is a special fixture providing information of the requesting test function. 435 436.. autoclass:: _pytest.fixtures.FixtureRequest() 437 :members: 438 439 440.. fixture:: pytestconfig 441 442pytestconfig 443~~~~~~~~~~~~ 444 445.. autofunction:: _pytest.fixtures.pytestconfig() 446 447 448.. fixture:: record_property 449 450record_property 451~~~~~~~~~~~~~~~~~~~ 452 453**Tutorial**: :ref:`record_property example`. 454 455.. autofunction:: _pytest.junitxml.record_property() 456 457 458.. fixture:: record_testsuite_property 459 460record_testsuite_property 461~~~~~~~~~~~~~~~~~~~~~~~~~ 462 463**Tutorial**: :ref:`record_testsuite_property example`. 464 465.. autofunction:: _pytest.junitxml.record_testsuite_property() 466 467 468.. fixture:: caplog 469 470caplog 471~~~~~~ 472 473**Tutorial**: :doc:`logging`. 474 475.. autofunction:: _pytest.logging.caplog() 476 :no-auto-options: 477 478 Returns a :class:`_pytest.logging.LogCaptureFixture` instance. 479 480.. autoclass:: _pytest.logging.LogCaptureFixture 481 :members: 482 483 484.. fixture:: monkeypatch 485 486monkeypatch 487~~~~~~~~~~~ 488 489.. currentmodule:: _pytest.monkeypatch 490 491**Tutorial**: :doc:`monkeypatch`. 492 493.. autofunction:: _pytest.monkeypatch.monkeypatch() 494 :no-auto-options: 495 496 Returns a :class:`MonkeyPatch` instance. 497 498.. autoclass:: _pytest.monkeypatch.MonkeyPatch 499 :members: 500 501 502.. fixture:: testdir 503 504testdir 505~~~~~~~ 506 507.. currentmodule:: _pytest.pytester 508 509This fixture provides a :class:`Testdir` instance useful for black-box testing of test files, making it ideal to 510test plugins. 511 512To use it, include in your top-most ``conftest.py`` file: 513 514.. code-block:: python 515 516 pytest_plugins = "pytester" 517 518 519 520.. autoclass:: Testdir() 521 :members: 522 523.. autoclass:: RunResult() 524 :members: 525 526.. autoclass:: LineMatcher() 527 :members: 528 529 530.. fixture:: recwarn 531 532recwarn 533~~~~~~~ 534 535**Tutorial**: :ref:`assertwarnings` 536 537.. currentmodule:: _pytest.recwarn 538 539.. autofunction:: recwarn() 540 :no-auto-options: 541 542.. autoclass:: WarningsRecorder() 543 :members: 544 545Each recorded warning is an instance of :class:`warnings.WarningMessage`. 546 547.. note:: 548 ``DeprecationWarning`` and ``PendingDeprecationWarning`` are treated 549 differently; see :ref:`ensuring_function_triggers`. 550 551 552.. fixture:: tmp_path 553 554tmp_path 555~~~~~~~~ 556 557**Tutorial**: :doc:`tmpdir` 558 559.. currentmodule:: _pytest.tmpdir 560 561.. autofunction:: tmp_path() 562 :no-auto-options: 563 564 565.. fixture:: tmp_path_factory 566 567tmp_path_factory 568~~~~~~~~~~~~~~~~ 569 570**Tutorial**: :ref:`tmp_path_factory example` 571 572.. _`tmp_path_factory factory api`: 573 574``tmp_path_factory`` instances have the following methods: 575 576.. currentmodule:: _pytest.tmpdir 577 578.. automethod:: TempPathFactory.mktemp 579.. automethod:: TempPathFactory.getbasetemp 580 581 582.. fixture:: tmpdir 583 584tmpdir 585~~~~~~ 586 587**Tutorial**: :doc:`tmpdir` 588 589.. currentmodule:: _pytest.tmpdir 590 591.. autofunction:: tmpdir() 592 :no-auto-options: 593 594 595.. fixture:: tmpdir_factory 596 597tmpdir_factory 598~~~~~~~~~~~~~~ 599 600**Tutorial**: :ref:`tmpdir factory example` 601 602.. _`tmpdir factory api`: 603 604``tmpdir_factory`` instances have the following methods: 605 606.. currentmodule:: _pytest.tmpdir 607 608.. automethod:: TempdirFactory.mktemp 609.. automethod:: TempdirFactory.getbasetemp 610 611 612.. _`hook-reference`: 613 614Hooks 615----- 616 617**Tutorial**: :doc:`writing_plugins`. 618 619.. currentmodule:: _pytest.hookspec 620 621Reference to all hooks which can be implemented by :ref:`conftest.py files <localplugin>` and :ref:`plugins <plugins>`. 622 623Bootstrapping hooks 624~~~~~~~~~~~~~~~~~~~ 625 626Bootstrapping hooks called for plugins registered early enough (internal and setuptools plugins). 627 628.. autofunction:: pytest_load_initial_conftests 629.. autofunction:: pytest_cmdline_preparse 630.. autofunction:: pytest_cmdline_parse 631.. autofunction:: pytest_cmdline_main 632 633.. _`initialization-hooks`: 634 635Initialization hooks 636~~~~~~~~~~~~~~~~~~~~ 637 638Initialization hooks called for plugins and ``conftest.py`` files. 639 640.. autofunction:: pytest_addoption 641.. autofunction:: pytest_addhooks 642.. autofunction:: pytest_configure 643.. autofunction:: pytest_unconfigure 644.. autofunction:: pytest_sessionstart 645.. autofunction:: pytest_sessionfinish 646 647.. autofunction:: pytest_plugin_registered 648 649Collection hooks 650~~~~~~~~~~~~~~~~ 651 652``pytest`` calls the following hooks for collecting files and directories: 653 654.. autofunction:: pytest_collection 655.. autofunction:: pytest_ignore_collect 656.. autofunction:: pytest_collect_file 657.. autofunction:: pytest_pycollect_makemodule 658 659For influencing the collection of objects in Python modules 660you can use the following hook: 661 662.. autofunction:: pytest_pycollect_makeitem 663.. autofunction:: pytest_generate_tests 664.. autofunction:: pytest_make_parametrize_id 665 666After collection is complete, you can modify the order of 667items, delete or otherwise amend the test items: 668 669.. autofunction:: pytest_collection_modifyitems 670 671.. autofunction:: pytest_collection_finish 672 673Test running (runtest) hooks 674~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 675 676All runtest related hooks receive a :py:class:`pytest.Item <pytest.Item>` object. 677 678.. autofunction:: pytest_runtestloop 679.. autofunction:: pytest_runtest_protocol 680.. autofunction:: pytest_runtest_logstart 681.. autofunction:: pytest_runtest_logfinish 682.. autofunction:: pytest_runtest_setup 683.. autofunction:: pytest_runtest_call 684.. autofunction:: pytest_runtest_teardown 685.. autofunction:: pytest_runtest_makereport 686 687For deeper understanding you may look at the default implementation of 688these hooks in ``_pytest.runner`` and maybe also 689in ``_pytest.pdb`` which interacts with ``_pytest.capture`` 690and its input/output capturing in order to immediately drop 691into interactive debugging when a test failure occurs. 692 693.. autofunction:: pytest_pyfunc_call 694 695Reporting hooks 696~~~~~~~~~~~~~~~ 697 698Session related reporting hooks: 699 700.. autofunction:: pytest_collectstart 701.. autofunction:: pytest_make_collect_report 702.. autofunction:: pytest_itemcollected 703.. autofunction:: pytest_collectreport 704.. autofunction:: pytest_deselected 705.. autofunction:: pytest_report_header 706.. autofunction:: pytest_report_collectionfinish 707.. autofunction:: pytest_report_teststatus 708.. autofunction:: pytest_terminal_summary 709.. autofunction:: pytest_fixture_setup 710.. autofunction:: pytest_fixture_post_finalizer 711.. autofunction:: pytest_warning_captured 712.. autofunction:: pytest_warning_recorded 713 714Central hook for reporting about test execution: 715 716.. autofunction:: pytest_runtest_logreport 717 718Assertion related hooks: 719 720.. autofunction:: pytest_assertrepr_compare 721.. autofunction:: pytest_assertion_pass 722 723 724Debugging/Interaction hooks 725~~~~~~~~~~~~~~~~~~~~~~~~~~~ 726 727There are few hooks which can be used for special 728reporting or interaction with exceptions: 729 730.. autofunction:: pytest_internalerror 731.. autofunction:: pytest_keyboard_interrupt 732.. autofunction:: pytest_exception_interact 733.. autofunction:: pytest_enter_pdb 734 735 736Objects 737------- 738 739Full reference to objects accessible from :ref:`fixtures <fixture>` or :ref:`hooks <hook-reference>`. 740 741 742CallInfo 743~~~~~~~~ 744 745.. autoclass:: _pytest.runner.CallInfo() 746 :members: 747 748 749Class 750~~~~~ 751 752.. autoclass:: pytest.Class() 753 :members: 754 :show-inheritance: 755 756Collector 757~~~~~~~~~ 758 759.. autoclass:: pytest.Collector() 760 :members: 761 :show-inheritance: 762 763CollectReport 764~~~~~~~~~~~~~ 765 766.. autoclass:: _pytest.reports.CollectReport() 767 :members: 768 :show-inheritance: 769 :inherited-members: 770 771Config 772~~~~~~ 773 774.. autoclass:: _pytest.config.Config() 775 :members: 776 777ExceptionInfo 778~~~~~~~~~~~~~ 779 780.. autoclass:: _pytest._code.ExceptionInfo 781 :members: 782 783 784ExitCode 785~~~~~~~~ 786 787.. autoclass:: pytest.ExitCode 788 :members: 789 790File 791~~~~ 792 793.. autoclass:: pytest.File() 794 :members: 795 :show-inheritance: 796 797 798FixtureDef 799~~~~~~~~~~ 800 801.. autoclass:: _pytest.fixtures.FixtureDef() 802 :members: 803 :show-inheritance: 804 805FSCollector 806~~~~~~~~~~~ 807 808.. autoclass:: _pytest.nodes.FSCollector() 809 :members: 810 :show-inheritance: 811 812Function 813~~~~~~~~ 814 815.. autoclass:: pytest.Function() 816 :members: 817 :show-inheritance: 818 819Item 820~~~~ 821 822.. autoclass:: pytest.Item() 823 :members: 824 :show-inheritance: 825 826MarkDecorator 827~~~~~~~~~~~~~ 828 829.. autoclass:: _pytest.mark.MarkDecorator 830 :members: 831 832 833MarkGenerator 834~~~~~~~~~~~~~ 835 836.. autoclass:: _pytest.mark.MarkGenerator 837 :members: 838 839 840Mark 841~~~~ 842 843.. autoclass:: _pytest.mark.structures.Mark 844 :members: 845 846 847Metafunc 848~~~~~~~~ 849 850.. autoclass:: _pytest.python.Metafunc 851 :members: 852 853Module 854~~~~~~ 855 856.. autoclass:: pytest.Module() 857 :members: 858 :show-inheritance: 859 860Node 861~~~~ 862 863.. autoclass:: _pytest.nodes.Node() 864 :members: 865 866Parser 867~~~~~~ 868 869.. autoclass:: _pytest.config.argparsing.Parser() 870 :members: 871 872 873PytestPluginManager 874~~~~~~~~~~~~~~~~~~~ 875 876.. autoclass:: _pytest.config.PytestPluginManager() 877 :members: 878 :undoc-members: 879 :inherited-members: 880 :show-inheritance: 881 882Session 883~~~~~~~ 884 885.. autoclass:: pytest.Session() 886 :members: 887 :show-inheritance: 888 889TestReport 890~~~~~~~~~~ 891 892.. autoclass:: _pytest.reports.TestReport() 893 :members: 894 :show-inheritance: 895 :inherited-members: 896 897_Result 898~~~~~~~ 899 900Result used within :ref:`hook wrappers <hookwrapper>`. 901 902.. autoclass:: pluggy.callers._Result 903.. automethod:: pluggy.callers._Result.get_result 904.. automethod:: pluggy.callers._Result.force_result 905 906Global Variables 907---------------- 908 909pytest treats some global variables in a special manner when defined in a test module or 910``conftest.py`` files. 911 912 913.. globalvar:: collect_ignore 914 915**Tutorial**: :ref:`customizing-test-collection` 916 917Can be declared in *conftest.py files* to exclude test directories or modules. 918Needs to be ``list[str]``. 919 920.. code-block:: python 921 922 collect_ignore = ["setup.py"] 923 924 925.. globalvar:: collect_ignore_glob 926 927**Tutorial**: :ref:`customizing-test-collection` 928 929Can be declared in *conftest.py files* to exclude test directories or modules 930with Unix shell-style wildcards. Needs to be ``list[str]`` where ``str`` can 931contain glob patterns. 932 933.. code-block:: python 934 935 collect_ignore_glob = ["*_ignore.py"] 936 937 938.. globalvar:: pytest_plugins 939 940**Tutorial**: :ref:`available installable plugins` 941 942Can be declared at the **global** level in *test modules* and *conftest.py files* to register additional plugins. 943Can be either a ``str`` or ``Sequence[str]``. 944 945.. code-block:: python 946 947 pytest_plugins = "myapp.testsupport.myplugin" 948 949.. code-block:: python 950 951 pytest_plugins = ("myapp.testsupport.tools", "myapp.testsupport.regression") 952 953 954.. globalvar:: pytestmark 955 956**Tutorial**: :ref:`scoped-marking` 957 958Can be declared at the **global** level in *test modules* to apply one or more :ref:`marks <marks ref>` to all 959test functions and methods. Can be either a single mark or a list of marks (applied in left-to-right order). 960 961.. code-block:: python 962 963 import pytest 964 965 pytestmark = pytest.mark.webtest 966 967 968.. code-block:: python 969 970 import pytest 971 972 pytestmark = [pytest.mark.integration, pytest.mark.slow] 973 974 975Environment Variables 976--------------------- 977 978Environment variables that can be used to change pytest's behavior. 979 980.. envvar:: PYTEST_ADDOPTS 981 982This contains a command-line (parsed by the py:mod:`shlex` module) that will be **prepended** to the command line given 983by the user, see :ref:`adding default options` for more information. 984 985.. envvar:: PYTEST_CURRENT_TEST 986 987This is not meant to be set by users, but is set by pytest internally with the name of the current test so other 988processes can inspect it, see :ref:`pytest current test env` for more information. 989 990.. envvar:: PYTEST_DEBUG 991 992When set, pytest will print tracing and debug information. 993 994.. envvar:: PYTEST_DISABLE_PLUGIN_AUTOLOAD 995 996When set, disables plugin auto-loading through setuptools entrypoints. Only explicitly specified plugins will be 997loaded. 998 999.. envvar:: PYTEST_PLUGINS 1000 1001Contains comma-separated list of modules that should be loaded as plugins: 1002 1003.. code-block:: bash 1004 1005 export PYTEST_PLUGINS=mymodule.plugin,xdist 1006 1007.. envvar:: PY_COLORS 1008 1009When set to ``1``, pytest will use color in terminal output. 1010When set to ``0``, pytest will not use color. 1011``PY_COLORS`` takes precedence over ``NO_COLOR`` and ``FORCE_COLOR``. 1012 1013.. envvar:: NO_COLOR 1014 1015When set (regardless of value), pytest will not use color in terminal output. 1016``PY_COLORS`` takes precedence over ``NO_COLOR``, which takes precedence over ``FORCE_COLOR``. 1017See `no-color.org <https://no-color.org/>`__ for other libraries supporting this community standard. 1018 1019.. envvar:: FORCE_COLOR 1020 1021When set (regardless of value), pytest will use color in terminal output. 1022``PY_COLORS`` and ``NO_COLOR`` take precedence over ``FORCE_COLOR``. 1023 1024Exceptions 1025---------- 1026 1027.. autoclass:: pytest.UsageError() 1028 :show-inheritance: 1029 1030.. _`warnings ref`: 1031 1032Warnings 1033-------- 1034 1035Custom warnings generated in some situations such as improper usage or deprecated features. 1036 1037.. autoclass:: pytest.PytestWarning 1038 :show-inheritance: 1039 1040.. autoclass:: pytest.PytestAssertRewriteWarning 1041 :show-inheritance: 1042 1043.. autoclass:: pytest.PytestCacheWarning 1044 :show-inheritance: 1045 1046.. autoclass:: pytest.PytestCollectionWarning 1047 :show-inheritance: 1048 1049.. autoclass:: pytest.PytestConfigWarning 1050 :show-inheritance: 1051 1052.. autoclass:: pytest.PytestDeprecationWarning 1053 :show-inheritance: 1054 1055.. autoclass:: pytest.PytestExperimentalApiWarning 1056 :show-inheritance: 1057 1058.. autoclass:: pytest.PytestUnhandledCoroutineWarning 1059 :show-inheritance: 1060 1061.. autoclass:: pytest.PytestUnknownMarkWarning 1062 :show-inheritance: 1063 1064 1065Consult the :ref:`internal-warnings` section in the documentation for more information. 1066 1067 1068.. _`ini options ref`: 1069 1070Configuration Options 1071--------------------- 1072 1073Here is a list of builtin configuration options that may be written in a ``pytest.ini``, ``pyproject.toml``, ``tox.ini`` or ``setup.cfg`` 1074file, usually located at the root of your repository. To see each file format in details, see 1075:ref:`config file formats`. 1076 1077.. warning:: 1078 Usage of ``setup.cfg`` is not recommended except for very simple use cases. ``.cfg`` 1079 files use a different parser than ``pytest.ini`` and ``tox.ini`` which might cause hard to track 1080 down problems. 1081 When possible, it is recommended to use the latter files, or ``pyproject.toml``, to hold your pytest configuration. 1082 1083Configuration options may be overwritten in the command-line by using ``-o/--override-ini``, which can also be 1084passed multiple times. The expected format is ``name=value``. For example:: 1085 1086 pytest -o console_output_style=classic -o cache_dir=/tmp/mycache 1087 1088 1089.. confval:: addopts 1090 1091 Add the specified ``OPTS`` to the set of command line arguments as if they 1092 had been specified by the user. Example: if you have this ini file content: 1093 1094 .. code-block:: ini 1095 1096 # content of pytest.ini 1097 [pytest] 1098 addopts = --maxfail=2 -rf # exit after 2 failures, report fail info 1099 1100 issuing ``pytest test_hello.py`` actually means: 1101 1102 .. code-block:: bash 1103 1104 pytest --maxfail=2 -rf test_hello.py 1105 1106 Default is to add no options. 1107 1108 1109.. confval:: cache_dir 1110 1111 Sets a directory where stores content of cache plugin. Default directory is 1112 ``.pytest_cache`` which is created in :ref:`rootdir <rootdir>`. Directory may be 1113 relative or absolute path. If setting relative path, then directory is created 1114 relative to :ref:`rootdir <rootdir>`. Additionally path may contain environment 1115 variables, that will be expanded. For more information about cache plugin 1116 please refer to :ref:`cache_provider`. 1117 1118 1119.. confval:: confcutdir 1120 1121 Sets a directory where search upwards for ``conftest.py`` files stops. 1122 By default, pytest will stop searching for ``conftest.py`` files upwards 1123 from ``pytest.ini``/``tox.ini``/``setup.cfg`` of the project if any, 1124 or up to the file-system root. 1125 1126 1127.. confval:: console_output_style 1128 1129 1130 1131 Sets the console output style while running tests: 1132 1133 * ``classic``: classic pytest output. 1134 * ``progress``: like classic pytest output, but with a progress indicator. 1135 * ``count``: like progress, but shows progress as the number of tests completed instead of a percent. 1136 1137 The default is ``progress``, but you can fallback to ``classic`` if you prefer or 1138 the new mode is causing unexpected problems: 1139 1140 .. code-block:: ini 1141 1142 # content of pytest.ini 1143 [pytest] 1144 console_output_style = classic 1145 1146 1147.. confval:: doctest_encoding 1148 1149 1150 1151 Default encoding to use to decode text files with docstrings. 1152 :doc:`See how pytest handles doctests <doctest>`. 1153 1154 1155.. confval:: doctest_optionflags 1156 1157 One or more doctest flag names from the standard ``doctest`` module. 1158 :doc:`See how pytest handles doctests <doctest>`. 1159 1160 1161.. confval:: empty_parameter_set_mark 1162 1163 1164 1165 Allows to pick the action for empty parametersets in parameterization 1166 1167 * ``skip`` skips tests with an empty parameterset (default) 1168 * ``xfail`` marks tests with an empty parameterset as xfail(run=False) 1169 * ``fail_at_collect`` raises an exception if parametrize collects an empty parameter set 1170 1171 .. code-block:: ini 1172 1173 # content of pytest.ini 1174 [pytest] 1175 empty_parameter_set_mark = xfail 1176 1177 .. note:: 1178 1179 The default value of this option is planned to change to ``xfail`` in future releases 1180 as this is considered less error prone, see `#3155 <https://github.com/pytest-dev/pytest/issues/3155>`_ 1181 for more details. 1182 1183 1184.. confval:: faulthandler_timeout 1185 1186 Dumps the tracebacks of all threads if a test takes longer than ``X`` seconds to run (including 1187 fixture setup and teardown). Implemented using the `faulthandler.dump_traceback_later`_ function, 1188 so all caveats there apply. 1189 1190 .. code-block:: ini 1191 1192 # content of pytest.ini 1193 [pytest] 1194 faulthandler_timeout=5 1195 1196 For more information please refer to :ref:`faulthandler`. 1197 1198.. _`faulthandler.dump_traceback_later`: https://docs.python.org/3/library/faulthandler.html#faulthandler.dump_traceback_later 1199 1200 1201.. confval:: filterwarnings 1202 1203 1204 1205 Sets a list of filters and actions that should be taken for matched 1206 warnings. By default all warnings emitted during the test session 1207 will be displayed in a summary at the end of the test session. 1208 1209 .. code-block:: ini 1210 1211 # content of pytest.ini 1212 [pytest] 1213 filterwarnings = 1214 error 1215 ignore::DeprecationWarning 1216 1217 This tells pytest to ignore deprecation warnings and turn all other warnings 1218 into errors. For more information please refer to :ref:`warnings`. 1219 1220 1221.. confval:: junit_duration_report 1222 1223 .. versionadded:: 4.1 1224 1225 Configures how durations are recorded into the JUnit XML report: 1226 1227 * ``total`` (the default): duration times reported include setup, call, and teardown times. 1228 * ``call``: duration times reported include only call times, excluding setup and teardown. 1229 1230 .. code-block:: ini 1231 1232 [pytest] 1233 junit_duration_report = call 1234 1235 1236.. confval:: junit_family 1237 1238 .. versionadded:: 4.2 1239 1240 Configures the format of the generated JUnit XML file. The possible options are: 1241 1242 * ``xunit1`` (or ``legacy``): produces old style output, compatible with the xunit 1.0 format. **This is the default**. 1243 * ``xunit2``: produces `xunit 2.0 style output <https://github.com/jenkinsci/xunit-plugin/blob/xunit-2.3.2/src/main/resources/org/jenkinsci/plugins/xunit/types/model/xsd/junit-10.xsd>`__, 1244 which should be more compatible with latest Jenkins versions. 1245 1246 .. code-block:: ini 1247 1248 [pytest] 1249 junit_family = xunit2 1250 1251 1252.. confval:: junit_logging 1253 1254 .. versionadded:: 3.5 1255 .. versionchanged:: 5.4 1256 ``log``, ``all``, ``out-err`` options added. 1257 1258 Configures if captured output should be written to the JUnit XML file. Valid values are: 1259 1260 * ``log``: write only ``logging`` captured output. 1261 * ``system-out``: write captured ``stdout`` contents. 1262 * ``system-err``: write captured ``stderr`` contents. 1263 * ``out-err``: write both captured ``stdout`` and ``stderr`` contents. 1264 * ``all``: write captured ``logging``, ``stdout`` and ``stderr`` contents. 1265 * ``no`` (the default): no captured output is written. 1266 1267 .. code-block:: ini 1268 1269 [pytest] 1270 junit_logging = system-out 1271 1272 1273.. confval:: junit_log_passing_tests 1274 1275 .. versionadded:: 4.6 1276 1277 If ``junit_logging != "no"``, configures if the captured output should be written 1278 to the JUnit XML file for **passing** tests. Default is ``True``. 1279 1280 .. code-block:: ini 1281 1282 [pytest] 1283 junit_log_passing_tests = False 1284 1285 1286.. confval:: junit_suite_name 1287 1288 To set the name of the root test suite xml item, you can configure the ``junit_suite_name`` option in your config file: 1289 1290 .. code-block:: ini 1291 1292 [pytest] 1293 junit_suite_name = my_suite 1294 1295.. confval:: log_auto_indent 1296 1297 Allow selective auto-indentation of multiline log messages. 1298 1299 Supports command line option ``--log-auto-indent [value]`` 1300 and config option ``log_auto_indent = [value]`` to set the 1301 auto-indentation behavior for all logging. 1302 1303 ``[value]`` can be: 1304 * True or "On" - Dynamically auto-indent multiline log messages 1305 * False or "Off" or 0 - Do not auto-indent multiline log messages (the default behavior) 1306 * [positive integer] - auto-indent multiline log messages by [value] spaces 1307 1308 .. code-block:: ini 1309 1310 [pytest] 1311 log_auto_indent = False 1312 1313 Supports passing kwarg ``extra={"auto_indent": [value]}`` to 1314 calls to ``logging.log()`` to specify auto-indentation behavior for 1315 a specific entry in the log. ``extra`` kwarg overrides the value specified 1316 on the command line or in the config. 1317 1318.. confval:: log_cli 1319 1320 Enable log display during test run (also known as :ref:`"live logging" <live_logs>`). 1321 The default is ``False``. 1322 1323 .. code-block:: ini 1324 1325 [pytest] 1326 log_cli = True 1327 1328.. confval:: log_cli_date_format 1329 1330 1331 1332 Sets a :py:func:`time.strftime`-compatible string that will be used when formatting dates for live logging. 1333 1334 .. code-block:: ini 1335 1336 [pytest] 1337 log_cli_date_format = %Y-%m-%d %H:%M:%S 1338 1339 For more information, see :ref:`live_logs`. 1340 1341.. confval:: log_cli_format 1342 1343 1344 1345 Sets a :py:mod:`logging`-compatible string used to format live logging messages. 1346 1347 .. code-block:: ini 1348 1349 [pytest] 1350 log_cli_format = %(asctime)s %(levelname)s %(message)s 1351 1352 For more information, see :ref:`live_logs`. 1353 1354 1355.. confval:: log_cli_level 1356 1357 1358 1359 Sets the minimum log message level that should be captured for live logging. The integer value or 1360 the names of the levels can be used. 1361 1362 .. code-block:: ini 1363 1364 [pytest] 1365 log_cli_level = INFO 1366 1367 For more information, see :ref:`live_logs`. 1368 1369 1370.. confval:: log_date_format 1371 1372 1373 1374 Sets a :py:func:`time.strftime`-compatible string that will be used when formatting dates for logging capture. 1375 1376 .. code-block:: ini 1377 1378 [pytest] 1379 log_date_format = %Y-%m-%d %H:%M:%S 1380 1381 For more information, see :ref:`logging`. 1382 1383 1384.. confval:: log_file 1385 1386 1387 1388 Sets a file name relative to the ``pytest.ini`` file where log messages should be written to, in addition 1389 to the other logging facilities that are active. 1390 1391 .. code-block:: ini 1392 1393 [pytest] 1394 log_file = logs/pytest-logs.txt 1395 1396 For more information, see :ref:`logging`. 1397 1398 1399.. confval:: log_file_date_format 1400 1401 1402 1403 Sets a :py:func:`time.strftime`-compatible string that will be used when formatting dates for the logging file. 1404 1405 .. code-block:: ini 1406 1407 [pytest] 1408 log_file_date_format = %Y-%m-%d %H:%M:%S 1409 1410 For more information, see :ref:`logging`. 1411 1412.. confval:: log_file_format 1413 1414 1415 1416 Sets a :py:mod:`logging`-compatible string used to format logging messages redirected to the logging file. 1417 1418 .. code-block:: ini 1419 1420 [pytest] 1421 log_file_format = %(asctime)s %(levelname)s %(message)s 1422 1423 For more information, see :ref:`logging`. 1424 1425.. confval:: log_file_level 1426 1427 1428 1429 Sets the minimum log message level that should be captured for the logging file. The integer value or 1430 the names of the levels can be used. 1431 1432 .. code-block:: ini 1433 1434 [pytest] 1435 log_file_level = INFO 1436 1437 For more information, see :ref:`logging`. 1438 1439 1440.. confval:: log_format 1441 1442 1443 1444 Sets a :py:mod:`logging`-compatible string used to format captured logging messages. 1445 1446 .. code-block:: ini 1447 1448 [pytest] 1449 log_format = %(asctime)s %(levelname)s %(message)s 1450 1451 For more information, see :ref:`logging`. 1452 1453 1454.. confval:: log_level 1455 1456 1457 1458 Sets the minimum log message level that should be captured for logging capture. The integer value or 1459 the names of the levels can be used. 1460 1461 .. code-block:: ini 1462 1463 [pytest] 1464 log_level = INFO 1465 1466 For more information, see :ref:`logging`. 1467 1468 1469.. confval:: markers 1470 1471 When the ``--strict-markers`` or ``--strict`` command-line arguments are used, 1472 only known markers - defined in code by core pytest or some plugin - are allowed. 1473 1474 You can list additional markers in this setting to add them to the whitelist, 1475 in which case you probably want to add ``--strict-markers`` to ``addopts`` 1476 to avoid future regressions: 1477 1478 .. code-block:: ini 1479 1480 [pytest] 1481 addopts = --strict-markers 1482 markers = 1483 slow 1484 serial 1485 1486 .. note:: 1487 The use of ``--strict-markers`` is highly preferred. ``--strict`` was kept for 1488 backward compatibility only and may be confusing for others as it only applies to 1489 markers and not to other options. 1490 1491.. confval:: minversion 1492 1493 Specifies a minimal pytest version required for running tests. 1494 1495 .. code-block:: ini 1496 1497 # content of pytest.ini 1498 [pytest] 1499 minversion = 3.0 # will fail if we run with pytest-2.8 1500 1501 1502.. confval:: norecursedirs 1503 1504 Set the directory basename patterns to avoid when recursing 1505 for test discovery. The individual (fnmatch-style) patterns are 1506 applied to the basename of a directory to decide if to recurse into it. 1507 Pattern matching characters:: 1508 1509 * matches everything 1510 ? matches any single character 1511 [seq] matches any character in seq 1512 [!seq] matches any char not in seq 1513 1514 Default patterns are ``'.*', 'build', 'dist', 'CVS', '_darcs', '{arch}', '*.egg', 'venv'``. 1515 Setting a ``norecursedirs`` replaces the default. Here is an example of 1516 how to avoid certain directories: 1517 1518 .. code-block:: ini 1519 1520 [pytest] 1521 norecursedirs = .svn _build tmp* 1522 1523 This would tell ``pytest`` to not look into typical subversion or 1524 sphinx-build directories or into any ``tmp`` prefixed directory. 1525 1526 Additionally, ``pytest`` will attempt to intelligently identify and ignore a 1527 virtualenv by the presence of an activation script. Any directory deemed to 1528 be the root of a virtual environment will not be considered during test 1529 collection unless ``‑‑collect‑in‑virtualenv`` is given. Note also that 1530 ``norecursedirs`` takes precedence over ``‑‑collect‑in‑virtualenv``; e.g. if 1531 you intend to run tests in a virtualenv with a base directory that matches 1532 ``'.*'`` you *must* override ``norecursedirs`` in addition to using the 1533 ``‑‑collect‑in‑virtualenv`` flag. 1534 1535 1536.. confval:: python_classes 1537 1538 One or more name prefixes or glob-style patterns determining which classes 1539 are considered for test collection. Search for multiple glob patterns by 1540 adding a space between patterns. By default, pytest will consider any 1541 class prefixed with ``Test`` as a test collection. Here is an example of how 1542 to collect tests from classes that end in ``Suite``: 1543 1544 .. code-block:: ini 1545 1546 [pytest] 1547 python_classes = *Suite 1548 1549 Note that ``unittest.TestCase`` derived classes are always collected 1550 regardless of this option, as ``unittest``'s own collection framework is used 1551 to collect those tests. 1552 1553 1554.. confval:: python_files 1555 1556 One or more Glob-style file patterns determining which python files 1557 are considered as test modules. Search for multiple glob patterns by 1558 adding a space between patterns: 1559 1560 .. code-block:: ini 1561 1562 [pytest] 1563 python_files = test_*.py check_*.py example_*.py 1564 1565 Or one per line: 1566 1567 .. code-block:: ini 1568 1569 [pytest] 1570 python_files = 1571 test_*.py 1572 check_*.py 1573 example_*.py 1574 1575 By default, files matching ``test_*.py`` and ``*_test.py`` will be considered 1576 test modules. 1577 1578 1579.. confval:: python_functions 1580 1581 One or more name prefixes or glob-patterns determining which test functions 1582 and methods are considered tests. Search for multiple glob patterns by 1583 adding a space between patterns. By default, pytest will consider any 1584 function prefixed with ``test`` as a test. Here is an example of how 1585 to collect test functions and methods that end in ``_test``: 1586 1587 .. code-block:: ini 1588 1589 [pytest] 1590 python_functions = *_test 1591 1592 Note that this has no effect on methods that live on a ``unittest 1593 .TestCase`` derived class, as ``unittest``'s own collection framework is used 1594 to collect those tests. 1595 1596 See :ref:`change naming conventions` for more detailed examples. 1597 1598 1599.. confval:: required_plugins 1600 1601 A space separated list of plugins that must be present for pytest to run. 1602 Plugins can be listed with or without version specifiers directly following 1603 their name. Whitespace between different version specifiers is not allowed. 1604 If any one of the plugins is not found, emit an error. 1605 1606 .. code-block:: ini 1607 1608 [pytest] 1609 required_plugins = pytest-django>=3.0.0,<4.0.0 pytest-html pytest-xdist>=1.0.0 1610 1611 1612.. confval:: testpaths 1613 1614 1615 1616 Sets list of directories that should be searched for tests when 1617 no specific directories, files or test ids are given in the command line when 1618 executing pytest from the :ref:`rootdir <rootdir>` directory. 1619 Useful when all project tests are in a known location to speed up 1620 test collection and to avoid picking up undesired tests by accident. 1621 1622 .. code-block:: ini 1623 1624 [pytest] 1625 testpaths = testing doc 1626 1627 This tells pytest to only look for tests in ``testing`` and ``doc`` 1628 directories when executing from the root directory. 1629 1630 1631.. confval:: usefixtures 1632 1633 List of fixtures that will be applied to all test functions; this is semantically the same to apply 1634 the ``@pytest.mark.usefixtures`` marker to all test functions. 1635 1636 1637 .. code-block:: ini 1638 1639 [pytest] 1640 usefixtures = 1641 clean_db 1642 1643 1644.. confval:: xfail_strict 1645 1646 If set to ``True``, tests marked with ``@pytest.mark.xfail`` that actually succeed will by default fail the 1647 test suite. 1648 For more information, see :ref:`xfail strict tutorial`. 1649 1650 1651 .. code-block:: ini 1652 1653 [pytest] 1654 xfail_strict = True 1655 1656 1657.. _`command-line-flags`: 1658 1659Command-line Flags 1660------------------ 1661 1662All the command-line flags can be obtained by running ``pytest --help``:: 1663 1664 $ pytest --help 1665 usage: pytest [options] [file_or_dir] [file_or_dir] [...] 1666 1667 positional arguments: 1668 file_or_dir 1669 1670 general: 1671 -k EXPRESSION only run tests which match the given substring 1672 expression. An expression is a python evaluatable 1673 expression where all names are substring-matched 1674 against test names and their parent classes. 1675 Example: -k 'test_method or test_other' matches all 1676 test functions and classes whose name contains 1677 'test_method' or 'test_other', while -k 'not 1678 test_method' matches those that don't contain 1679 'test_method' in their names. -k 'not test_method 1680 and not test_other' will eliminate the matches. 1681 Additionally keywords are matched to classes and 1682 functions containing extra names in their 1683 'extra_keyword_matches' set, as well as functions 1684 which have names assigned directly to them. The 1685 matching is case-insensitive. 1686 -m MARKEXPR only run tests matching given mark expression. 1687 For example: -m 'mark1 and not mark2'. 1688 --markers show markers (builtin, plugin and per-project ones). 1689 -x, --exitfirst exit instantly on first error or failed test. 1690 --fixtures, --funcargs 1691 show available fixtures, sorted by plugin appearance 1692 (fixtures with leading '_' are only shown with '-v') 1693 --fixtures-per-test show fixtures per test 1694 --pdb start the interactive Python debugger on errors or 1695 KeyboardInterrupt. 1696 --pdbcls=modulename:classname 1697 start a custom interactive Python debugger on 1698 errors. For example: 1699 --pdbcls=IPython.terminal.debugger:TerminalPdb 1700 --trace Immediately break when running each test. 1701 --capture=method per-test capturing method: one of fd|sys|no|tee-sys. 1702 -s shortcut for --capture=no. 1703 --runxfail report the results of xfail tests as if they were 1704 not marked 1705 --lf, --last-failed rerun only the tests that failed at the last run (or 1706 all if none failed) 1707 --ff, --failed-first run all tests, but run the last failures first. 1708 This may re-order tests and thus lead to repeated 1709 fixture setup/teardown. 1710 --nf, --new-first run tests from new files first, then the rest of the 1711 tests sorted by file mtime 1712 --cache-show=[CACHESHOW] 1713 show cache contents, don't perform collection or 1714 tests. Optional argument: glob (default: '*'). 1715 --cache-clear remove all cache contents at start of test run. 1716 --lfnf={all,none}, --last-failed-no-failures={all,none} 1717 which tests to run with no previously (known) 1718 failures. 1719 --sw, --stepwise exit on test failure and continue from last failing 1720 test next time 1721 --stepwise-skip ignore the first failing test but stop on the next 1722 failing test 1723 1724 reporting: 1725 --durations=N show N slowest setup/test durations (N=0 for all). 1726 --durations-min=N Minimal duration in seconds for inclusion in slowest 1727 list. Default 0.005 1728 -v, --verbose increase verbosity. 1729 --no-header disable header 1730 --no-summary disable summary 1731 -q, --quiet decrease verbosity. 1732 --verbosity=VERBOSE set verbosity. Default is 0. 1733 -r chars show extra test summary info as specified by chars: 1734 (f)ailed, (E)rror, (s)kipped, (x)failed, (X)passed, 1735 (p)assed, (P)assed with output, (a)ll except passed 1736 (p/P), or (A)ll. (w)arnings are enabled by default 1737 (see --disable-warnings), 'N' can be used to reset 1738 the list. (default: 'fE'). 1739 --disable-warnings, --disable-pytest-warnings 1740 disable warnings summary 1741 -l, --showlocals show locals in tracebacks (disabled by default). 1742 --tb=style traceback print mode 1743 (auto/long/short/line/native/no). 1744 --show-capture={no,stdout,stderr,log,all} 1745 Controls how captured stdout/stderr/log is shown on 1746 failed tests. Default is 'all'. 1747 --full-trace don't cut any tracebacks (default is to cut). 1748 --color=color color terminal output (yes/no/auto). 1749 --code-highlight={yes,no} 1750 Whether code should be highlighted (only if --color 1751 is also enabled) 1752 --pastebin=mode send failed|all info to bpaste.net pastebin service. 1753 --junit-xml=path create junit-xml style report file at given path. 1754 --junit-prefix=str prepend prefix to classnames in junit-xml output 1755 1756 pytest-warnings: 1757 -W PYTHONWARNINGS, --pythonwarnings=PYTHONWARNINGS 1758 set which warnings to report, see -W option of 1759 python itself. 1760 --maxfail=num exit after first num failures or errors. 1761 --strict-config any warnings encountered while parsing the `pytest` 1762 section of the configuration file raise errors. 1763 --strict-markers, --strict 1764 markers not registered in the `markers` section of 1765 the configuration file raise errors. 1766 -c file load configuration from `file` instead of trying to 1767 locate one of the implicit configuration files. 1768 --continue-on-collection-errors 1769 Force test execution even if collection errors 1770 occur. 1771 --rootdir=ROOTDIR Define root directory for tests. Can be relative 1772 path: 'root_dir', './root_dir', 1773 'root_dir/another_dir/'; absolute path: 1774 '/home/user/root_dir'; path with variables: 1775 '$HOME/root_dir'. 1776 1777 collection: 1778 --collect-only, --co only collect tests, don't execute them. 1779 --pyargs try to interpret all arguments as python packages. 1780 --ignore=path ignore path during collection (multi-allowed). 1781 --ignore-glob=path ignore path pattern during collection (multi- 1782 allowed). 1783 --deselect=nodeid_prefix 1784 deselect item (via node id prefix) during collection 1785 (multi-allowed). 1786 --confcutdir=dir only load conftest.py's relative to specified dir. 1787 --noconftest Don't load any conftest.py files. 1788 --keep-duplicates Keep duplicate tests. 1789 --collect-in-virtualenv 1790 Don't ignore tests in a local virtualenv directory 1791 --import-mode={prepend,append,importlib} 1792 prepend/append to sys.path when importing test 1793 modules and conftest files, default is to prepend. 1794 --doctest-modules run doctests in all .py modules 1795 --doctest-report={none,cdiff,ndiff,udiff,only_first_failure} 1796 choose another output format for diffs on doctest 1797 failure 1798 --doctest-glob=pat doctests file matching pattern, default: test*.txt 1799 --doctest-ignore-import-errors 1800 ignore doctest ImportErrors 1801 --doctest-continue-on-failure 1802 for a given doctest, continue to run after the first 1803 failure 1804 1805 test session debugging and configuration: 1806 --basetemp=dir base temporary directory for this test run.(warning: 1807 this directory is removed if it exists) 1808 -V, --version display pytest version and information about 1809 plugins.When given twice, also display information 1810 about plugins. 1811 -h, --help show help message and configuration info 1812 -p name early-load given plugin module name or entry point 1813 (multi-allowed). 1814 To avoid loading of plugins, use the `no:` prefix, 1815 e.g. `no:doctest`. 1816 --trace-config trace considerations of conftest.py files. 1817 --debug store internal tracing debug information in 1818 'pytestdebug.log'. 1819 -o OVERRIDE_INI, --override-ini=OVERRIDE_INI 1820 override ini option with "option=value" style, e.g. 1821 `-o xfail_strict=True -o cache_dir=cache`. 1822 --assert=MODE Control assertion debugging tools. 1823 'plain' performs no assertion debugging. 1824 'rewrite' (the default) rewrites assert statements 1825 in test modules on import to provide assert 1826 expression information. 1827 --setup-only only setup fixtures, do not execute tests. 1828 --setup-show show setup of fixtures while executing tests. 1829 --setup-plan show what fixtures and tests would be executed but 1830 don't execute anything. 1831 1832 logging: 1833 --log-level=LEVEL level of messages to catch/display. 1834 Not set by default, so it depends on the root/parent 1835 log handler's effective level, where it is "WARNING" 1836 by default. 1837 --log-format=LOG_FORMAT 1838 log format as used by the logging module. 1839 --log-date-format=LOG_DATE_FORMAT 1840 log date format as used by the logging module. 1841 --log-cli-level=LOG_CLI_LEVEL 1842 cli logging level. 1843 --log-cli-format=LOG_CLI_FORMAT 1844 log format as used by the logging module. 1845 --log-cli-date-format=LOG_CLI_DATE_FORMAT 1846 log date format as used by the logging module. 1847 --log-file=LOG_FILE path to a file when logging will be written to. 1848 --log-file-level=LOG_FILE_LEVEL 1849 log file logging level. 1850 --log-file-format=LOG_FILE_FORMAT 1851 log format as used by the logging module. 1852 --log-file-date-format=LOG_FILE_DATE_FORMAT 1853 log date format as used by the logging module. 1854 --log-auto-indent=LOG_AUTO_INDENT 1855 Auto-indent multiline messages passed to the logging 1856 module. Accepts true|on, false|off or an integer. 1857 1858 [pytest] ini-options in the first pytest.ini|tox.ini|setup.cfg file found: 1859 1860 markers (linelist): markers for test functions 1861 empty_parameter_set_mark (string): 1862 default marker for empty parametersets 1863 norecursedirs (args): directory patterns to avoid for recursion 1864 testpaths (args): directories to search for tests when no files or 1865 directories are given in the command line. 1866 filterwarnings (linelist): 1867 Each line specifies a pattern for 1868 warnings.filterwarnings. Processed after 1869 -W/--pythonwarnings. 1870 usefixtures (args): list of default fixtures to be used with this 1871 project 1872 python_files (args): glob-style file patterns for Python test module 1873 discovery 1874 python_classes (args): 1875 prefixes or glob names for Python test class 1876 discovery 1877 python_functions (args): 1878 prefixes or glob names for Python test function and 1879 method discovery 1880 disable_test_id_escaping_and_forfeit_all_rights_to_community_support (bool): 1881 disable string escape non-ascii characters, might 1882 cause unwanted side effects(use at your own risk) 1883 console_output_style (string): 1884 console output: "classic", or with additional 1885 progress information ("progress" (percentage) | 1886 "count"). 1887 xfail_strict (bool): default for the strict parameter of xfail markers 1888 when not given explicitly (default: False) 1889 enable_assertion_pass_hook (bool): 1890 Enables the pytest_assertion_pass hook.Make sure to 1891 delete any previously generated pyc cache files. 1892 junit_suite_name (string): 1893 Test suite name for JUnit report 1894 junit_logging (string): 1895 Write captured log messages to JUnit report: one of 1896 no|log|system-out|system-err|out-err|all 1897 junit_log_passing_tests (bool): 1898 Capture log information for passing tests to JUnit 1899 report: 1900 junit_duration_report (string): 1901 Duration time to report: one of total|call 1902 junit_family (string): 1903 Emit XML for schema: one of legacy|xunit1|xunit2 1904 doctest_optionflags (args): 1905 option flags for doctests 1906 doctest_encoding (string): 1907 encoding used for doctest files 1908 cache_dir (string): cache directory path. 1909 log_level (string): default value for --log-level 1910 log_format (string): default value for --log-format 1911 log_date_format (string): 1912 default value for --log-date-format 1913 log_cli (bool): enable log display during test run (also known as 1914 "live logging"). 1915 log_cli_level (string): 1916 default value for --log-cli-level 1917 log_cli_format (string): 1918 default value for --log-cli-format 1919 log_cli_date_format (string): 1920 default value for --log-cli-date-format 1921 log_file (string): default value for --log-file 1922 log_file_level (string): 1923 default value for --log-file-level 1924 log_file_format (string): 1925 default value for --log-file-format 1926 log_file_date_format (string): 1927 default value for --log-file-date-format 1928 log_auto_indent (string): 1929 default value for --log-auto-indent 1930 faulthandler_timeout (string): 1931 Dump the traceback of all threads if a test takes 1932 more than TIMEOUT seconds to finish. 1933 addopts (args): extra command line options 1934 minversion (string): minimally required pytest version 1935 required_plugins (args): 1936 plugins that must be present for pytest to run 1937 1938 environment variables: 1939 PYTEST_ADDOPTS extra command line options 1940 PYTEST_PLUGINS comma-separated plugins to load during startup 1941 PYTEST_DISABLE_PLUGIN_AUTOLOAD set to disable plugin auto-loading 1942 PYTEST_DEBUG set to enable debug tracing of pytest's internals 1943 1944 1945 to see available markers type: pytest --markers 1946 to see available fixtures type: pytest --fixtures 1947 (shown according to specified file_or_dir or current dir if not specified; fixtures with leading '_' are only shown with the '-v' option 1948