[FEAT]: pytest-xdist support for distributed test execution

docs/api/pytest-plugin.md

@@ -14,3 +14,27 @@ RAMPART's pytest integration. Activates automatically when installed.
       members:
         - RampartSession
         - TrialGroupResult
+
+## Parallel Execution Hooks
+
+When `pytest-xdist` is installed, the plugin registers `pytest_testnodedown` (as an optional hook) to merge worker results into the controller session. See [Parallel Execution](../usage/xdist.md) for the data flow and trust boundary.
+
+::: rampart.pytest_plugin._xdist
+    options:
+      members:
+        - SCHEMA_VERSION
+        - WORKEROUTPUT_KEY
+        - SIZE_LIMIT_OPTION
+        - DEFAULT_SIZE_LIMIT_BYTES
+        - WorkerOutputError
+        - SchemaVersionError
+        - SizeLimitError
+        - is_xdist_worker
+        - is_xdist_controller
+        - get_dist_mode
+        - get_worker_count
+        - serialize_worker_data
+        - deserialize_worker_data
+        - finalize_worker
+        - handle_testnodedown
+        - discover_sinks_from_conftest

docs/contributing/architecture.md

@@ -57,6 +57,15 @@ This allows the same evaluator (e.g., `ToolCalled`) to be used in both attack an
 
 Subclasses implement only `_execute_async` and `strategy_name`. They should **not** catch `InfrastructureError` — the base class handles it.
 
+### Pytest Plugin
+
+`pytest_plugin/` integrates RAMPART with pytest:
+
+- `plugin.py` — hook registrations (configure, collection, sessionfinish, terminal summary, optional `pytest_testnodedown`).
+- `_session.py` — session-scoped state container (`RampartSession`), trial-group aggregates, sink registry, idempotency and incomplete-run flags.
+- `_collection.py` — per-test `ResultCollector` and the `ContextVar`-based handler that captures results from executions.
+- `_xdist.py` — pytest-xdist support: detection helpers, JSON-safe serialization of `Result` objects, controller-side merge, and conftest-scanning sink discovery. Workers serialize their results into `config.workeroutput`; the controller deserializes via `pytest_testnodedown` and emits a single unified report. See [Parallel Execution](../usage/xdist.md) for the data flow and trust boundary.
+
 ### PyRIT Bridge
 
 PyRIT is RAMPART's upstream dependency for converters and prompt generation. Its import chain is heavy, so:

docs/index.md

@@ -35,4 +35,5 @@ You provide an **adapter** that connects your agent to the framework. RAMPART pr
 - **Execution strategies** — orchestrate injection, triggering, and evaluation lifecycles
 - **Evaluators** — detect conditions in agent responses (tool calls, text patterns, side effects)
 - **pytest integration** — markers for harm categorization and statistical trials, automatic result collection, terminal summaries
+- **Parallel execution** — run tests across worker processes with `pytest-xdist`; RAMPART produces a single unified report
 - **Reporting** — structured JSON output for CI dashboards

docs/usage/ci-integration.md

@@ -16,6 +16,17 @@ RAMPART tests interact with real or simulated agents and may take longer than un
 pytest tests/ -v --timeout=300
 ```
 
+### Parallel Execution
+
+For faster CI runs, use [`pytest-xdist`](xdist.md):
+
+```bash
+pip install pytest-xdist
+pytest tests/ -n auto --dist=loadgroup
+```
+
+RAMPART aggregates results across worker processes and emits a single unified report. `--dist=loadgroup` is recommended when using `@trial` markers so that trial clones run on the same worker. See [Parallel Execution](xdist.md) for details and security considerations.
+
 ---
 
 ## Trial Markers for Statistical Confidence
@@ -59,9 +70,23 @@ The JSON file contains aggregate statistics and per-result data that CI dashboar
 
 ---
 
+## Pytest Options
+
+RAMPART is configured via pytest options and Python (sinks, adapters, payloads).
+
+### `--rampart-xdist-max-bytes`
+
+Maximum size in bytes of a worker's serialized result payload when running under [`pytest-xdist`](xdist.md). Defaults to `67108864` (64 MB). Workers that exceed the cap log a warning and the controller marks the run as incomplete. Also configurable via the `rampart_xdist_max_bytes` ini option.
+
+```bash
+pytest -n auto --rampart-xdist-max-bytes=134217728   # 128 MB
+```
+
+---
+
 ## Environment Variables
 
-RAMPART itself does not read environment variables. Your adapter and test configuration typically do. Setting them locally for ad-hoc runs:
+Your adapter and test configuration typically read environment variables. Setting them locally for ad-hoc runs:
 
 === "Linux / macOS"
 

docs/usage/configuration.md

@@ -4,6 +4,16 @@ RAMPART's configurable components: [`LLMConfig`][rampart.core.llm.LLMConfig] for
 
 ---
 
+## Parallel-execution tuning
+
+RAMPART exposes one pytest option for parallel-execution tuning. Other components (LLM endpoints, agent configuration) typically have their own configuration conventions.
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--rampart-xdist-max-bytes` (CLI) / `rampart_xdist_max_bytes` (ini) | `67108864` (64 MB) | Maximum size of a worker's serialized result payload when running under [`pytest-xdist`](xdist.md). Workers exceeding the cap are recorded as incomplete in `TestRunReport.metadata`. |
+
+---
+
 ## LLMConfig
 
 Immutable configuration for an LLM endpoint. Used by [`LLMDriver`][rampart.drivers.llm.LLMDriver] and [`Payloads.generate_async()`][rampart.payloads.Payloads.generate_async].

docs/usage/pytest-integration.md

@@ -68,6 +68,9 @@ async def test_with_threshold(adapter):
 - `ERROR` results count against the pass rate (they are not `SAFE`)
 - The trial group aggregate appears in the terminal summary
 
+!!! tip "Running trials in parallel"
+    Under [`pytest-xdist`](xdist.md), use `--dist=loadgroup` to co-locate trial clones on a single worker. Aggregation is correct under any `--dist` mode, but `loadgroup` reduces cross-worker overhead.
+
 ---
 
 ## Fixtures
@@ -98,6 +101,14 @@ def rampart_sinks() -> list[ReportSink]:
     ]
 ```
 
+!!! warning "xdist compatibility"
+    Under [`pytest-xdist`](xdist.md), the controller process discovers sinks by calling `rampart_sinks` directly. Fixtures that depend on other fixtures (e.g., `tmp_path_factory`, `request`) cannot be resolved on the controller and are skipped with a warning. Use a parameterless fixture or a module-level list to remain compatible:
+
+    ```python
+    # Compatible with xdist
+    rampart_sinks = [JsonFileReportSink(output_dir=Path(".report"))]
+    ```
+
 ---
 
 ## Automatic Result Collection

docs/usage/results-and-reporting.md

@@ -91,6 +91,9 @@ class MyDatabaseSink:
 
 Define the `rampart_sinks` fixture in your `conftest.py`. See [pytest Markers & Fixtures](pytest-integration.md#rampart_sinks) for the setup and examples with multiple sinks.
 
+!!! note "Parallel execution"
+    Under [`pytest-xdist`](xdist.md), workers send their results to the controller, which emits sinks **once** with a unified [`TestRunReport`][rampart.reporting.sink.TestRunReport]. Sinks discovered on the controller cannot depend on other pytest fixtures; use a parameterless fixture or a module-level list. See [Parallel Execution](xdist.md#constraints-on-rampart_sinks) for details.
+
 ---
 
 ## TestRunReport

docs/usage/xdist.md

@@ -0,0 +1,170 @@
+# Parallel Execution with pytest-xdist
+
+RAMPART supports parallel test execution via `pytest-xdist`, producing a **single unified report** even when tests run across multiple worker processes.
+
+---
+
+## Quick Start
+
+```bash
+pip install pytest-xdist
+pytest -n 4
+```
+
+With `-n 4`, pytest spawns 4 worker processes that execute tests in parallel. RAMPART intercepts each worker's results, ships them to the controller process, and emits **one consolidated report** at the end of the session.
+
+---
+
+## How It Works
+
+```
+Worker 1                    Worker 2                    Controller
+─────────                   ─────────                   ──────────
+collect results             collect results
+    │                           │
+pytest_sessionfinish        pytest_sessionfinish
+    │                           │
+serialize → workeroutput    serialize → workeroutput
+    │                           │
+    └───────────┬───────────────┘
+                ▼
+        pytest_testnodedown (per worker)
+        deserialize + merge into
+        controller's RampartSession
+                │
+                ▼
+        pytest_sessionfinish (controller)
+        aggregate trials → evaluate gates → emit sinks
+                │
+                ▼
+        Single unified TestRunReport
+```
+
+- **Workers** collect [`Result`][rampart.core.result.Result] objects normally and serialize them into `config.workeroutput`. Workers do **not** emit reports.
+- **Controller** receives each worker's payload via the `pytest_testnodedown` hook, merges results into its own [`RampartSession`][rampart.pytest_plugin._session.RampartSession], and emits sinks once at session end.
+
+The result: **one** `JsonFileReportSink` output file, **one** call to `MyCustomSink.emit_async`, and accurate population statistics over the full result set.
+
+---
+
+## Trial Tests with xdist
+
+`@pytest.mark.trial(n=, threshold=)` clones a test into N independent runs. Under xdist, clones may be distributed across workers depending on the `--dist` mode.
+
+| `--dist` mode | Trial behavior |
+|---------------|----------------|
+| `loadgroup` | All trial clones for one test run on the same worker (recommended for locality) |
+| `load` (default) | Trial clones distributed round-robin across workers |
+| `loadscope` / `loadfile` | Grouped by class/module/file |
+
+**Correctness is preserved regardless of mode** — the controller aggregates trial groups from the merged result set. You'll see a warning if you use `@trial` markers without `--dist=loadgroup`:
+
+```text
+RAMPART @trial markers present with --dist=load. Trial clones may be
+split across workers. Aggregation remains correct (controller merges
+all results), but using --dist=loadgroup keeps trial clones co-located
+on one worker for better locality.
+```
+
+To silence the warning and improve locality:
+
+```bash
+pytest -n 4 --dist=loadgroup
+```
+
+---
+
+## Constraints on `rampart_sinks`
+
+When running under xdist, the controller process does not execute test fixtures. To discover your sinks, RAMPART scans registered conftest modules for a `rampart_sinks` attribute and calls it directly.
+
+**Supported shapes:**
+
+```python
+# Parameterless fixture — works on both single-process and xdist
+@pytest.fixture(scope="session")
+def rampart_sinks():
+    return [JsonFileReportSink(output_dir=Path(".report"))]
+
+# Plain list assigned at module level — works on both
+rampart_sinks = [JsonFileReportSink(output_dir=Path(".report"))]
+```
+
+**Not supported under xdist** (the warning is logged and the sink is skipped):
+
+```python
+# Fixture with dependencies — cannot be resolved on the controller
+@pytest.fixture(scope="session")
+def rampart_sinks(my_sink_config, db_connection):
+    return [DatabaseSink(connection=db_connection)]
+```
+
+If your sinks need dependencies, consider:
+
+- Constructing them at module level with explicit configuration
+- Reading configuration from environment variables inside a parameterless function
+- Running without xdist (`pytest` instead of `pytest -n 4`) until a hook-based registration API is added
+
+---
+
+## Trust Boundary & Security
+
+Worker payloads cross a process boundary via `execnet` and may contain attacker-controlled content (agent responses, payload text, evaluator rationale). RAMPART's serialization defends against:
+
+- **Arbitrary code execution** — strict JSON-safe primitives only; no `pickle`, `marshal`, or custom `__reduce__`.
+- **Schema drift** — payloads with missing or unknown schema versions are rejected fail-closed.
+- **Memory exhaustion** — worker payloads are capped at 64 MB by default.
+- **Terminal/log injection** — ANSI escape sequences are stripped from free-form text at the deserialization boundary.
+- **Path traversal** — worker-local artifact paths are stored as opaque strings in metadata; the controller never accesses worker files.
+
+### Size cap
+
+The default 64 MB cap can be overridden via the pytest CLI option or an ini setting:
+
+```bash
+pytest -n 4 --rampart-xdist-max-bytes=134217728
+```
+
+Or in `pytest.ini` / `pyproject.toml`:
+
+```ini
+[pytest]
+rampart_xdist_max_bytes = 134217728
+```
+
+Workers that exceed the cap log a warning and emit a truncation marker. The controller records the affected worker as incomplete in `TestRunReport.metadata`.
+
+---
+
+## Incomplete Runs
+
+If a worker crashes, runs out of time, or hits the size cap, the controller marks the run as incomplete:
+
+```python
+report.metadata["incomplete"]            # True if any worker failed
+report.metadata["incomplete_reasons"]    # list[str] — one per failure
+```
+
+Reports are still emitted with whatever data was collected. For safety-critical CI, sinks or post-processing should check the `incomplete` flag and fail the build accordingly.
+
+---
+
+## Run-Mode Metadata
+
+Reports produced under xdist include:
+
+```python
+report.metadata["xdist_active"]   # True
+report.metadata["worker_count"]   # int
+report.metadata["dist_mode"]      # "load", "loadgroup", etc.
+```
+
+---
+
+## Limitations
+
+- Sinks discovered on the controller cannot depend on other pytest fixtures (see Constraints above).
+- Mixed RAMPART versions across controller and workers are unsupported; install the same version everywhere.
+- `pytest-xdist` itself does not support interactive debugging (`--pdb`, `--trace`); use single-process mode for debugging.
+
+A hook-based sink registration API for complex sink configurations is a planned follow-up.

mkdocs.yml

@@ -163,6 +163,7 @@ nav:
       - Configuration: usage/configuration.md
       - pytest Markers & Fixtures: usage/pytest-integration.md
       - Results & Reporting: usage/results-and-reporting.md
+      - Parallel Execution: usage/xdist.md
       - CI Integration: usage/ci-integration.md
   - Contributing:
       - contributing/index.md