deprecations.rst (40885B)
1 .. _deprecations: 2 3 Deprecations and Removals 4 ========================= 5 6 This page lists all pytest features that are currently deprecated or have been removed in past major releases. 7 The objective is to give users a clear rationale why a certain feature has been removed, and what alternatives 8 should be used instead. 9 10 .. contents:: 11 :depth: 3 12 :local: 13 14 15 Deprecated Features 16 ------------------- 17 18 Below is a complete list of all pytest features which are considered deprecated. Using those features will issue 19 :class:`~pytest.PytestWarning` or subclasses, which can be filtered using :ref:`standard warning filters <warnings>`. 20 21 22 .. _import-or-skip-import-error: 23 24 ``pytest.importorskip`` default behavior regarding :class:`ImportError` 25 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 26 27 .. deprecated:: 8.2 28 29 Traditionally :func:`pytest.importorskip` will capture :class:`ImportError`, with the original intent being to skip 30 tests where a dependent module is not installed, for example testing with different dependencies. 31 32 However some packages might be installed in the system, but are not importable due to 33 some other issue, for example, a compilation error or a broken installation. In those cases :func:`pytest.importorskip` 34 would still silently skip the test, but more often than not users would like to see the unexpected 35 error so the underlying issue can be fixed. 36 37 In ``8.2`` the ``exc_type`` parameter has been added, giving users the ability of passing :class:`ModuleNotFoundError` 38 to skip tests only if the module cannot really be found, and not because of some other error. 39 40 Catching only :class:`ModuleNotFoundError` by default (and letting other errors propagate) would be the best solution, 41 however for backward compatibility, pytest will keep the existing behavior but raise an warning if: 42 43 1. The captured exception is of type :class:`ImportError`, and: 44 2. The user does not pass ``exc_type`` explicitly. 45 46 If the import attempt raises :class:`ModuleNotFoundError` (the usual case), then the module is skipped and no 47 warning is emitted. 48 49 This way, the usual cases will keep working the same way, while unexpected errors will now issue a warning, with 50 users being able to supress the warning by passing ``exc_type=ImportError`` explicitly. 51 52 In ``9.0``, the warning will turn into an error, and in ``9.1`` :func:`pytest.importorskip` will only capture 53 :class:`ModuleNotFoundError` by default and no warnings will be issued anymore -- but users can still capture 54 :class:`ImportError` by passing it to ``exc_type``. 55 56 57 .. _node-ctor-fspath-deprecation: 58 59 ``fspath`` argument for Node constructors replaced with ``pathlib.Path`` 60 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 61 62 .. deprecated:: 7.0 63 64 In order to support the transition from ``py.path.local`` to :mod:`pathlib`, 65 the ``fspath`` argument to :class:`~_pytest.nodes.Node` constructors like 66 :func:`pytest.Function.from_parent()` and :func:`pytest.Class.from_parent()` 67 is now deprecated. 68 69 Plugins which construct nodes should pass the ``path`` argument, of type 70 :class:`pathlib.Path`, instead of the ``fspath`` argument. 71 72 Plugins which implement custom items and collectors are encouraged to replace 73 ``fspath`` parameters (``py.path.local``) with ``path`` parameters 74 (``pathlib.Path``), and drop any other usage of the ``py`` library if possible. 75 76 If possible, plugins with custom items should use :ref:`cooperative 77 constructors <uncooperative-constructors-deprecated>` to avoid hardcoding 78 arguments they only pass on to the superclass. 79 80 .. note:: 81 The name of the :class:`~_pytest.nodes.Node` arguments and attributes (the 82 new attribute being ``path``) is **the opposite** of the situation for 83 hooks, :ref:`outlined below <legacy-path-hooks-deprecated>` (the old 84 argument being ``path``). 85 86 This is an unfortunate artifact due to historical reasons, which should be 87 resolved in future versions as we slowly get rid of the :pypi:`py` 88 dependency (see :issue:`9283` for a longer discussion). 89 90 Due to the ongoing migration of methods like :meth:`~pytest.Item.reportinfo` 91 which still is expected to return a ``py.path.local`` object, nodes still have 92 both ``fspath`` (``py.path.local``) and ``path`` (``pathlib.Path``) attributes, 93 no matter what argument was used in the constructor. We expect to deprecate the 94 ``fspath`` attribute in a future release. 95 96 97 Configuring hook specs/impls using markers 98 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 99 100 Before pluggy, pytest's plugin library, was its own package and had a clear API, 101 pytest just used ``pytest.mark`` to configure hooks. 102 103 The :py:func:`pytest.hookimpl` and :py:func:`pytest.hookspec` decorators 104 have been available since years and should be used instead. 105 106 .. code-block:: python 107 108 @pytest.mark.tryfirst 109 def pytest_runtest_call(): ... 110 111 112 # or 113 def pytest_runtest_call(): ... 114 115 116 pytest_runtest_call.tryfirst = True 117 118 should be changed to: 119 120 .. code-block:: python 121 122 @pytest.hookimpl(tryfirst=True) 123 def pytest_runtest_call(): ... 124 125 Changed ``hookimpl`` attributes: 126 127 * ``tryfirst`` 128 * ``trylast`` 129 * ``optionalhook`` 130 * ``hookwrapper`` 131 132 Changed ``hookwrapper`` attributes: 133 134 * ``firstresult`` 135 * ``historic`` 136 137 138 .. _legacy-path-hooks-deprecated: 139 140 ``py.path.local`` arguments for hooks replaced with ``pathlib.Path`` 141 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 142 143 .. deprecated:: 7.0 144 145 In order to support the transition from ``py.path.local`` to :mod:`pathlib`, the following hooks now receive additional arguments: 146 147 * :hook:`pytest_ignore_collect(collection_path: pathlib.Path) <pytest_ignore_collect>` as equivalent to ``path`` 148 * :hook:`pytest_collect_file(file_path: pathlib.Path) <pytest_collect_file>` as equivalent to ``path`` 149 * :hook:`pytest_pycollect_makemodule(module_path: pathlib.Path) <pytest_pycollect_makemodule>` as equivalent to ``path`` 150 * :hook:`pytest_report_header(start_path: pathlib.Path) <pytest_report_header>` as equivalent to ``startdir`` 151 * :hook:`pytest_report_collectionfinish(start_path: pathlib.Path) <pytest_report_collectionfinish>` as equivalent to ``startdir`` 152 153 The accompanying ``py.path.local`` based paths have been deprecated: plugins which manually invoke those hooks should only pass the new ``pathlib.Path`` arguments, and users should change their hook implementations to use the new ``pathlib.Path`` arguments. 154 155 .. note:: 156 The name of the :class:`~_pytest.nodes.Node` arguments and attributes, 157 :ref:`outlined above <node-ctor-fspath-deprecation>` (the new attribute 158 being ``path``) is **the opposite** of the situation for hooks (the old 159 argument being ``path``). 160 161 This is an unfortunate artifact due to historical reasons, which should be 162 resolved in future versions as we slowly get rid of the :pypi:`py` 163 dependency (see :issue:`9283` for a longer discussion). 164 165 Directly constructing internal classes 166 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 167 168 .. deprecated:: 7.0 169 170 Directly constructing the following classes is now deprecated: 171 172 - ``_pytest.mark.structures.Mark`` 173 - ``_pytest.mark.structures.MarkDecorator`` 174 - ``_pytest.mark.structures.MarkGenerator`` 175 - ``_pytest.python.Metafunc`` 176 - ``_pytest.runner.CallInfo`` 177 - ``_pytest._code.ExceptionInfo`` 178 - ``_pytest.config.argparsing.Parser`` 179 - ``_pytest.config.argparsing.OptionGroup`` 180 - ``_pytest.pytester.HookRecorder`` 181 182 These constructors have always been considered private, but now issue a deprecation warning, which may become a hard error in pytest 8. 183 184 .. _diamond-inheritance-deprecated: 185 186 Diamond inheritance between :class:`pytest.Collector` and :class:`pytest.Item` 187 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 188 189 .. deprecated:: 7.0 190 191 Defining a custom pytest node type which is both an :class:`~pytest.Item` and a :class:`~pytest.Collector` (e.g. :class:`~pytest.File`) now issues a warning. 192 It was never sanely supported and triggers hard to debug errors. 193 194 Some plugins providing linting/code analysis have been using this as a hack. 195 Instead, a separate collector node should be used, which collects the item. See 196 :ref:`non-python tests` for an example, as well as an `example pr fixing inheritance`_. 197 198 .. _example pr fixing inheritance: https://github.com/asmeurer/pytest-flakes/pull/40/files 199 200 201 .. _uncooperative-constructors-deprecated: 202 203 Constructors of custom :class:`~_pytest.nodes.Node` subclasses should take ``**kwargs`` 204 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 205 206 .. deprecated:: 7.0 207 208 If custom subclasses of nodes like :class:`pytest.Item` override the 209 ``__init__`` method, they should take ``**kwargs``. Thus, 210 211 .. code-block:: python 212 213 class CustomItem(pytest.Item): 214 def __init__(self, name, parent, additional_arg): 215 super().__init__(name, parent) 216 self.additional_arg = additional_arg 217 218 should be turned into: 219 220 .. code-block:: python 221 222 class CustomItem(pytest.Item): 223 def __init__(self, *, additional_arg, **kwargs): 224 super().__init__(**kwargs) 225 self.additional_arg = additional_arg 226 227 to avoid hard-coding the arguments pytest can pass to the superclass. 228 See :ref:`non-python tests` for a full example. 229 230 For cases without conflicts, no deprecation warning is emitted. For cases with 231 conflicts (such as :class:`pytest.File` now taking ``path`` instead of 232 ``fspath``, as :ref:`outlined above <node-ctor-fspath-deprecation>`), a 233 deprecation warning is now raised. 234 235 Applying a mark to a fixture function 236 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 237 238 .. deprecated:: 7.4 239 240 Applying a mark to a fixture function never had any effect, but it is a common user error. 241 242 .. code-block:: python 243 244 @pytest.mark.usefixtures("clean_database") 245 @pytest.fixture 246 def user() -> User: ... 247 248 Users expected in this case that the ``usefixtures`` mark would have its intended effect of using the ``clean_database`` fixture when ``user`` was invoked, when in fact it has no effect at all. 249 250 Now pytest will issue a warning when it encounters this problem, and will raise an error in the future versions. 251 252 253 Returning non-None value in test functions 254 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 255 256 .. deprecated:: 7.2 257 258 A :class:`pytest.PytestReturnNotNoneWarning` is now emitted if a test function returns something other than `None`. 259 260 This prevents a common mistake among beginners that expect that returning a `bool` would cause a test to pass or fail, for example: 261 262 .. code-block:: python 263 264 @pytest.mark.parametrize( 265 ["a", "b", "result"], 266 [ 267 [1, 2, 5], 268 [2, 3, 8], 269 [5, 3, 18], 270 ], 271 ) 272 def test_foo(a, b, result): 273 return foo(a, b) == result 274 275 Given that pytest ignores the return value, this might be surprising that it will never fail. 276 277 The proper fix is to change the `return` to an `assert`: 278 279 .. code-block:: python 280 281 @pytest.mark.parametrize( 282 ["a", "b", "result"], 283 [ 284 [1, 2, 5], 285 [2, 3, 8], 286 [5, 3, 18], 287 ], 288 ) 289 def test_foo(a, b, result): 290 assert foo(a, b) == result 291 292 293 The ``yield_fixture`` function/decorator 294 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 295 296 .. deprecated:: 6.2 297 298 ``pytest.yield_fixture`` is a deprecated alias for :func:`pytest.fixture`. 299 300 It has been so for a very long time, so can be search/replaced safely. 301 302 303 Removed Features and Breaking Changes 304 ------------------------------------- 305 306 As stated in our :ref:`backwards-compatibility` policy, deprecated features are removed only in major releases after 307 an appropriate period of deprecation has passed. 308 309 Some breaking changes which could not be deprecated are also listed. 310 311 .. _nose-deprecation: 312 313 Support for tests written for nose 314 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 315 316 .. deprecated:: 7.2 317 .. versionremoved:: 8.0 318 319 Support for running tests written for `nose <https://nose.readthedocs.io/en/latest/>`__ is now deprecated. 320 321 ``nose`` has been in maintenance mode-only for years, and maintaining the plugin is not trivial as it spills 322 over the code base (see :issue:`9886` for more details). 323 324 setup/teardown 325 ^^^^^^^^^^^^^^ 326 327 One thing that might catch users by surprise is that plain ``setup`` and ``teardown`` methods are not pytest native, 328 they are in fact part of the ``nose`` support. 329 330 331 .. code-block:: python 332 333 class Test: 334 def setup(self): 335 self.resource = make_resource() 336 337 def teardown(self): 338 self.resource.close() 339 340 def test_foo(self): ... 341 342 def test_bar(self): ... 343 344 345 346 Native pytest support uses ``setup_method`` and ``teardown_method`` (see :ref:`xunit-method-setup`), so the above should be changed to: 347 348 .. code-block:: python 349 350 class Test: 351 def setup_method(self): 352 self.resource = make_resource() 353 354 def teardown_method(self): 355 self.resource.close() 356 357 def test_foo(self): ... 358 359 def test_bar(self): ... 360 361 362 This is easy to do in an entire code base by doing a simple find/replace. 363 364 @with_setup 365 ^^^^^^^^^^^ 366 367 Code using `@with_setup <with-setup-nose>`_ such as this: 368 369 .. code-block:: python 370 371 from nose.tools import with_setup 372 373 374 def setup_some_resource(): ... 375 376 377 def teardown_some_resource(): ... 378 379 380 @with_setup(setup_some_resource, teardown_some_resource) 381 def test_foo(): ... 382 383 Will also need to be ported to a supported pytest style. One way to do it is using a fixture: 384 385 .. code-block:: python 386 387 import pytest 388 389 390 def setup_some_resource(): ... 391 392 393 def teardown_some_resource(): ... 394 395 396 @pytest.fixture 397 def some_resource(): 398 setup_some_resource() 399 yield 400 teardown_some_resource() 401 402 403 def test_foo(some_resource): ... 404 405 406 .. _`with-setup-nose`: https://nose.readthedocs.io/en/latest/testing_tools.html?highlight=with_setup#nose.tools.with_setup 407 408 409 The ``compat_co_firstlineno`` attribute 410 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 411 412 Nose inspects this attribute on function objects to allow overriding the function's inferred line number. 413 Pytest no longer respects this attribute. 414 415 416 417 Passing ``msg=`` to ``pytest.skip``, ``pytest.fail`` or ``pytest.exit`` 418 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 419 420 .. deprecated:: 7.0 421 .. versionremoved:: 8.0 422 423 Passing the keyword argument ``msg`` to :func:`pytest.skip`, :func:`pytest.fail` or :func:`pytest.exit` 424 is now deprecated and ``reason`` should be used instead. This change is to bring consistency between these 425 functions and the ``@pytest.mark.skip`` and ``@pytest.mark.xfail`` markers which already accept a ``reason`` argument. 426 427 .. code-block:: python 428 429 def test_fail_example(): 430 # old 431 pytest.fail(msg="foo") 432 # new 433 pytest.fail(reason="bar") 434 435 436 def test_skip_example(): 437 # old 438 pytest.skip(msg="foo") 439 # new 440 pytest.skip(reason="bar") 441 442 443 def test_exit_example(): 444 # old 445 pytest.exit(msg="foo") 446 # new 447 pytest.exit(reason="bar") 448 449 450 .. _instance-collector-deprecation: 451 452 The ``pytest.Instance`` collector 453 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 454 455 .. versionremoved:: 7.0 456 457 The ``pytest.Instance`` collector type has been removed. 458 459 Previously, Python test methods were collected as :class:`~pytest.Class` -> ``Instance`` -> :class:`~pytest.Function`. 460 Now :class:`~pytest.Class` collects the test methods directly. 461 462 Most plugins which reference ``Instance`` do so in order to ignore or skip it, 463 using a check such as ``if isinstance(node, Instance): return``. 464 Such plugins should simply remove consideration of ``Instance`` on pytest>=7. 465 However, to keep such uses working, a dummy type has been instanced in ``pytest.Instance`` and ``_pytest.python.Instance``, 466 and importing it emits a deprecation warning. This was removed in pytest 8. 467 468 469 Using ``pytest.warns(None)`` 470 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 471 472 .. deprecated:: 7.0 473 .. versionremoved:: 8.0 474 475 :func:`pytest.warns(None) <pytest.warns>` is now deprecated because it was frequently misused. 476 Its correct usage was checking that the code emits at least one warning of any type - like ``pytest.warns()`` 477 or ``pytest.warns(Warning)``. 478 479 See :ref:`warns use cases` for examples. 480 481 482 Backward compatibilities in ``Parser.addoption`` 483 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 484 485 .. deprecated:: 2.4 486 .. versionremoved:: 8.0 487 488 Several behaviors of :meth:`Parser.addoption <pytest.Parser.addoption>` are now 489 removed in pytest 8 (deprecated since pytest 2.4.0): 490 491 - ``parser.addoption(..., help=".. %default ..")`` - use ``%(default)s`` instead. 492 - ``parser.addoption(..., type="int/string/float/complex")`` - use ``type=int`` etc. instead. 493 494 495 The ``--strict`` command-line option 496 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 497 498 .. deprecated:: 6.2 499 .. versionremoved:: 8.0 500 501 The ``--strict`` command-line option has been deprecated in favor of ``--strict-markers``, which 502 better conveys what the option does. 503 504 We have plans to maybe in the future to reintroduce ``--strict`` and make it an encompassing 505 flag for all strictness related options (``--strict-markers`` and ``--strict-config`` 506 at the moment, more might be introduced in the future). 507 508 509 .. _cmdline-preparse-deprecated: 510 511 Implementing the ``pytest_cmdline_preparse`` hook 512 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 513 514 .. deprecated:: 7.0 515 .. versionremoved:: 8.0 516 517 Implementing the ``pytest_cmdline_preparse`` hook has been officially deprecated. 518 Implement the :hook:`pytest_load_initial_conftests` hook instead. 519 520 .. code-block:: python 521 522 def pytest_cmdline_preparse(config: Config, args: List[str]) -> None: ... 523 524 525 # becomes: 526 527 528 def pytest_load_initial_conftests( 529 early_config: Config, parser: Parser, args: List[str] 530 ) -> None: ... 531 532 533 Collection changes in pytest 8 534 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 535 536 Added a new :class:`pytest.Directory` base collection node, which all collector nodes for filesystem directories are expected to subclass. 537 This is analogous to the existing :class:`pytest.File` for file nodes. 538 539 Changed :class:`pytest.Package` to be a subclass of :class:`pytest.Directory`. 540 A ``Package`` represents a filesystem directory which is a Python package, 541 i.e. contains an ``__init__.py`` file. 542 543 :class:`pytest.Package` now only collects files in its own directory; previously it collected recursively. 544 Sub-directories are collected as sub-collector nodes, thus creating a collection tree which mirrors the filesystem hierarchy. 545 546 :attr:`session.name <pytest.Session.name>` is now ``""``; previously it was the rootdir directory name. 547 This matches :attr:`session.nodeid <_pytest.nodes.Node.nodeid>` which has always been `""`. 548 549 Added a new :class:`pytest.Dir` concrete collection node, a subclass of :class:`pytest.Directory`. 550 This node represents a filesystem directory, which is not a :class:`pytest.Package`, 551 i.e. does not contain an ``__init__.py`` file. 552 Similarly to ``Package``, it only collects the files in its own directory, 553 while collecting sub-directories as sub-collector nodes. 554 555 Files and directories are now collected in alphabetical order jointly, unless changed by a plugin. 556 Previously, files were collected before directories. 557 558 The collection tree now contains directories/packages up to the :ref:`rootdir <rootdir>`, 559 for initial arguments that are found within the rootdir. 560 For files outside the rootdir, only the immediate directory/package is collected -- 561 note however that collecting from outside the rootdir is discouraged. 562 563 As an example, given the following filesystem tree:: 564 565 myroot/ 566 pytest.ini 567 top/ 568 ├── aaa 569 │ └── test_aaa.py 570 ├── test_a.py 571 ├── test_b 572 │ ├── __init__.py 573 │ └── test_b.py 574 ├── test_c.py 575 └── zzz 576 ├── __init__.py 577 └── test_zzz.py 578 579 the collection tree, as shown by `pytest --collect-only top/` but with the otherwise-hidden :class:`~pytest.Session` node added for clarity, 580 is now the following:: 581 582 <Session> 583 <Dir myroot> 584 <Dir top> 585 <Dir aaa> 586 <Module test_aaa.py> 587 <Function test_it> 588 <Module test_a.py> 589 <Function test_it> 590 <Package test_b> 591 <Module test_b.py> 592 <Function test_it> 593 <Module test_c.py> 594 <Function test_it> 595 <Package zzz> 596 <Module test_zzz.py> 597 <Function test_it> 598 599 Previously, it was:: 600 601 <Session> 602 <Module top/test_a.py> 603 <Function test_it> 604 <Module top/test_c.py> 605 <Function test_it> 606 <Module top/aaa/test_aaa.py> 607 <Function test_it> 608 <Package test_b> 609 <Module test_b.py> 610 <Function test_it> 611 <Package zzz> 612 <Module test_zzz.py> 613 <Function test_it> 614 615 Code/plugins which rely on a specific shape of the collection tree might need to update. 616 617 618 :class:`pytest.Package` is no longer a :class:`pytest.Module` or :class:`pytest.File` 619 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 620 621 .. versionchanged:: 8.0 622 623 The ``Package`` collector node designates a Python package, that is, a directory with an `__init__.py` file. 624 Previously ``Package`` was a subtype of ``pytest.Module`` (which represents a single Python module), 625 the module being the `__init__.py` file. 626 This has been deemed a design mistake (see :issue:`11137` and :issue:`7777` for details). 627 628 The ``path`` property of ``Package`` nodes now points to the package directory instead of the ``__init__.py`` file. 629 630 Note that a ``Module`` node for ``__init__.py`` (which is not a ``Package``) may still exist, 631 if it is picked up during collection (e.g. if you configured :confval:`python_files` to include ``__init__.py`` files). 632 633 634 Collecting ``__init__.py`` files no longer collects package 635 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 636 637 .. versionremoved:: 8.0 638 639 Running `pytest pkg/__init__.py` now collects the `pkg/__init__.py` file (module) only. 640 Previously, it collected the entire `pkg` package, including other test files in the directory, but excluding tests in the `__init__.py` file itself 641 (unless :confval:`python_files` was changed to allow `__init__.py` file). 642 643 To collect the entire package, specify just the directory: `pytest pkg`. 644 645 646 The ``pytest.collect`` module 647 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 648 649 .. deprecated:: 6.0 650 .. versionremoved:: 7.0 651 652 The ``pytest.collect`` module is no longer part of the public API, all its names 653 should now be imported from ``pytest`` directly instead. 654 655 656 657 The ``pytest_warning_captured`` hook 658 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 659 660 .. deprecated:: 6.0 661 .. versionremoved:: 7.0 662 663 This hook has an `item` parameter which cannot be serialized by ``pytest-xdist``. 664 665 Use the ``pytest_warning_recorded`` hook instead, which replaces the ``item`` parameter 666 by a ``nodeid`` parameter. 667 668 669 670 The ``pytest._fillfuncargs`` function 671 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 672 673 .. deprecated:: 6.0 674 .. versionremoved:: 7.0 675 676 This function was kept for backward compatibility with an older plugin. 677 678 It's functionality is not meant to be used directly, but if you must replace 679 it, use `function._request._fillfixtures()` instead, though note this is not 680 a public API and may break in the future. 681 682 683 ``--no-print-logs`` command-line option 684 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 685 686 .. deprecated:: 5.4 687 .. versionremoved:: 6.0 688 689 690 The ``--no-print-logs`` option and ``log_print`` ini setting are removed. If 691 you used them, please use ``--show-capture`` instead. 692 693 A ``--show-capture`` command-line option was added in ``pytest 3.5.0`` which allows to specify how to 694 display captured output when tests fail: ``no``, ``stdout``, ``stderr``, ``log`` or ``all`` (the default). 695 696 697 .. _resultlog deprecated: 698 699 Result log (``--result-log``) 700 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 701 702 .. deprecated:: 4.0 703 .. versionremoved:: 6.0 704 705 The ``--result-log`` option produces a stream of test reports which can be 706 analysed at runtime, but it uses a custom format which requires users to implement their own 707 parser. 708 709 The `pytest-reportlog <https://github.com/pytest-dev/pytest-reportlog>`__ plugin provides a ``--report-log`` option, a more standard and extensible alternative, producing 710 one JSON object per-line, and should cover the same use cases. Please try it out and provide feedback. 711 712 The ``pytest-reportlog`` plugin might even be merged into the core 713 at some point, depending on the plans for the plugins and number of users using it. 714 715 ``pytest_collect_directory`` hook 716 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 717 718 .. versionremoved:: 6.0 719 720 The ``pytest_collect_directory`` hook has not worked properly for years (it was called 721 but the results were ignored). Users may consider using :hook:`pytest_collection_modifyitems` instead. 722 723 TerminalReporter.writer 724 ~~~~~~~~~~~~~~~~~~~~~~~ 725 726 .. versionremoved:: 6.0 727 728 The ``TerminalReporter.writer`` attribute has been deprecated and should no longer be used. This 729 was inadvertently exposed as part of the public API of that plugin and ties it too much 730 with ``py.io.TerminalWriter``. 731 732 Plugins that used ``TerminalReporter.writer`` directly should instead use ``TerminalReporter`` 733 methods that provide the same functionality. 734 735 .. _junit-family changed default value: 736 737 ``junit_family`` default value change to "xunit2" 738 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 739 740 .. versionchanged:: 6.0 741 742 The default value of ``junit_family`` option will change to ``xunit2`` in pytest 6.0, which 743 is an update of the old ``xunit1`` format and is supported by default in modern tools 744 that manipulate this type of file (for example, Jenkins, Azure Pipelines, etc.). 745 746 Users are recommended to try the new ``xunit2`` format and see if their tooling that consumes the JUnit 747 XML file supports it. 748 749 To use the new format, update your ``pytest.ini``: 750 751 .. code-block:: ini 752 753 [pytest] 754 junit_family=xunit2 755 756 If you discover that your tooling does not support the new format, and want to keep using the 757 legacy version, set the option to ``legacy`` instead: 758 759 .. code-block:: ini 760 761 [pytest] 762 junit_family=legacy 763 764 By using ``legacy`` you will keep using the legacy/xunit1 format when upgrading to 765 pytest 6.0, where the default format will be ``xunit2``. 766 767 In order to let users know about the transition, pytest will issue a warning in case 768 the ``--junit-xml`` option is given in the command line but ``junit_family`` is not explicitly 769 configured in ``pytest.ini``. 770 771 Services known to support the ``xunit2`` format: 772 773 * `Jenkins <https://www.jenkins.io/>`__ with the `JUnit <https://plugins.jenkins.io/junit>`__ plugin. 774 * `Azure Pipelines <https://azure.microsoft.com/en-us/services/devops/pipelines>`__. 775 776 Node Construction changed to ``Node.from_parent`` 777 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 778 779 .. versionchanged:: 6.0 780 781 The construction of nodes now should use the named constructor ``from_parent``. 782 This limitation in api surface intends to enable better/simpler refactoring of the collection tree. 783 784 This means that instead of :code:`MyItem(name="foo", parent=collector, obj=42)` 785 one now has to invoke :code:`MyItem.from_parent(collector, name="foo")`. 786 787 Plugins that wish to support older versions of pytest and suppress the warning can use 788 `hasattr` to check if `from_parent` exists in that version: 789 790 .. code-block:: python 791 792 def pytest_pycollect_makeitem(collector, name, obj): 793 if hasattr(MyItem, "from_parent"): 794 item = MyItem.from_parent(collector, name="foo") 795 item.obj = 42 796 return item 797 else: 798 return MyItem(name="foo", parent=collector, obj=42) 799 800 Note that ``from_parent`` should only be called with keyword arguments for the parameters. 801 802 803 ``pytest.fixture`` arguments are keyword only 804 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 805 806 .. versionremoved:: 6.0 807 808 Passing arguments to pytest.fixture() as positional arguments has been removed - pass them by keyword instead. 809 810 ``funcargnames`` alias for ``fixturenames`` 811 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 812 813 .. versionremoved:: 6.0 814 815 The ``FixtureRequest``, ``Metafunc``, and ``Function`` classes track the names of 816 their associated fixtures, with the aptly-named ``fixturenames`` attribute. 817 818 Prior to pytest 2.3, this attribute was named ``funcargnames``, and we have kept 819 that as an alias since. It is finally due for removal, as it is often confusing 820 in places where we or plugin authors must distinguish between fixture names and 821 names supplied by non-fixture things such as ``pytest.mark.parametrize``. 822 823 824 .. _pytest.config global deprecated: 825 826 ``pytest.config`` global 827 ~~~~~~~~~~~~~~~~~~~~~~~~ 828 829 .. versionremoved:: 5.0 830 831 The ``pytest.config`` global object is deprecated. Instead use 832 ``request.config`` (via the ``request`` fixture) or if you are a plugin author 833 use the ``pytest_configure(config)`` hook. Note that many hooks can also access 834 the ``config`` object indirectly, through ``session.config`` or ``item.config`` for example. 835 836 837 .. _`raises message deprecated`: 838 839 ``"message"`` parameter of ``pytest.raises`` 840 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 841 842 .. versionremoved:: 5.0 843 844 It is a common mistake to think this parameter will match the exception message, while in fact 845 it only serves to provide a custom message in case the ``pytest.raises`` check fails. To prevent 846 users from making this mistake, and because it is believed to be little used, pytest is 847 deprecating it without providing an alternative for the moment. 848 849 If you have a valid use case for this parameter, consider that to obtain the same results 850 you can just call ``pytest.fail`` manually at the end of the ``with`` statement. 851 852 For example: 853 854 .. code-block:: python 855 856 with pytest.raises(TimeoutError, message="Client got unexpected message"): 857 wait_for(websocket.recv(), 0.5) 858 859 860 Becomes: 861 862 .. code-block:: python 863 864 with pytest.raises(TimeoutError): 865 wait_for(websocket.recv(), 0.5) 866 pytest.fail("Client got unexpected message") 867 868 869 If you still have concerns about this deprecation and future removal, please comment on 870 :issue:`3974`. 871 872 873 .. _raises-warns-exec: 874 875 ``raises`` / ``warns`` with a string as the second argument 876 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 877 878 .. versionremoved:: 5.0 879 880 Use the context manager form of these instead. When necessary, invoke ``exec`` 881 directly. 882 883 Example: 884 885 .. code-block:: python 886 887 pytest.raises(ZeroDivisionError, "1 / 0") 888 pytest.raises(SyntaxError, "a $ b") 889 890 pytest.warns(DeprecationWarning, "my_function()") 891 pytest.warns(SyntaxWarning, "assert(1, 2)") 892 893 Becomes: 894 895 .. code-block:: python 896 897 with pytest.raises(ZeroDivisionError): 898 1 / 0 899 with pytest.raises(SyntaxError): 900 exec("a $ b") # exec is required for invalid syntax 901 902 with pytest.warns(DeprecationWarning): 903 my_function() 904 with pytest.warns(SyntaxWarning): 905 exec("assert(1, 2)") # exec is used to avoid a top-level warning 906 907 908 909 910 Using ``Class`` in custom Collectors 911 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 912 913 .. versionremoved:: 4.0 914 915 Using objects named ``"Class"`` as a way to customize the type of nodes that are collected in ``Collector`` 916 subclasses has been deprecated. Users instead should use ``pytest_pycollect_makeitem`` to customize node types during 917 collection. 918 919 This issue should affect only advanced plugins who create new collection types, so if you see this warning 920 message please contact the authors so they can change the code. 921 922 923 .. _marks in pytest.parametrize deprecated: 924 925 marks in ``pytest.mark.parametrize`` 926 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 927 928 .. versionremoved:: 4.0 929 930 Applying marks to values of a ``pytest.mark.parametrize`` call is now deprecated. For example: 931 932 .. code-block:: python 933 934 @pytest.mark.parametrize( 935 "a, b", 936 [ 937 (3, 9), 938 pytest.mark.xfail(reason="flaky")(6, 36), 939 (10, 100), 940 (20, 200), 941 (40, 400), 942 (50, 500), 943 ], 944 ) 945 def test_foo(a, b): ... 946 947 This code applies the ``pytest.mark.xfail(reason="flaky")`` mark to the ``(6, 36)`` value of the above parametrization 948 call. 949 950 This was considered hard to read and understand, and also its implementation presented problems to the code preventing 951 further internal improvements in the marks architecture. 952 953 To update the code, use ``pytest.param``: 954 955 .. code-block:: python 956 957 @pytest.mark.parametrize( 958 "a, b", 959 [ 960 (3, 9), 961 pytest.param(6, 36, marks=pytest.mark.xfail(reason="flaky")), 962 (10, 100), 963 (20, 200), 964 (40, 400), 965 (50, 500), 966 ], 967 ) 968 def test_foo(a, b): ... 969 970 971 .. _pytest_funcarg__ prefix deprecated: 972 973 ``pytest_funcarg__`` prefix 974 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 975 976 .. versionremoved:: 4.0 977 978 In very early pytest versions fixtures could be defined using the ``pytest_funcarg__`` prefix: 979 980 .. code-block:: python 981 982 def pytest_funcarg__data(): 983 return SomeData() 984 985 Switch over to the ``@pytest.fixture`` decorator: 986 987 .. code-block:: python 988 989 @pytest.fixture 990 def data(): 991 return SomeData() 992 993 994 995 [pytest] section in setup.cfg files 996 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 997 998 .. versionremoved:: 4.0 999 1000 ``[pytest]`` sections in ``setup.cfg`` files should now be named ``[tool:pytest]`` 1001 to avoid conflicts with other distutils commands. 1002 1003 1004 .. _metafunc.addcall deprecated: 1005 1006 Metafunc.addcall 1007 ~~~~~~~~~~~~~~~~ 1008 1009 .. versionremoved:: 4.0 1010 1011 ``Metafunc.addcall`` was a precursor to the current parametrized mechanism. Users should use 1012 :meth:`pytest.Metafunc.parametrize` instead. 1013 1014 Example: 1015 1016 .. code-block:: python 1017 1018 def pytest_generate_tests(metafunc): 1019 metafunc.addcall({"i": 1}, id="1") 1020 metafunc.addcall({"i": 2}, id="2") 1021 1022 Becomes: 1023 1024 .. code-block:: python 1025 1026 def pytest_generate_tests(metafunc): 1027 metafunc.parametrize("i", [1, 2], ids=["1", "2"]) 1028 1029 1030 .. _cached_setup deprecated: 1031 1032 ``cached_setup`` 1033 ~~~~~~~~~~~~~~~~ 1034 1035 .. versionremoved:: 4.0 1036 1037 ``request.cached_setup`` was the precursor of the setup/teardown mechanism available to fixtures. 1038 1039 Example: 1040 1041 .. code-block:: python 1042 1043 @pytest.fixture 1044 def db_session(): 1045 return request.cached_setup( 1046 setup=Session.create, teardown=lambda session: session.close(), scope="module" 1047 ) 1048 1049 This should be updated to make use of standard fixture mechanisms: 1050 1051 .. code-block:: python 1052 1053 @pytest.fixture(scope="module") 1054 def db_session(): 1055 session = Session.create() 1056 yield session 1057 session.close() 1058 1059 1060 You can consult :std:doc:`funcarg comparison section in the docs <funcarg_compare>` for 1061 more information. 1062 1063 1064 .. _pytest_plugins in non-top-level conftest files deprecated: 1065 1066 pytest_plugins in non-top-level conftest files 1067 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1068 1069 .. versionremoved:: 4.0 1070 1071 Defining :globalvar:`pytest_plugins` is now deprecated in non-top-level conftest.py 1072 files because they will activate referenced plugins *globally*, which is surprising because for all other pytest 1073 features ``conftest.py`` files are only *active* for tests at or below it. 1074 1075 1076 .. _config.warn and node.warn deprecated: 1077 1078 ``Config.warn`` and ``Node.warn`` 1079 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1080 1081 .. versionremoved:: 4.0 1082 1083 Those methods were part of the internal pytest warnings system, but since ``3.8`` pytest is using the builtin warning 1084 system for its own warnings, so those two functions are now deprecated. 1085 1086 ``Config.warn`` should be replaced by calls to the standard ``warnings.warn``, example: 1087 1088 .. code-block:: python 1089 1090 config.warn("C1", "some warning") 1091 1092 Becomes: 1093 1094 .. code-block:: python 1095 1096 warnings.warn(pytest.PytestWarning("some warning")) 1097 1098 ``Node.warn`` now supports two signatures: 1099 1100 * ``node.warn(PytestWarning("some message"))``: is now the **recommended** way to call this function. 1101 The warning instance must be a PytestWarning or subclass. 1102 1103 * ``node.warn("CI", "some message")``: this code/message form has been **removed** and should be converted to the warning instance form above. 1104 1105 .. _record_xml_property deprecated: 1106 1107 record_xml_property 1108 ~~~~~~~~~~~~~~~~~~~ 1109 1110 .. versionremoved:: 4.0 1111 1112 The ``record_xml_property`` fixture is now deprecated in favor of the more generic ``record_property``, which 1113 can be used by other consumers (for example ``pytest-html``) to obtain custom information about the test run. 1114 1115 This is just a matter of renaming the fixture as the API is the same: 1116 1117 .. code-block:: python 1118 1119 def test_foo(record_xml_property): ... 1120 1121 Change to: 1122 1123 .. code-block:: python 1124 1125 def test_foo(record_property): ... 1126 1127 1128 .. _passing command-line string to pytest.main deprecated: 1129 1130 Passing command-line string to ``pytest.main()`` 1131 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1132 1133 .. versionremoved:: 4.0 1134 1135 Passing a command-line string to ``pytest.main()`` is deprecated: 1136 1137 .. code-block:: python 1138 1139 pytest.main("-v -s") 1140 1141 Pass a list instead: 1142 1143 .. code-block:: python 1144 1145 pytest.main(["-v", "-s"]) 1146 1147 1148 By passing a string, users expect that pytest will interpret that command-line using the shell rules they are working 1149 on (for example ``bash`` or ``Powershell``), but this is very hard/impossible to do in a portable way. 1150 1151 1152 .. _calling fixtures directly deprecated: 1153 1154 Calling fixtures directly 1155 ~~~~~~~~~~~~~~~~~~~~~~~~~ 1156 1157 .. versionremoved:: 4.0 1158 1159 Calling a fixture function directly, as opposed to request them in a test function, is deprecated. 1160 1161 For example: 1162 1163 .. code-block:: python 1164 1165 @pytest.fixture 1166 def cell(): 1167 return ... 1168 1169 1170 @pytest.fixture 1171 def full_cell(): 1172 cell = cell() 1173 cell.make_full() 1174 return cell 1175 1176 This is a great source of confusion to new users, which will often call the fixture functions and request them from test functions interchangeably, which breaks the fixture resolution model. 1177 1178 In those cases just request the function directly in the dependent fixture: 1179 1180 .. code-block:: python 1181 1182 @pytest.fixture 1183 def cell(): 1184 return ... 1185 1186 1187 @pytest.fixture 1188 def full_cell(cell): 1189 cell.make_full() 1190 return cell 1191 1192 Alternatively if the fixture function is called multiple times inside a test (making it hard to apply the above pattern) or 1193 if you would like to make minimal changes to the code, you can create a fixture which calls the original function together 1194 with the ``name`` parameter: 1195 1196 .. code-block:: python 1197 1198 def cell(): 1199 return ... 1200 1201 1202 @pytest.fixture(name="cell") 1203 def cell_fixture(): 1204 return cell() 1205 1206 1207 .. _yield tests deprecated: 1208 1209 ``yield`` tests 1210 ~~~~~~~~~~~~~~~ 1211 1212 .. versionremoved:: 4.0 1213 1214 pytest supported ``yield``-style tests, where a test function actually ``yield`` functions and values 1215 that are then turned into proper test methods. Example: 1216 1217 .. code-block:: python 1218 1219 def check(x, y): 1220 assert x**x == y 1221 1222 1223 def test_squared(): 1224 yield check, 2, 4 1225 yield check, 3, 9 1226 1227 This would result into two actual test functions being generated. 1228 1229 This form of test function doesn't support fixtures properly, and users should switch to ``pytest.mark.parametrize``: 1230 1231 .. code-block:: python 1232 1233 @pytest.mark.parametrize("x, y", [(2, 4), (3, 9)]) 1234 def test_squared(x, y): 1235 assert x**x == y 1236 1237 .. _internal classes accessed through node deprecated: 1238 1239 Internal classes accessed through ``Node`` 1240 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1241 1242 .. versionremoved:: 4.0 1243 1244 Access of ``Module``, ``Function``, ``Class``, ``Instance``, ``File`` and ``Item`` through ``Node`` instances now issue 1245 this warning: 1246 1247 .. code-block:: text 1248 1249 usage of Function.Module is deprecated, please use pytest.Module instead 1250 1251 Users should just ``import pytest`` and access those objects using the ``pytest`` module. 1252 1253 This has been documented as deprecated for years, but only now we are actually emitting deprecation warnings. 1254 1255 ``Node.get_marker`` 1256 ~~~~~~~~~~~~~~~~~~~ 1257 1258 .. versionremoved:: 4.0 1259 1260 As part of a large :ref:`marker-revamp`, ``_pytest.nodes.Node.get_marker`` is removed. See 1261 :ref:`the documentation <update marker code>` on tips on how to update your code. 1262 1263 1264 ``somefunction.markname`` 1265 ~~~~~~~~~~~~~~~~~~~~~~~~~ 1266 1267 .. versionremoved:: 4.0 1268 1269 As part of a large :ref:`marker-revamp` we already deprecated using ``MarkInfo`` 1270 the only correct way to get markers of an element is via ``node.iter_markers(name)``. 1271 1272 1273 .. _pytest.namespace deprecated: 1274 1275 ``pytest_namespace`` 1276 ~~~~~~~~~~~~~~~~~~~~ 1277 1278 .. versionremoved:: 4.0 1279 1280 This hook is deprecated because it greatly complicates the pytest internals regarding configuration and initialization, making some 1281 bug fixes and refactorings impossible. 1282 1283 Example of usage: 1284 1285 .. code-block:: python 1286 1287 class MySymbol: ... 1288 1289 1290 def pytest_namespace(): 1291 return {"my_symbol": MySymbol()} 1292 1293 1294 Plugin authors relying on this hook should instead require that users now import the plugin modules directly (with an appropriate public API). 1295 1296 As a stopgap measure, plugin authors may still inject their names into pytest's namespace, usually during ``pytest_configure``: 1297 1298 .. code-block:: python 1299 1300 import pytest 1301 1302 1303 def pytest_configure(): 1304 pytest.my_symbol = MySymbol()