pytest-dev / pytest-dev/pytest
Improve documentation around conftest-files and importing of fixtures
Nobody has claimed this yet.
- 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.pyfile 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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