pytest config intelligence¶
pytest config intelligence turns pytest's configuration files into schema-aware editing surfaces: ini-option completion, validation of option names and value types, and warnings when pytest ignores a configuration entirely.
The feature is active in these files and tables only:
| File | Table / section | Values | Since |
|---|---|---|---|
pytest.ini | [pytest] | INI-style values | always |
.pytest.ini | [pytest] when present; the file itself on pytest 9+ | INI-style values | pytest 9.0 for empty files |
pytest.toml, .pytest.toml | [pytest] | native TOML types | pytest 9.0 |
pyproject.toml | [tool.pytest] | native TOML types | pytest 9.0 |
pyproject.toml | [tool.pytest.ini_options] | INI-style values | pytest 6.0 |
The option set is resolved for the interpreter of the configuration file's module, using installed pytest metadata, then a background interpreter probe, then the winning configuration's minversion. If the version is unknown, completion uses the newest bundled catalog. Runtime plugin options are isolated by interpreter and working directory, so nested configurations cannot replace another configuration's plugin options. Runtime catalogs refresh after pytest configuration edits, including unsaved committed edits, and when the detected interpreter version changes. A configuration's minversion is a lower bound, not proof of the installed version; unresolved long-string IDs remain conservative. Explicit interpreter refreshes retain authoritative probe results instead of reverting to stale package metadata. Changing minversion also refreshes version-dependent fixture bindings.
On pytest 9.2 and newer, top-level scalar or array options in pytest.toml or .pytest.toml are reported when the file has no semantic pytest table. Inline and dotted TOML table declarations are accepted; unrelated dictionaries do not trigger this warning. Move stray options under [pytest]. This warning stays silent for older or unknown pytest versions.
Completion¶
Invoke completion on a key position inside a recognised table or [pytest] section to complete ini-option names. Each lookup shows the option kind as tail text and the pytest help string as type text; keys already present in the table or section are filtered out. Allowed string values are also completed in value positions, including pytest 9.2's parametrize_long_str_id_strategy (short, sha256, legacy, disallow).
Unknown or unavailable option keys¶
[tool.pytest.ini_options]
testpath = ["tests"] # Unknown pytest ini-option 'testpath' → quick fix: Rename to 'testpaths'
Options that exist only in a newer pytest are reported against the detected version, for example 'consider_namespace_packages' requires pytest >= 8.0 (project uses 7.0). Unknown keys are not reported while the runtime catalog is still unresolved and plugin-contributed options could be missing.
Value type mismatches¶
Value shapes are validated per option kind and per dialect. In native-TOML tables a list option needs a real array; in [tool.pytest.ini_options] a whitespace-separated string is also accepted. INI-mode string options accept scalar values converted by pytest, such as faulthandler_timeout = 0.5. Integer alternatives accept Python-style decimal strings, including surrounding whitespace and digit separators.
[tool.pytest.ini_options]
xfail_strict = "true" # 'xfail_strict' expects a boolean value → quick fix: Convert to true
testpaths = "tests src" # accepted (INI-style value)
[tool.pytest]
testpaths = "tests src" # 'testpaths' expects an array of strings → quick fix: ["tests", "src"]
On pytest 9.2 or newer, invalid enum strings such as junit_family = "bogus" in TOML or junit_family = bogus in an INI pytest section are reported with replacement quick-fixes for the supported values. These warnings stay silent when the version is unknown or older than 9.2. The 9.2 catalog also accepts native numbers for logging levels, truncation limits, verbosity, retention count, warning limits and faulthandler timeout, and native booleans for log_auto_indent. Marker content stays with mark-completion; filterwarnings categories are linked below.
Filterwarnings categories¶
Category tokens in filterwarnings values (action:message:category[:module[:lineno]]) resolve like Python @pytest.mark.filterwarnings(...) strings. ⌘B / Ctrl+B on DeprecationWarning or package.CustomWarning jumps to the class; unknown hard categories stay unresolved.
[pytest]
filterwarnings =
error::Depreca<caret>tionWarning # Go to Declaration → builtins.DeprecationWarning
Missing configured directories¶
Non-glob directory values for norecursedirs, pythonpath, cache_dir, and confcutdir are highlighted when the path does not exist. Create-directory is offered for every key except norecursedirs. testpaths stays with the dedicated missing-testdir inspection.
[pytest]
norecursedirs = missing_dir # highlighted, no create-directory
pythonpath = src # highlighted + Create directory when missing
Glob tokens (*, ?, [, {) are skipped.
Configuration precedence¶
pytest picks exactly one configuration file and never merges options across files. Within the same directory the order is scoped to the detected pytest version: file forms and tables that version does not understand are not candidates.
| Priority | File | Counts as configuration when | Since |
|---|---|---|---|
| 1 | pytest.toml | it exists, even when empty | pytest 9.0 |
| 2 | .pytest.toml | it exists, even when empty | pytest 9.0 |
| 3 | pytest.ini | it exists, even when empty | always |
| 4 | .pytest.ini | it exists on pytest 9+, or declares [pytest] on older pytest | pytest 9.0 for empty files |
| 5 | pyproject.toml | it declares [tool.pytest] | pytest 9.0 |
| 5 | pyproject.toml | it declares [tool.pytest.ini_options] | pytest 6.0 |
| 6 | tox.ini | it declares a [pytest] section | always |
| 7 | setup.cfg | it declares a [tool:pytest] section | always |
A shadowed configuration is reported on its table header or INI section header:
# pyproject.toml, next to a pytest.ini
[tool.pytest.ini_options] # pytest ignores this configuration: 'pytest.ini' in the same directory takes precedence
# pytest.ini, next to a pytest.toml, on pytest 9.0
[pytest] # pytest ignores this configuration: 'pytest.toml' in the same directory takes precedence
On pytest 8.0 the same pytest.toml is not a candidate, so pytest.ini is not reported as shadowed.
Inside pyproject.toml, [tool.pytest] wins over [tool.pytest.ini_options] only on pytest 9.0+. Because the report only considers files in the same directory, it never guesses at pytest's rootdir resolution.
pytest 9 gating¶
pytest.toml, .pytest.toml and [tool.pytest] were introduced in pytest 9.0. On an older detected version their table header is reported, for example 'pytest.toml' requires pytest >= 9.0 (project uses 7.0).
Notes¶
- The feature is gated by the pytest config intelligence setting under Settings | BetterPy | Testing (Pytest) | Configuration Files.
- All intelligence works offline from the bundled catalog; the interpreter probe only enriches it and runs in the background.
- Versions and runtime catalogs are cached per SDK, not per project. A file without a module SDK uses the Python interpreter resolver's fallback order. Unknown versions never enable new 9.2 warnings.
- Copy Diagnostic Data shows the cached pytest version and its source, and requests a refresh. Use it after external
pipchanges if the IDE has not yet received a package-refresh event.