Skip to content

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).

[tool.pytest.ini_options]
test<caret>          # testpaths (paths)  directories to search for tests …
[pytest]
test<caret>          # testpaths (paths)  directories to search for tests …

Unknown or unavailable option keys

[tool.pytest.ini_options]
testpath = ["tests"]   # Unknown pytest ini-option 'testpath'  → quick fix: Rename to 'testpaths'
[pytest]
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
[tool.pytest.ini_options]
filterwarnings = [
    "ignore::pkg.Custom<caret>Warning",
]

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
[tool.pytest.ini_options]
cache_dir = ".missing-cache"
confcutdir = "missing_conf"

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 pip changes if the IDE has not yet received a package-refresh event.