Configuration Reference¶

pytest-stochastic is configured through decorator parameters and CLI options. No pyproject.toml or pytest.ini configuration is required for basic usage.

CLI Options¶

`--stochastic-tune`¶

Enable tune mode. Instead of running tests normally, each @stochastic_test function is profiled to discover distributional parameters.

pytest --stochastic-tune

`--stochastic-tune-samples N`¶

Number of samples to collect per test during tuning. Default: 50,000.

pytest --stochastic-tune --stochastic-tune-samples 100000

Pytest Markers¶

The plugin automatically adds a stochastic marker to all @stochastic_test functions. You can use this for filtering:

# Run only stochastic tests
pytest -m stochastic

# Skip stochastic tests
pytest -m "not stochastic"

.stochastic.toml¶

The tuning data file, created by --stochastic-tune. This file is loaded automatically when present.

Location¶

The file is written to and read from the pytest root directory (typically the project root).

Format¶

# Auto-generated by pytest-stochastic --stochastic-tune

[tests."tests.test_module.test_function_name"]
variance = 0.08345
observed_range = [0.000012, 0.999987]
n_tune_samples = 50000
tuned_at = "2026-02-22T15:30:00+00:00"

Version Control¶

Commit .stochastic.toml to version control so all developers and CI benefit from tuned parameters. The file merges gracefully when re-tuned.

Fixtures¶

`stochastic_rng`¶

A pytest fixture providing a seeded numpy.random.Generator. The seed is derived from the test's node ID for reproducibility.

def test_custom(stochastic_rng):
    value = stochastic_rng.normal()
    assert isinstance(value, float)

Verbose Output¶

In verbose mode (-v), stochastic tests include bound information in the status line:

test_example.py::test_mean PASSED [bernstein, n=423, observed=0.501234]

Failed tests include the seed and assertion details:

test_example.py::test_mean FAILED [bernstein, n=423, seed=12345]:
  |0.567 - 0.5| = 0.067 not < 0.05 (expected=0.5, tol=0.05)

Error Handling¶

Configuration errors are raised at import time (when the decorator is applied), not at test time. This means misconfigurations surface immediately:

Error	Cause
`InvalidToleranceError`	Both `atol` and `rtol` are zero, or negative values
`InvalidPropertyError`	Invalid property values (negative variance, bad bounds, etc.)
`NoApplicableBoundError`	No concentration bound matches the declared properties
`ConfigurationError`	General configuration issues (bad side, bad significance, etc.)