diff --git a/changelog/15127.doc.rst b/changelog/15127.doc.rst new file mode 100644 index 00000000000..e3559287d36 --- /dev/null +++ b/changelog/15127.doc.rst @@ -0,0 +1 @@ +Added guidance on typing yield fixtures, including annotating fixture functions with their generator type and fixture consumers with the yielded value type. diff --git a/doc/en/explanation/types.rst b/doc/en/explanation/types.rst index 827a2bf02b6..d34640e5b27 100644 --- a/doc/en/explanation/types.rst +++ b/doc/en/explanation/types.rst @@ -81,6 +81,27 @@ The same logic applies when typing fixture functions which receive other fixture def mock_env_user(monkeypatch: pytest.MonkeyPatch) -> None: monkeypatch.setenv("USER", "TestingUser") +For a fixture that uses ``yield``, annotate the fixture function with the +type of its generator. Annotate a test or another fixture that requests it +with the type of the value yielded: + +.. code-block:: python + + from typing import Generator + + import pytest + + + @pytest.fixture + def sample_fixture_yield() -> Generator[int, None, None]: + yield 38 + + + def test_sample_fixture_yield(sample_fixture_yield: int) -> None: + assert sample_fixture_yield == 38 + +The test receives the yielded ``int``, not the generator object. See :ref:`How to use fixtures ` for more information about +``yield`` fixtures and teardown. Conclusion ----------