[Dhruv-Sharma29]

Problem

A module-level pytest.importorskip() currently stops collection when an optional dependency is unavailable. Individual tests and parametrizations behind that gate are absent from --collect-only and per-test reports.

Proposed behavior

Add the opt-in defer=True parameter:

dependency = pytest.importorskip("optional_dependency", defer=True)

During test-module or conftest import, record the missing or too-old dependency as a scoped gate and return an unavailable-module stand-in. Allow collection to finish, then skip each affected item at setup before fixtures execute. Preserve the original reason and gate location in skip reports. A conftest gate applies only to tests under that directory.

If eager dependency use or a subsequent exception prevents completing the gated import, fall back to the original module-level skip. Inside tests or fixtures, skip immediately as before. Calls without defer=True keep the existing behavior.

Closes #15267

Implementation

• Use an import context variable and per-config stash to keep gates scoped to the active import and test run.
• Integrate the context with test-module and conftest imports, and check gates during setup.
• Add ten regression cases, API documentation, a feature changelog entry, and an AUTHORS entry.

Validation

• Full suite: 4,728 passed, 50 skipped, 15 xfailed, 5 xpassed; no failures (Python 3.13.15, two workers).
• Existing skipping/conftest/collection tests: 267 passed, 4 skipped, 1 xfailed.
• After the final correction preserving immediate-skip call-site reporting: all 105 feature and skipping tests passed.
• Pinned Ruff 0.17.3 lint and formatting checks passed; git diff --check passed.

Design review

This is a draft implementation of the proposal, pending agreement on the public API and fallback semantics. The rest of a gated module executes, so import-time side effects are possible. Successful deferred collection changes skip counts from one per module to one per test. The stand-in is neither a real module nor None.

This does not introduce the optional companion requires_import marker. The documentation's versionadded entry assumes 9.2 and can be adjusted to the intended release.

AI assistance was used to prepare this change. I have reviewed the diff, understand its behavior, and take responsibility for responding substantively to maintainer feedback.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.