pytest-plugin-utils 0.1.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:

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)

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

MIT License

---

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