quickcheck2.scrbl

@defproc[(specification [prop property?] [arb arbitrary?] ...) specification?]{
  Constructs a runnable, executable, testable @specification-tech[] that tests that
  @racket[prop] holds for all inputs from the given @racket[arb]s. The returned
  specification can be quickly tested with @racket[check-specification]. Additionally,
  the specification can be run and have its results analyzed separately by using
  @racket[run-specification].
  @quickcheck2-examples[
    (check-specification (specification positive? arbitrary-natural))
    (check-specification (specification even? arbitrary-natural))
]}

@defproc[(run-specification [spec specification?]) (stream/c specification-result?)]{
  Given a specification, initializes the test run and returns a lazy @racket[stream?]
  containing the results of each individual test. To actually run the tests, the stream must
  be forced, examining each result.
  @quickcheck2-examples[
    (define spec (specification positive? arbitrary-natural))
    (stream-first (run-specification spec))
]}

@struct[specification-result ([status (or/c 'pass 'fail 'exhausted)]
                              [input any/c]
                              [classifications (listof symbol?)]
                              [measurements (hash/c symbol? any/c)])]{
  Represents the result of a single test in a specification test run. The @racket[status]
  field indicates whether the specification passed the test, failed the test, or
  @input-exhaustion-section{exhausted the inputs}. The @racket[input] field contains
  the value used in the test run. If multiple inputs were used due to initial values being
  irrelevant to the property, this field contains the last one used. The @racket[classifications]
  field contains the relevent @classification-section{classifications} the
  specification decided this test falls into. The @racket[measurements] field
  contains a collection of named @measurements-section{measurements} the
  specification collected for this test run.
}

@defproc[(summary-results-status [results (stream/c specification-result)])
         (or/c 'pass 'fail 'exhausted)]{
  Given a results stream, reduces it to a single summary value - @racket['pass]
  if all tests passed, @racket['fail] if any test failed, or @racket['exhausted]
  if all tests passed up to a point where the tests exhausted the inputs.
  @quickcheck2-examples[
    (define spec (specification positive? arbitrary-natural))
    (summary-results-status (run-specification spec))
    (define bad-spec (specification even? arbitrary-natural))
    (summary-results-status (run-specification bad-spec))
]}