On this page:
contract-random-generate
contract-exercise
contract-random-generate/  choose
contract-random-generate-fail
contract-random-generate-fail?
contract-random-generate-env?
contract-random-generate-stash
contract-random-generate-get-current-environment

8.11 Random generation

procedure

(contract-random-generate ctc [fuel fail])  any/c

  ctc : contract?
  fuel : 5 = exact-nonnegative-integer?
  fail : (or/c #f (-> any) (-> boolean? any)) = #f
Attempts to randomly generate a value which will match the contract. The fuel argument limits how hard the generator tries to generate a value matching the contract and is a rough limit of the size of the resulting value.

The generator may fail to generate a value, either because some contracts do not have corresponding generators (for example, not all predicates have generators) or because there is not enough fuel. In either case, the function fail is invoked. If fail accepts an argument, it is called with #t when there is no generator for ctc and called with #f when there is a generator, but the generator ended up returning contract-random-generate-fail.

Example:
> (for/list ([i (in-range 10)])
    (contract-random-generate (or/c integer? #f)))

'(1.0 85.0 -125.0 0 30.0 #f 11.0 #f 2147483647 123)

Changed in version 6.1.1.5 of package base: Allow fail to accept a boolean.

procedure

(contract-exercise val ...+)  void?

  val : any/c
Attempts to get the vals to break their contracts (if any).

Uses value-contract to determine if any of the vals have a contract and, for those that do, uses information about the contract’s shape to poke and prod at the value. For example, if the value is function, it will use the contract to tell it what arguments to supply to the value.

Examples:
> (define/contract (returns-false x)
    (-> integer? integer?)
    ; does not obey its contract
    #f)
> (contract-exercise returns-false)

returns-false: broke its own contract

  promised: integer?

  produced: #f

  in: the range of

      (-> integer? integer?)

  contract from: (function returns-false)

  blaming: (function returns-false)

   (assuming the contract is correct)

  at: eval:2.0

> (define/contract (calls-its-argument-with-eleven f)
    (-> (-> integer? integer?) boolean?)
    ; f returns an integer, but
    ; we're supposed to return a boolean
    (f 11))
> (contract-exercise calls-its-argument-with-eleven)

calls-its-argument-with-eleven: broke its own contract

  promised: boolean?

  produced: 192

  in: the range of

      (-> (-> integer? integer?) boolean?)

  contract from:

      (function calls-its-argument-with-eleven)

  blaming: (function calls-its-argument-with-eleven)

   (assuming the contract is correct)

  at: eval:4.0

procedure

(contract-random-generate/choose c fuel)  (or/c #f (-> c))

  c : contract?
  fuel : exact-nonnegative-integer?
This function is like contract-random-generate, but it is intended to be used with combinators that generate values based on sub-contracts they have. It cannot be called, except during contract generation. It will never fail, but it might escape back to an enclosing call or to the original call to contract-random-generate.

It chooses one of several possible generation strategies, and thus it may not actually use the generator associated with c, but might instead use a stashed value that matches c that it knows about via contract-random-generate-stash.

Added in version 6.1.1.5 of package base.

An atomic value that is used to indicate that a generator failed to generate a value.

Added in version 6.1.1.5 of package base.

procedure

(contract-random-generate-fail? v)  boolean?

  v : any/c
A predicate to recognize contract-random-generate-fail.

Added in version 6.1.1.5 of package base.

procedure

(contract-random-generate-env? v)  boolean?

  v : any/c
Recognizes contract generation environments.

Added in version 6.1.1.5 of package base.

procedure

(contract-random-generate-stash env c v)  void?

  env : contract-random-generate-env?
  c : contract?
  v : c
This should be called with values that the program under test supplies during contract generation. For example, when (-> (-> integer? integer?) integer?) is generated, it may call its argument function. That argument function may return an integer and, if so, that integer should be saved by calling contract-random-generate-stash, so it can be used by other integer generators.

Added in version 6.1.1.5 of package base.

procedure

(contract-random-generate-get-current-environment)

  contract-random-generate-env?
Returns the environment currently being for generation. This function can be called only during the dynamic extent of contract generation. It is intended to be grabbed during the construction of a contract generator and then used with contract-random-generate-stash while generation is happening.

Added in version 6.1.1.5 of package base.