Better document/fix shrinking API

[sir4ur0n]

Hi,

I have written a library of generators for Vavr, and I'm now addressing the shrinking part.
The shrinking API is weird and not enough documented. Here's a list of proposals:

1. Why try bigger values before smaller values?
   See QuickCheck documentation on shrinking: it tries smaller values before bigger values, which makes more sense (don't bother testing a huge list of N-1 elements if an empty list already blows up).

2. Support a lazy structure: doShrink must return a java.util.List which has only strict implementations in the JDK AFAIK. Building a list of shrinks may be CPU-heavy, and if the first value doesn't pass, then we discard everything and start shrinking again from the slightly smallest value.
   If we could return a lazy structure (e.g. a Stream), this would significantly improve the shrinking process.

3. Provide an easy way to log/understand what happens during shrinking, much like QuickCheck provides a verbose mode which details every step (passed, failed, shrunk, etc.).

Passed:
[]
Passed:
[]
Passed:
[]
Failed:
[2,2]
Passed:
[]
Passed:
[2]
Passed:
[2]
Failed:
[0,2]
Passed:
[]
Passed:
[2]
Passed:
[0]
Failed:
[0,0]
Passed:
[]
Passed:
[0]
Passed:
[0]
*** Failed! Falsifiable (after 4 tests and 2 shrinks):
[0,0]
Use --quickcheck-replay=249810 to reproduce.

If it already exists, providing documentation to detail this would be nice 😄

Let me know if you want me to open several issues.

[pholser]

@sir4ur0n Thanks for your interest! I will look into these requested changes.

[pholser]

@sir4ur0n For 1), you're right -- there's no particular reason to try larger shrinks before smaller ones.

2. I agree that laziness would be more useful. Also, what you said about abandoning generated shrinks as soon as a smaller counterexample is found from among them sounds reasonable, even if we were to continue yielding Lists from doShrink.

3. Also reasonable.

These three sound like each might be valuable independent of the others. What do you think about having separate GH issues for each?

[sir4ur0n]

I propose we address 1) through #219

2. can be addressed in Shrinkers should be able to provide a Stream #220

3. can be addressed in Provide optional step-by-step logs #221

Then we can close this issue :)

[pholser]

Agreed. Closing this one. Thanks!