Signal-Aware Suite Runner

A minimal command wrapper that executes scenarios with fail-fast thresholds, signal-aware interruption, and deterministic exit codes for CI environments.

Capabilities

Failure threshold halts execution

• With max_failures=1, when two failing scenarios precede a passing scenario, execution stops after the first failure and returns a non-zero exit code @test
• With max_failures=2, execution stops after the second failing scenario, leaving later scenarios unrun, and returns a non-zero exit code @test

Graceful signal interruption

• When an OS signal matching intercept_signal is raised during execution, the runner halts remaining scenarios, records the run as interrupted, and returns a non-zero exit code distinct from a normal success @test

Empty selection exit policy

• When no scenarios match the provided paths and allow_empty is false, the runner exits with a non-zero code and a short message indicating nothing ran @test
• When the same command is invoked with allow_empty true, the runner exits with code zero while still emitting an empty-discovery notice @test

Implementation

@generates

API

from typing import Iterable

def run_suite(paths: Iterable[str], *, max_failures: int | None = 1, allow_empty: bool = False, intercept_signal: str | None = "SIGINT") -> int:
    """
    Run scenarios located at the provided paths using the dependency's built-in
    interruption and exit-handling controls.
    
    Args:
        paths: File or directory paths to search for scenarios.
        max_failures: Stop execution after this many scenario failures; None disables
            the fail-fast threshold.
        allow_empty: If True, treat an empty selection as success; otherwise treat it
            as a failure.
        intercept_signal: Name of an OS signal that should trigger an orderly stop
            and exit; None disables signal interception.
    
    Returns:
        The process-style exit code produced by the executed run.
    """

Dependencies { .dependencies }

vedro { .dependency }

Behavior-driven Python testing framework with scenario discovery, interruption controls, and exit shaping.