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.12 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)))

'(#f -488271126.0 -1939728703 #f #f 0 -188.0 #f #f 0)

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

procedure

(contract-exercise [#:fuel fuel    
  #:shuffle? shuffle?]    
  val ...+)  void?
  fuel : exact-nonnegative-integer? = 10
  shuffle? : any/c = #f
  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.

The argument fuel determines how hard contract-exercise tries to break the values. It controls both the number of exercise iterations and the size of the intermediate values generated during the exercises.

The argument shuffle? controls whether contract-exercise randomizes the exercise order or not. If shuffle? is not #f, contract-exercise would shuffle the order of the contracts in each exercise iteration.

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: 11

  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

Changed in version 7.0.0.18 of package base: Added the shuffle? optional argument.

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 must be called when contract-random-generate (and contract-exercise) creates the generators. To be more precise, contract-random-generate/choose is available only for the generate and exercise arguments in build-contract-property, build-chaperone-contract-property or build-flat-contract-property and only during the dynamic extent of the call to generate (and exercise). That is, after it receives the c and fuel arguments and before it returns the thunk (or the exerciser).

contract-random-generate/choose 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.

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.