diff --git a/changelog/7389.trivial.rst b/changelog/7389.trivial.rst new file mode 100644 index 00000000000..00cfe92bcee --- /dev/null +++ b/changelog/7389.trivial.rst @@ -0,0 +1 @@ +Fixture scope ``package`` is no longer considered experimental. diff --git a/doc/en/fixture.rst b/doc/en/fixture.rst index a4e262c2fa3..883cdcd4390 100644 --- a/doc/en/fixture.rst +++ b/doc/en/fixture.rst @@ -244,8 +244,8 @@ and `pytest-datafiles `__. .. _smtpshared: -Scope: sharing a fixture instance across tests in a class, module or session ----------------------------------------------------------------------------- +Scope: sharing fixtures across classes, modules, packages or session +-------------------------------------------------------------------- .. regendoc:wipe @@ -356,29 +356,23 @@ instance, you can simply declare it: # all tests needing it ... -Finally, the ``class`` scope will invoke the fixture once per test *class*. -.. note:: - - Pytest will only cache one instance of a fixture at a time. - This means that when using a parametrized fixture, pytest may invoke a fixture more than once in the given scope. - - -``package`` scope (experimental) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Fixture scopes +^^^^^^^^^^^^^^ +Fixtures are created when first requested by a test, and are destroyed based on their ``scope``: +* ``function``: the default scope, the fixture is destroyed at the end of the test. +* ``class``: the fixture is destroyed during teardown of the last test in the class. +* ``module``: the fixture is destroyed during teardown of the last test in the module. +* ``package``: the fixture is destroyed during teardown of the last test in the package. +* ``session``: the fixture is destroyed at the end of the test session. -In pytest 3.7 the ``package`` scope has been introduced. Package-scoped fixtures -are finalized when the last test of a *package* finishes. - -.. warning:: - This functionality is considered **experimental** and may be removed in future - versions if hidden corner-cases or serious problems with this functionality - are discovered after it gets more usage in the wild. - - Use this new feature sparingly and please make sure to report any issues you find. +.. note:: + Pytest only caches one instance of a fixture at a time, which + means that when using a parametrized fixture, pytest may invoke a fixture more than once in + the given scope. .. _dynamic scope: diff --git a/src/_pytest/fixtures.py b/src/_pytest/fixtures.py index 9423df7e4c3..4aebdb95155 100644 --- a/src/_pytest/fixtures.py +++ b/src/_pytest/fixtures.py @@ -1274,8 +1274,7 @@ def fixture( # noqa: F811 :arg scope: the scope for which this fixture is shared, one of ``"function"`` (default), ``"class"``, ``"module"``, - ``"package"`` or ``"session"`` (``"package"`` is considered **experimental** - at this time). + ``"package"`` or ``"session"``. This parameter may also be a callable which receives ``(fixture_name, config)`` as parameters, and must return a ``str`` with one of the values mentioned above.