setupplan.py

Overview

The [setupplan.py](/projects/286/67433) file is a utility extension for the pytest testing framework that introduces a command-line option to **display the planned fixture and test setup sequence without actually executing any tests or fixture setups**. This is useful for debugging and understanding the order and dependencies of fixtures and tests in a pytest session.

Key functionality includes:

• Adding a --setupplan (or --setup-plan) command-line flag.

• Intercepting fixture setup calls to prevent actual fixture execution when --setupplan is used.

• Adjusting pytest's internal options to reflect a "dry run" mode that only shows setup plans.

This file leverages pytest’s hook system to integrate seamlessly with pytest’s lifecycle and configuration processing.

Detailed Explanation

Functions

pytest_addoption(parser: Parser) -> None

**Purpose:** Registers a new command-line option group "debugconfig" and adds the `--setupplan` / [--setup-plan](/projects/286/67223) flag to pytest's CLI options.

**Parameters:**

• parser (Parser): The pytest argument parser instance to which the option group and option will be added.

**Returns:**

• None

**Behavior:**

• Creates a new option group named "debugconfig".

• Adds a boolean flag --setupplan (alias --setup-plan) that, when enabled, instructs pytest to show the fixture and test execution plan without running anything.

**Usage Example:**

pytest --setupplan

pytest_fixture_setup(fixturedef: FixtureDef[object], request: SubRequest) -> object | None

**Purpose:** A hook implementation that intercepts fixture setup calls. If the `--setupplan` option is enabled, this function prevents actual fixture execution by returning a dummy cached result.

**Parameters:**

• fixturedef (FixtureDef[object]): The definition object for the fixture being set up.

• request (SubRequest): The pytest request object used to access test context and config.

**Returns:**

• object | None: Returns a dummy cached fixture result if --setupplan is enabled; otherwise returns None to let pytest continue normal fixture setup.

**Behavior:**

• Checks if the setupplan option is enabled on the pytest config.

• Generates a cache key for the fixture.

• Sets the fixture's cached result to a tuple (None, cache_key, None) which acts as a placeholder to indicate the fixture was "set up" without side effects.

• Returns this dummy cached result to short-circuit actual fixture initialization.

**Usage Context:** Called internally by pytest during fixture setup. Not typically called manually.

pytest_cmdline_main(config: Config) -> int | ExitCode | None

**Purpose:** A hook implementation that modifies pytest configuration options early in the command-line main phase, aligning other internal options with `--setupplan`.

**Parameters:**

• config (Config): The pytest configuration object that holds CLI options and internal state.

**Returns:**

• int | ExitCode | None: Returns None to allow pytest to continue normal main execution.

**Behavior:**

• When setupplan is enabled:

  • Sets config.option.setuponly to True, indicating only fixture setup should be considered.

  • Sets config.option.setupshow to True, enabling fixtures setup display.

• These options influence pytest's built-in behavior to support the dry-run setup plan mode.

Important Implementation Details

• Hook Implementations with tryfirst=True:
  Both pytest_fixture_setup and pytest_cmdline_main are registered with tryfirst=True, ensuring they run before other hook implementations. This early intervention is critical to override fixture setup behavior and config options.

• Use of Cached Fixture Results:
  Instead of executing fixture setup code, pytest_fixture_setup simulates the setup by assigning a cached result tuple with the fixture's cache key but no actual value. This prevents side effects and reduces runtime while still showing what would be set up.

• Option Grouping:
  The --setupplan option is grouped under "debugconfig" to logically organize debugging-related options in the pytest CLI help.

Interaction with Other System Components

• Pytest Core:
  This file hooks into pytest's plugin system and modifies the behavior of fixture setup and command-line processing. It depends on pytest's internal APIs such as FixtureDef, SubRequest, and the Config object.

• Fixture Management:
  By intercepting fixture setup, it provides insight into the test dependency graph without executing tests or fixtures, aiding in debugging complex test suites.

• Command-line Interface:
  Extends pytest's CLI with a new option that influences runtime behavior, integrating with pytest's config parsing and option handling.

Usage Summary

To use this feature, simply run pytest with:

pytest --setupplan

This will output the plan of fixtures and tests pytest would execute, but will **not actually run** the tests or fixture setup code. This is helpful to understand dependencies and order of test setup.

Visual Diagram

classDiagram
    class SetupPlanPlugin {
        +pytest_addoption(parser: Parser) void
        +pytest_fixture_setup(fixturedef: FixtureDef, request: SubRequest) object | None
        +pytest_cmdline_main(config: Config) int | ExitCode | None
    }

    SetupPlanPlugin ..> Parser : uses
    SetupPlanPlugin ..> FixtureDef : uses
    SetupPlanPlugin ..> SubRequest : uses
    SetupPlanPlugin ..> Config : uses

Summary

The [setupplan.py](/projects/286/67433) file is a pytest plugin extension that adds a `--setupplan` option to show the planned fixture and test execution order without running anything. It achieves this by hooking into pytest’s fixture setup and command-line main phases, disabling actual fixture execution and adjusting configuration options to simulate a setup-only dry run. This tool is valuable for debugging and inspecting test dependencies in complex pytest test suites.

End of Documentation for setupplan.py