pub trait ValueTree {
type Value: Debug;
fn current(&self) -> Self::Value;
fn simplify(&mut self) -> bool;
fn complicate(&mut self) -> bool;
}Expand description
A generated value and its associated shrinker.
Conceptually, a ValueTree represents a spectrum between a “minimally
complex” value and a starting, randomly-chosen value. For values such as
numbers, this can be thought of as a simple binary search, and this is how
the ValueTree state machine is defined.
The ValueTree state machine notionally has three fields: low, current,
and high. Initially, low is the “minimally complex” value for the type, and
high and current are both the initially chosen value. It can be queried for
its current state. When shrinking, the controlling code tries simplifying
the value one step. If the test failure still happens with the simplified
value, further simplification occurs. Otherwise, the code steps back up
towards the prior complexity.
The main invariants here are that the “high” value always corresponds to a
failing test case, and that repeated calls to complicate() will return
false only once the “current” value has returned to what it was before
the last call to simplify().
While it would be possible for default do-nothing implementations of
simplify() and complicate() to be provided, this was not done
deliberately since the majority of strategies will want to define their own
shrinking anyway, and the minority that do not must call it out explicitly
by their own implementation.
Required Associated Types
Required Methods
Attempts to simplify the current value. Notionally, this sets the “high” value to the current value, and the current value to a “halfway point” between high and low, rounding towards low.
Returns whether any state changed as a result of this call. This does
not necessarily imply that the value of current() has changed, since
in the most general case, it is not possible for an implementation to
determine this.
This call needs to correctly handle being called even immediately after
it had been called previously and returned false.
fn complicate(&mut self) -> bool
fn complicate(&mut self) -> bool
Attempts to partially undo the last simplification. Notionally, this sets the “low” value to one plus the current value, and the current value to a “halfway point” between high and the new low, rounding towards low.
Returns whether any state changed as a result of this call. This does
not necessarily imply that the value of current() has changed, since
in the most general case, it is not possible for an implementation to
determine this.
It is usually expected that, immediately after a call to simplify()
which returns true, this call will itself return true. However, this is
not always the case; in some strategies, particularly those that use
some form of rejection sampling, the act of trying to simplify may
change the state such that simplify() returns true, yet ultimately
left the resulting value unchanged, in which case there is nothing left
to complicate.
This call does not need to gracefully handle being called before
simplify() was ever called, but does need to correctly handle being
called even immediately after it had been called previously and
returned false.