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 registers a stochastic marker (visible in pytest --markers, compatible with --strict-markers) and automatically applies it to all @stochastic_test and @distributional_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"]
confidence = 1e-08
method = "maurer_pontil"
n_tune_samples = 50000
observed_range = [0.000012, 0.999987]
tuned_at = "2026-02-22T15:30:00+00:00"
variance = 0.09973

Keys are the fully qualified test-function name ({module}.{qualname}). See Tune Mode for field meanings.

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 a stable digest (sha256) of the test's node ID, so it is reproducible across runs and machines.

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, bad `side`, `failure_prob` out of range, etc.)
`NoApplicableBoundError`	No concentration bound matches the declared properties
`ConfigurationError`	Invalid `@distributional_test` configuration (unknown test, bad significance, etc.); also the base class of the errors above