parallel¶

File-based coordination for parallel fail-fast across worker processes.

When behave runs with --parallel=N, each worker is a separate process with its own PriorityState. This module provides a ParallelCoordinator that uses a shared directory with one JSON file per worker to track global failure counts and critical failures.

Each worker writes its own file atomically (temp file + rename). To check global state, all worker files in the coordination directory are read and aggregated. This avoids the need for cross-process file locking.

Usage:

# Before running behave with --parallel, set env var:
#   BEHAVE_PRIORITY_COORD_DIR=/tmp/behave_priority_coord

# In environment.py:
setup_priority(context, stop_after_failures=3, parallel_coord=True)

class behave_priority.parallel.ParallelCoordinator(coord_dir: str | Path, worker_id: str | None = None)[source]¶

Bases: object

File-based coordination for parallel workers.

Each worker creates and maintains its own JSON file in a shared coordination directory. The file contains the worker’s failure count and critical-failure flag. Global state is computed by reading all worker files in the directory.

Variables:

coord_dir – Directory where worker files are stored.
worker_id – Unique identifier for this worker (defaults to PID).

cleanup() → None[source]¶: Remove this worker’s file from the coordination directory.

report_failure(*, is_critical: bool = False) → None[source]¶

Record a failure for this worker.

Atomically updates the worker’s file with the new failure count.

Parameters:: is_critical – Whether the failure was in a critical scenario.

should_stop(stop_after_failures: int | None, stop_on_critical: bool) → bool[source]¶

Check if global fail-fast conditions have been met.

Reads all worker files in the coordination directory and aggregates failure counts and critical-failure flags.

Parameters:

stop_after_failures – Global failure threshold, or None.
stop_on_critical – Whether to stop on any critical failure.

Returns:

True if global conditions indicate execution should stop.

behave_priority.parallel.cleanup_coordinator(context: object) → None[source]¶

Clean up the parallel coordinator for this worker.

Intended for use in after_all. Removes the worker’s file from the coordination directory.

Parameters:: context – Behave’s context object.

behave_priority.parallel.create_coordinator(worker_id: str | None = None) → ParallelCoordinator | None[source]¶

Create a ParallelCoordinator from the env var, if set.

Parameters:: worker_id – Optional worker identifier. Defaults to PID.
Returns:: A ParallelCoordinator if BEHAVE_PRIORITY_COORD_DIR is set, otherwise None.

behave_priority.parallel.get_coord_dir() → str | None[source]¶

Get the coordination directory from the environment variable.

Returns:: The path from BEHAVE_PRIORITY_COORD_DIR env var, or None.

Classes¶