pytest-plugin-utils 0.2.0

Reusable configuration and artifact utilities for building pytest plugins

Reusable pytest Plugin Utilities

Building pytest plugins means dealing with the same problems repeatedly: managing configuration options with proper precedence (CLI vs INI vs defaults), creating per-test artifact directories, and sanitizing test names for filesystem paths. This package extracts those common patterns into reusable utilities.

I created this after extracting the config and path handling logic from pytest-playwright-artifacts. Rather than reinvent option handling in every plugin, you can use these utilities to get consistent behavior across pytest plugins.

Installation

uv add pytest-plugin-utils

Usage

Configuration Options

Register pytest options with automatic precedence handling (runtime > CLI > INI > defaults) and type inference.

For Plugin Authors

from pytest_plugin_utils import set_pytest_option, register_pytest_options, get_pytest_option

def pytest_addoption(parser):
    # Define your options (use __package__ for namespace)
    set_pytest_option(
        __package__,
        "api_url",
        default="http://localhost:3000",
        help="API base URL",
        available="all",  # Expose via CLI and INI
        type_hint=str,
    )

    # Register them with pytest
    register_pytest_options(__package__, parser)

def pytest_configure(config):
    # Retrieve with automatic type casting
    api_url = get_pytest_option(__package__, config, "api_url", type_hint=str)

For Plugin Users

Once a plugin has registered options using this package, users can configure them in three ways (in order of precedence):

1. Command Line (highest priority):

   pytest --api-url=https://prod.example.com
   

2. INI Configuration (medium priority):

   In pytest.ini:

   [pytest]
   api_url = https://staging.example.com
   

   Or in pyproject.toml:

   [tool.pytest.ini_options]
   api_url = "https://staging.example.com"
   

3. Runtime/Programmatic (via conftest.py):

   def pytest_configure(config):
       # Override at runtime
       config.option.api_url = "https://custom.example.com"
   

The value resolution follows this precedence chain, with each level overriding the next: Runtime > CLI > INI > Default.

Artifact Directory Management

Create per-test artifact directories with sanitized names:

from pytest_plugin_utils import set_artifact_dir_option, get_artifact_dir

def pytest_configure(config):
    # Configure which option name to use (use __package__ for namespace)
    set_artifact_dir_option(__package__, "my_plugin_output")

def pytest_runtest_setup(item):
    # Get a clean directory for this specific test
    artifact_dir = get_artifact_dir(__package__, item)
    # Returns: /output/test-file-py-test-name-param/

Features

• Centralized option registry with runtime, CLI, and INI support
• Automatic INI type inference from Python type hints (bool, str, list[str], list[Path])
• Smart value casting with fallback precedence handling
• Filesystem-safe test name sanitization for artifact paths
• Per-test artifact directory creation and resolution
• Type-safe configuration retrieval with warnings on mismatches

Related Projects

• pytest-playwright-visual-snapshot: Easy pytest visual regression testing using playwright.
• pytest-line-runner: Run pytest tests by line number instead of exact test name.
• pytest-celery-utils: Pytest plugin for inspecting Celery task queues in Redis during tests.
• pytest-playwright-artifacts: Pytest plugin that captures HTML, screenshots, and console logs on Playwright test failures.

MIT License

---

This project was created from iloveitaly/python-package-template