Struct proptest::test_runner::Config
source · pub struct Config {Show 14 fields
pub cases: u32,
pub max_local_rejects: u32,
pub max_global_rejects: u32,
pub max_flat_map_regens: u32,
pub failure_persistence: Option<Box<dyn FailurePersistence>>,
pub source_file: Option<&'static str>,
pub test_name: Option<&'static str>,
pub fork: bool,
pub timeout: u32,
pub max_shrink_time: u32,
pub max_shrink_iters: u32,
pub result_cache: fn() -> Box<dyn ResultCache>,
pub verbose: u32,
pub rng_algorithm: RngAlgorithm,
/* private fields */
}Expand description
Configuration for how a proptest test should be run.
Fields§
§cases: u32The number of successful test cases that must execute for the test as a whole to pass.
This does not include implicitly-replayed persisted failing cases.
The default is 256, which can be overridden by setting the
PROPTEST_CASES environment variable. (The variable is only considered
when the std feature is enabled, which it is by default.)
max_local_rejects: u32The maximum number of individual inputs that may be rejected before the test as a whole aborts.
The default is 65536, which can be overridden by setting the
PROPTEST_MAX_LOCAL_REJECTS environment variable. (The variable is only
considered when the std feature is enabled, which it is by default.)
max_global_rejects: u32The maximum number of combined inputs that may be rejected before the test as a whole aborts.
The default is 1024, which can be overridden by setting the
PROPTEST_MAX_GLOBAL_REJECTS environment variable. (The variable is
only considered when the std feature is enabled, which it is by
default.)
max_flat_map_regens: u32The maximum number of times all Flatten combinators will attempt to
regenerate values. This puts a limit on the worst-case exponential
explosion that can happen with nested Flattens.
The default is 1_000_000, which can be overridden by setting the
PROPTEST_MAX_FLAT_MAP_REGENS environment variable. (The variable is
only considered when the std feature is enabled, which it is by
default.)
failure_persistence: Option<Box<dyn FailurePersistence>>Indicates whether and how to persist failed test results.
When compiling with “std” feature (i.e. the standard library is available), the default
is Some(Box::new(FileFailurePersistence::SourceParallel("proptest-regressions"))).
Without the standard library, the default is None, and no persistence occurs.
See the docs of FileFailurePersistence
and MapFailurePersistence for more information.
You can disable failure persistence with the PROPTEST_DISABLE_FAILURE_PERSISTENCE
environment variable but its not currently possible to set the persistence file
with an environment variable. (The variable is
only considered when the std feature is enabled, which it is by
default.)
source_file: Option<&'static str>File location of the current test, relevant for persistence and debugging.
Note the use of &str rather than Path to be compatible with
#![no_std] use cases where Path is unavailable.
See the docs of FileFailurePersistence
for more information on how it may be used for persistence.
test_name: Option<&'static str>The fully-qualified name of the test being run, as would be passed to the test executable to run just that test.
This must be set if fork is true. Otherwise, it is unused. It is
automatically set by proptest!.
This must include the crate name at the beginning, as produced by
module_path!().
fork: boolfork only.If true, tests are run in a subprocess.
Forking allows proptest to work with tests which may fail by aborting the process, causing a segmentation fault, etc, but can be a lot slower in certain environments or when running a very large number of tests.
For forking to work correctly, both the Strategy and the content of
the test case itself must be deterministic.
This requires the “fork” feature, enabled by default.
The default is false, which can be overridden by setting the
PROPTEST_FORK environment variable. (The variable is
only considered when the std feature is enabled, which it is by
default.)
timeout: u32timeout only.If non-zero, tests are run in a subprocess and each generated case fails if it takes longer than this number of milliseconds.
This implicitly enables forking, even if the fork field is false.
The type here is plain u32 (rather than
Option<std::time::Duration>) for the sake of ergonomics.
This requires the “timeout” feature, enabled by default.
Setting a timeout to less than the time it takes the process to start up and initialise the first test case will cause the whole test to be aborted.
The default is 0 (i.e., no timeout), which can be overridden by
setting the PROPTEST_TIMEOUT environment variable. (The variable is
only considered when the std feature is enabled, which it is by
default.)
max_shrink_time: u32std only.If non-zero, give up the shrinking process after this many milliseconds have elapsed since the start of the shrinking process.
This will not cause currently running test cases to be interrupted.
This configuration is only available when the std feature is enabled
(which it is by default).
The default is 0 (i.e., no limit), which can be overridden by setting
the PROPTEST_MAX_SHRINK_TIME environment variable. (The variable is
only considered when the std feature is enabled, which it is by
default.)
max_shrink_iters: u32Give up on shrinking if more than this number of iterations of the test code are run.
Setting this to std::u32::MAX causes the actual limit to be four
times the number of test cases.
Setting this value to 0 disables shrinking altogether.
Note that the type of this field will change in a future version of proptest to better accommodate its special values.
The default is std::u32::MAX, which can be overridden by setting the
PROPTEST_MAX_SHRINK_ITERS environment variable. (The variable is only
considered when the std feature is enabled, which it is by default.)
result_cache: fn() -> Box<dyn ResultCache>A function to create new result caches.
The default is to do no caching. The easiest way to enable caching is
to set this field to basic_result_cache (though that is currently
only available with the std feature).
This is useful for strategies which have a tendency to produce duplicate values, or for tests where shrinking can take a very long time due to exploring the same output multiple times.
When caching is enabled, generated values themselves are not stored, so this does not pose a risk of memory exhaustion for large test inputs unless using extraordinarily large test case counts.
Caching incurs its own overhead, and may very well make your test run more slowly.
verbose: u32std only.Set to non-zero values to cause proptest to emit human-targeted messages to stderr as it runs.
Greater values cause greater amounts of logs to be emitted. The exact meaning of certain levels other than 0 is subject to change.
- 0: No extra output.
- 1: Log test failure messages. In state machine tests, this level is used to print transitions.
- 2: Trace low-level details.
This is only available with the std feature (enabled by default)
since on nostd proptest has no way to produce output.
The default is 0, which can be overridden by setting the
PROPTEST_VERBOSE environment variable. (The variable is only considered
when the std feature is enabled, which it is by default.)
rng_algorithm: RngAlgorithmThe RNG algorithm to use when not using a user-provided RNG.
The default is RngAlgorithm::default(), which can be overridden by
setting the PROPTEST_RNG_ALGORITHM environment variable to one of the following:
xs—RngAlgorithm::XorShiftcc—RngAlgorithm::ChaCha
(The variable is only considered when the std feature is enabled,
which it is by default.)
Implementations§
source§impl Config
impl Config
sourcepub fn with_cases(cases: u32) -> Self
pub fn with_cases(cases: u32) -> Self
Constructs a Config only differing from the default() in the
number of test cases required to pass the test successfully.
This is simply a more concise alternative to using field-record update syntax:
assert_eq!(
Config::with_cases(42),
Config { cases: 42, .. Config::default() }
);sourcepub fn with_source_file(source_file: &'static str) -> Self
pub fn with_source_file(source_file: &'static str) -> Self
Constructs a Config only differing from the default() in the
source_file of the present test.
This is simply a more concise alternative to using field-record update syntax:
assert_eq!(
Config::with_source_file("computer/question"),
Config { source_file: Some("computer/question"), .. Config::default() }
);sourcepub fn clone_with_source_file(&self, source_file: &'static str) -> Self
pub fn clone_with_source_file(&self, source_file: &'static str) -> Self
Constructs a Config only differing from the provided Config instance, self,
in the source_file of the present test.
This is simply a more concise alternative to using field-record update syntax:
let a = Config::with_source_file("computer/question");
let b = a.clone_with_source_file("answer/42");
assert_eq!(
a,
Config { source_file: Some("computer/question"), .. Config::default() }
);
assert_eq!(
b,
Config { source_file: Some("answer/42"), .. Config::default() }
);sourcepub fn fork(&self) -> bool
pub fn fork(&self) -> bool
Return whether this configuration implies forking.
This method exists even if the “fork” feature is disabled, in which case it simply returns false.
sourcepub fn timeout(&self) -> u32
pub fn timeout(&self) -> u32
Returns the configured timeout.
This method exists even if the “timeout” feature is disabled, in which case it simply returns 0.
sourcepub fn max_shrink_iters(&self) -> u32
pub fn max_shrink_iters(&self) -> u32
Returns the configured limit on shrinking iterations.
This takes into account the special “automatic” behaviour.