Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Settings

Settings

Settings(
    *,
    max_examples: Int = 100,
    seed: Optional[UInt64] = None,
    derandomize: Bool = False,
    database: Optional[String] = ".proptest/examples",
    database_key: String = "",
    phases: Phases = Phases(),
    verbosity: Verbosity = Verbosity.normal,
    report_multiple_bugs: Bool = True,
    suppress_health_check: List[HealthCheck] = [],
    stateful_step_count: Int = 50,
    max_shrinks: Int = 500,
    print_blob: Bool = False,
    deadline: Optional[Float64] = 200.0,
    reproduce: Optional[String] = None,
    show_statistics: Bool = False,
    check_coverage: Optional[Confidence] = None,
    fork: Bool = False,
    timeout: Optional[Float64] = None,
)
SettingDescription
max_examplesHow many valid test cases to run before passing.
seedThe random seed. Random for each run when unset.
derandomizeDerive the seed from the test’s database key, so every run of the test is the same.
databaseThe directory for saved failures; None disables the database.
database_keyThe test’s key in the database. Filled in from the test’s source location when empty.
phasesWhich phases of the run are enabled; see Phases.
verbosityHow much to print; see Verbosity.
report_multiple_bugsReport every distinct failure found, rather than just one.
suppress_health_checkHealth checks not to run.
stateful_step_countThe maximum number of steps in a state machine program.
max_shrinksStop shrinking after this many successful shrinks.
print_blobInclude a reproduce= blob in failure reports.
deadlineFail a test case whose body (not counting data generation) takes longer than this many milliseconds. None disables it. In stateful tests it applies to each step.
reproduceA blob from a failure report: replay exactly that test case, without searching or shrinking (Hypothesis’s @reproduce_failure).
show_statisticsPrint the run’s statistics: events, tables, and coverage.
forkRun each test case in a child process, so that a crash (a segfault, an abort, a sanitizer report) fails the test case and is shrunk instead of ending the run. See Test code that crashes.
timeoutKill a test case that runs longer than this many milliseconds, and fail it with Timeout. Implies fork.
check_coverageCheck cover requirements statistically, generating past max_examples until they’re settled, and fail if one isn’t met (QuickCheck’s checkCoverage).

Environment variables

Settings that a test leaves at their defaults can be changed from the environment, like a Hypothesis settings profile. A value set in the code always wins.

VariableSettingValues
PROPTEST_MAX_EXAMPLESmax_examplesan integer
PROPTEST_SEEDseedan integer
PROPTEST_VERBOSITYverbosityquiet, normal, verbose, debug
PROPTEST_DATABASEdatabasea directory, or none
PROPTEST_FORKfork1 or true
PROPTEST_TIMEOUTtimeoutmilliseconds

settings.with_env_overrides() returns the settings with these applied; the test runners call it for you.

Phases

Phases(*, explicit=True, reuse=True, generate=True, target=True, shrink=True, explain=True)
PhaseDescription
explicitRun explicit examples.
reuseReplay failures saved in the database.
generateGenerate new test cases.
targetHill-climb on data.target scores.
shrinkShrink failing test cases.
explainAfter shrinking, find arguments that can vary without changing the failure, and mark them in the report.

Verbosity

ValuePrints
Verbosity.quietNothing beyond failures. Coverage warnings are suppressed.
Verbosity.normalFailure reports, and warnings about unmet coverage.
Verbosity.verboseAlso each run’s counts and seed, the statistics, and reproduce blobs.
Verbosity.debugAlso every test case, every shrink, and shrink pass statistics.

HealthCheck

ValueFails when
HealthCheck.filter_too_muchMost test cases are rejected.
HealthCheck.data_too_largeMany test cases exceed the choice limit (8,192 choices).
HealthCheck.too_slowGenerating data is too slow.
HealthCheck.large_base_exampleThe simplest input is very large.

See Suppress a health check.

Confidence

Confidence(*, certainty: Float64 = 1e9, tolerance: Float64 = 0.9)

How sure a coverage check must be (QuickCheck’s Confidence). A requirement of p% passes once proptest is confident the true share is at least tolerance × p%, and fails once it is confident the share is below p%. Each conclusion is wrong with probability about 1 / certainty.