From 027d2336b8d6de145e14a0eaaedacd04dca21c08 Mon Sep 17 00:00:00 2001 From: Bruno Oliveira Date: Thu, 5 Jul 2018 21:54:02 -0300 Subject: [PATCH] Add minimal docs for package-scoped fixtures (experimental) --- changelog/2283.feature | 2 +- doc/en/fixture.rst | 16 ++++++++++++++++ src/_pytest/fixtures.py | 27 +++++++++++++++++---------- 3 files changed, 34 insertions(+), 11 deletions(-) diff --git a/changelog/2283.feature b/changelog/2283.feature index 6f8019000..9a8f2c4c9 100644 --- a/changelog/2283.feature +++ b/changelog/2283.feature @@ -1 +1 @@ -Pytest now supports package-level fixtures. +New ``package`` fixture scope: fixtures are finalized when the last test of a *package* finishes. This feature is considered **experimental**, so use it sparingly. diff --git a/doc/en/fixture.rst b/doc/en/fixture.rst index e07d00eaa..aca0e456f 100644 --- a/doc/en/fixture.rst +++ b/doc/en/fixture.rst @@ -258,6 +258,22 @@ instance, you can simply declare it: Finally, the ``class`` scope will invoke the fixture once per test *class*. +``package`` scope (experimental) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 3.7 + +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. + + Higher-scoped fixtures are instantiated first --------------------------------------------- diff --git a/src/_pytest/fixtures.py b/src/_pytest/fixtures.py index a5bbdbec9..6f1a0880d 100644 --- a/src/_pytest/fixtures.py +++ b/src/_pytest/fixtures.py @@ -960,16 +960,27 @@ class FixtureFunctionMarker(object): def fixture(scope="function", params=None, autouse=False, ids=None, name=None): """Decorator to mark a fixture factory function. - This decorator can be used (with or without parameters) to define a - fixture function. The name of the fixture function can later be - referenced to cause its invocation ahead of running tests: test - modules or classes can use the pytest.mark.usefixtures(fixturename) - marker. Test functions can directly use fixture names as input + This decorator can be used, with or without parameters, to define a + fixture function. + + The name of the fixture function can later be referenced to cause its + invocation ahead of running tests: test + modules or classes can use the ``pytest.mark.usefixtures(fixturename)`` + marker. + + Test functions can directly use fixture names as input arguments in which case the fixture instance returned from the fixture function will be injected. + Fixtures can provide their values to test functions using ``return`` or ``yield`` + statements. When using ``yield`` the code block after the ``yield`` statement is executed + as teardown code regardless of the test outcome, and must yield exactly once. + :arg scope: the scope for which this fixture is shared, one of - "function" (default), "class", "module" or "session". + ``"function"`` (default), ``"class"``, ``"module"``, + ``"package"`` or ``"session"``. + + ``"package"`` is considered **experimental** at this time. :arg params: an optional list of parameters which will cause multiple invocations of the fixture function and all of the tests @@ -990,10 +1001,6 @@ def fixture(scope="function", params=None, autouse=False, ids=None, name=None): to resolve this is to name the decorated function ``fixture_`` and then use ``@pytest.fixture(name='')``. - - Fixtures can optionally provide their values to test functions using a ``yield`` statement, - instead of ``return``. In this case, the code block after the ``yield`` statement is executed - as teardown code regardless of the test outcome. A fixture function must yield exactly once. """ if callable(scope) and params is None and autouse is False: # direct decoration