pytest-dev / pytest-dev/pytest

Improve documentation around conftest-files and importing of fixtures

Open
#13,148 2 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

type: docs
Dominant language
Python
Stars
14.5k
Forks
3.4k
Avg merge
2d 9h
Merged PRs (30d)
35

Description

Prompted by #13144, I looked at the fixtures documentation of pytest again, and I feel like we're not doing a very good job at explaining a quite basic concept: How to use conftest.py files on a basic level, and why fixtures shouldn't be imported. I'd even go as far as recommending a rule of thumb like "never import anything from a test file or from a conftest.py, unless it's for type annotations".

The section about scope could then perhaps have a note linking to that, to avoid confusion when something like in #13144 happens.

What we have so far:

How to use fixtures mentions conftest.py in passing, while actually talking about the scope argument (which seems extra confusing, even more so with the title of "scope: sharing fixtures", while scope is about the caching/lifetime and not the visibility!):

The next example puts the fixture function into a separate conftest.py file so that tests from multiple test modules in the directory can access the fixture function: [...]

In the same document, under Using fixtures from other projects, there is a note (emphasis mine):

Sometimes users will import fixtures from other projects for use, however this is not recommended: importing fixtures into a module will register them in pytest as defined in that module.

This has minor consequences, such as appearing multiple times in pytest --help, but it is not recommended because this behavior might change/stop working in future versions.

While the note is aimed at importing things from other non-test code, as seen in #13144, doing something very similar in the current's project test code can introduce confusion on why a fixture with scope="session" that's imported somewhere else is run twice.

Finally, only in the fixtures reference we have a section about conftest.py, which already goes into quite some technical detail with how nesting of multiple conftest.py works.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the “How to use fixtures” and “Using fixtures from other projects” sections in docs.pytest.org/en/stable/how-to/fixtures.html, then compare them with the conftest.py section in the fixtures reference. Clarify basic conftest.py usage, distinguish fixture visibility from scope and caching, explain why fixtures should not be imported, and link the relevant guidance from the scope discussion.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation, testing-qa
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.