clojure.test.check.generators — org.clojure/test.check 1.0.0

any clj/s

A recursive generator that will generate many different, often nested, values

any-equatable clj/s

Like any, but only generates objects that can be equal to other objects (e.g., do not contain a NaN)

any-printable clj/s

Like any, but avoids characters that the shell will interpret as actions, like 7 and 14 (bell and alternate character set command)

any-printable-equatable clj/s

Like any, but avoids characters that the shell will interpret as actions, like 7 and 14 (bell and alternate character set command), and only generates objects that can be equal to other objects (e.g., do not contain a NaN)

big-ratio clj

Generates a ratio (or integer) using gen/size-bounded-bigint. Shrinks toward simpler ratios, which may be larger or smaller.

bind clj/s

(bind generator f)

Creates a new generator that passes the result of gen into function f. f should return a new generator. This allows you to create new generators that depend on the value of other generators. For example, to create a generator of permutations which first generates a num-elements and then generates a shuffling of (range num-elements):

(gen/bind gen/nat
          ;; this function takes a value generated by
          ;; the generator above and returns a new generator
          ;; which shuffles the collection returned by `range`
          (fn [num-elements]
            (gen/shuffle (range num-elements))))

Also see gen/let for a macro with similar functionality.

boolean clj/s

Generates one of true or false. Shrinks to false.

byte clj

Generates java.lang.Bytes, using the full byte-range.

bytes clj

Generates byte-arrays.

char clj/s

Generates character from 0-255.

char-alpha clj/s

Generates alpha characters.

char-alpha-numeric clj/s deprecated

Deprecated - use char-alphanumeric instead.

Generates alphanumeric characters.

char-alphanumeric clj/s

Generates alphanumeric characters.

char-ascii clj/s

Generates only ascii characters.

choose clj/s≠

(choose lower upper)

clj

Creates a generator that generates integers uniformly in the range lower to upper, inclusive.

(gen/sample (gen/choose 200 800))
=> (331 241 593 339 643 718 688 473 247 694)

cljs

Creates a generator that generates integer numbers uniformly in the range lower to upper, inclusive.

(gen/sample (gen/choose 200 800))
=> (331 241 593 339 643 718 688 473 247 694)

container-type clj/s

(container-type inner-type)

double clj/s

Generates 64-bit floating point numbers from the entire range, including +/- infinity and NaN. Use double* for more control.

double* clj/s

(double* {:keys [infinite? NaN? min max] :or {infinite? true NaN? true}})

Generates a 64-bit floating point number. Options:

:infinite? - whether +/- infinity can be generated (default true) :NaN? - whether NaN can be generated (default true) :min - minimum value (inclusive, default none) :max - maximum value (inclusive, default none)

Note that the min/max options must be finite numbers. Supplying a min precludes -Infinity, and supplying a max precludes +Infinity.

elements clj/s

(elements coll)

Creates a generator that randomly chooses an element from coll.

(gen/sample (gen/elements [:foo :bar :baz])) => (:foo :baz :baz :bar :foo :foo :bar :bar :foo :bar)

fmap clj/s

(fmap f gen)

Returns a generator like gen but with values transformed by f. E.g.:

(gen/sample (gen/fmap str gen/nat))
=> ("0" "1" "0" "1" "4" "3" "6" "6" "4" "2")

Also see gen/let for a macro with similar functionality.

frequency clj/s

(frequency pairs)

Creates a generator that chooses a generator from pairs based on the provided likelihoods. The likelihood of a given generator being chosen is its likelihood divided by the sum of all likelihoods. Shrinks toward choosing an earlier generator, as well as shrinking the value generated by the chosen generator.

Examples:

(gen/sample (gen/frequency [[5 gen/small-integer] [3 (gen/vector gen/small-integer)] [2 gen/boolean]]))
=> (true [] -1 [0] [1 -4 -4 1] true 4 [] 6 true)

generate clj/s

(generate generator)

(generate generator size)

(generate generator size seed)

Returns a single sample value from the generator.

Note that this function is a dev helper and is not meant to be used to build other generators.

Optional args:

• size: the abstract size parameter, defaults to 30
• seed: the seed for the random number generator, an integer

Generator clj/s

generator? clj/s

(generator? x)

Test if x is a generator. Generators should be treated as opaque values.

hash-map clj/s

(hash-map & kvs)

Like clojure.core/hash-map, except the values are generators. Returns a generator that makes maps with the supplied keys and values generated using the supplied generators.

(gen/sample (gen/hash-map :a gen/boolean :b gen/nat))
=> ({:a false, :b 0}
    {:a true,  :b 1}
    {:a false, :b 2}
    {:a true,  :b 2}
    {:a false, :b 4}
    {:a false, :b 2}
    {:a true,  :b 3}
    {:a true,  :b 4}
    {:a false, :b 1}
    {:a false, :b 0})

int clj/s deprecated

Deprecated - use gen/small-integer instead.

Generates a positive or negative integer bounded by the generator's size parameter.

keyword clj/s

Generates keywords without namespaces.

keyword-ns clj/s

Generates keywords with namespaces.

large-integer clj/s

Generates a platform-native integer from the full available range (in clj, 64-bit Longs, and in cljs, numbers between -(2^53 - 1) and (2^53 - 1)).

Use large-integer* for more control.

large-integer* clj/s

(large-integer* {:keys [min max]})

Like large-integer, but accepts options:

:min the minimum integer (inclusive) :max the maximum integer (inclusive)

Both :min and :max are optional.

(gen/sample (gen/large-integer* {:min 9000 :max 10000}))
=> (9000 9001 9001 9002 9000 9003 9006 9030 9005 9044)

let clj/s macro

(let bindings & body)

Macro for building generators using values from other generators. Uses a binding vector with the same syntax as clojure.core/let, where the right-hand side of the binding pairs are generators, and the left-hand side are names (or destructuring forms) for generated values.

Subsequent generator expressions can refer to the previously bound values, in the same way as clojure.core/let.

The body of the let can be either a value or a generator, and does the expected thing in either case. In this way let provides the functionality of both bind and fmap.

Examples:

(gen/let [strs (gen/not-empty (gen/list gen/string)) s (gen/elements strs)] {:some-strings strs :one-of-those-strings s})

;; generates collections of "users" that have integer IDs ;; from 0...N-1, but are in a random order (gen/let [users (gen/list (gen/hash-map :name gen/string-ascii :age gen/nat))] (->> users (map #(assoc %2 :id %1) (range)) (gen/shuffle)))

list clj/s

(list generator)

Like vector, but generates lists.

list-distinct clj/s

(list-distinct gen)

(list-distinct gen opts)

Generates a list of elements from the given generator, with the guarantee that the elements will be distinct.

If the generator cannot or is unlikely to produce enough distinct elements, this generator will fail in the same way as such-that.

Available options:

:num-elements the fixed size of generated list :min-elements the min size of generated list :max-elements the max size of generated list :max-tries the number of times the generator will be tried before failing when it does not produce distinct elements (default 10) :ex-fn a function of one arg that will be called if test.check cannot generate enough distinct values; it will be passed a map with :gen, :num-elements, and :max-tries and should return an exception

list-distinct-by clj/s

(list-distinct-by key-fn gen)

(list-distinct-by key-fn gen opts)

Generates a list of elements from the given generator, with the guarantee that (map key-fn the-list) will be distinct.

If the generator cannot or is unlikely to produce enough distinct elements, this generator will fail in the same way as such-that.

Available options:

:num-elements the fixed size of generated list :min-elements the min size of generated list :max-elements the max size of generated list :max-tries the number of times the generator will be tried before failing when it does not produce distinct elements (default 10) :ex-fn a function of one arg that will be called if test.check cannot generate enough distinct values; it will be passed a map with :gen, :num-elements, and :max-tries and should return an exception

map clj/s

(map key-gen val-gen)

(map key-gen val-gen opts)

Creates a generator that generates maps, with keys chosen from key-gen and values chosen from val-gen.

If the key generator cannot or is unlikely to produce enough distinct elements, this generator will fail in the same way as such-that.

Available options:

:num-elements the fixed size of generated maps :min-elements the min size of generated maps :max-elements the max size of generated maps :max-tries the number of times the generator will be tried before failing when it does not produce distinct elements (default 10) :ex-fn a function of one arg that will be called if test.check cannot generate enough distinct keys; it will be passed a map with :gen (the key-gen), :num-elements, and :max-tries and should return an exception

nat clj/s

Generates non-negative integers bounded by the generator's size parameter. Shrinks to zero.

neg-int clj/s deprecated

Deprecated - use (gen/fmap - gen/nat) instead (see also gen/large-integer).

(this generator, despite its name, can generate 0)

Generates nonpositive integers bounded by the generator's size parameter.

no-shrink clj/s

(no-shrink gen)

Creates a new generator that is just like gen, except does not shrink at all. This can be useful when shrinking is taking a long time or is not applicable to the domain.

not-empty clj/s

(not-empty gen)

Modifies a generator so that it doesn't generate empty collections.

Examples:

;; generate a vector of booleans, but never the empty vector
(gen/sample (gen/not-empty (gen/vector gen/boolean)))
=> ([false]
    [false false]
    [false false]
    [false false false]
    [false false false false]
    [false true true]
    [true false false false]
    [true]
    [true true true false false true false]
    [false true true true false true true true false])

one-of clj/s

(one-of generators)

Creates a generator that randomly chooses a value from the list of provided generators. Shrinks toward choosing an earlier generator, as well as shrinking the value generated by the chosen generator.

(gen/sample (gen/one-of [gen/small-integer gen/boolean (gen/vector gen/small-integer)]))
=> (true [] -1 [0] [1 -4 -4 1] true 4 [] 6 true)

pos-int clj/s deprecated

Deprecated - use gen/nat instead (see also gen/large-integer).

(this generator, despite its name, can generate 0)

Generates nonnegative integers bounded by the generator's size parameter.

ratio clj/s

Generates a small ratio (or integer) using gen/small-integer. Shrinks toward simpler ratios, which may be larger or smaller.

recursive-gen clj/s

(recursive-gen container-gen-fn scalar-gen)

This is a helper for writing recursive (tree-shaped) generators. The first argument should be a function that takes a generator as an argument, and produces another generator that 'contains' that generator. The vector function in this namespace is a simple example. The second argument is a scalar generator, like boolean. For example, to produce a tree of booleans:

(gen/recursive-gen gen/vector gen/boolean)

Vectors or maps either recurring or containing booleans or integers:

(gen/recursive-gen (fn [inner] (gen/one-of [(gen/vector inner) (gen/map inner inner)])) (gen/one-of [gen/boolean gen/small-integer]))

Note that raw scalar values will be generated as well. To prevent this, you can wrap the returned generator with the function passed as the first arg, e.g.:

(gen/vector (gen/recursive-gen gen/vector gen/boolean))

resize clj/s

(resize n generator)

Creates a new generator with size always bound to n.

(gen/sample (gen/set (gen/resize 200 gen/double))) => (#{} #{-4.994772362980037E147} #{-4.234418056487335E-146} #{} #{} #{} #{NaN} #{8.142414100982609E-63} #{-3.58429955903876E-159 2.8563794617604296E-154 4.1021360195776005E-100 1.9084564045332549E-38} #{-2.1582818131881376E83 -5.8460065493236117E48 9.729260993803226E166})

return clj/s

(return value)

Creates a generator that always returns value, and never shrinks. You can think of this as the constantly of generators. E.g.:

(gen/sample (gen/return 42))
=> (42 42 42 42 42 42 42 42 42 42)

s-neg-int clj/s deprecated

Deprecated - use (gen/fmap (comp dec -) gen/nat) instead (see also gen/large-integer).

Generates negative integers bounded by the generator's size + 1

s-pos-int clj/s deprecated

Deprecated - use (gen/fmap inc gen/nat) instead (see also gen/large-integer).

Generates positive integers bounded by the generator's size + 1

sample clj/s

(sample generator)

(sample generator num-samples)

Return a sequence of num-samples (default 10) realized values from generator.

The sequence starts with small values from the generator, which probably do not reflect the variety of values that will be generated during a longer test run.

Note that this function is a dev helper and is not meant to be used to build other generators.

sample-seq clj/s

(sample-seq generator)

(sample-seq generator max-size)

Returns an infinite sequence of realized values from generator.

Note that this function is a dev helper and is not meant to be used to build other generators.

scale clj/s

(scale f generator)

Creates a new generator that modifies the size parameter by the given function. Intended to support generators with sizes that need to grow at different rates compared to the normal linear scaling.

(gen/sample (gen/tuple (gen/scale #(/ % 10) gen/nat)
                       gen/nat
                       (gen/scale #(* % 10) gen/nat)))
=> ([0 0 0]  [0 1 2]  [0 2 13] [0 1 6]  [0 1 23]
    [0 2 42] [0 1 26] [0 1 12] [0 1 12] [0 0 3])

set clj/s

(set gen)

(set gen opts)

Generates a set of elements from the given generator.

If the generator cannot or is unlikely to produce enough distinct elements, this generator will fail in the same way as such-that.

Available options:

:num-elements the fixed size of generated set :min-elements the min size of generated set :max-elements the max size of generated set :max-tries the number of times the generator will be tried before failing when it does not produce distinct elements (default 10) :ex-fn a function of one arg that will be called if test.check cannot generate enough distinct values; it will be passed a map with :gen, :num-elements, and :max-tries and should return an exception

shrink-2 clj/s

(shrink-2 gen)

Creates a new generator like gen, but will consider nodes for shrinking even if their parent passes the test (up to one additional level).

shuffle clj/s

(shuffle coll)

Creates a generator that generates random permutations of coll. Shrinks toward the original collection: coll. coll will be coerced to a vector.

simple-type clj/s

Generates a variety of scalar types.

simple-type-equatable clj/s

Like gen/simple-type, but only generates objects that can be equal to other objects (e.g., not a NaN).

simple-type-printable clj/s

Generates a variety of scalar types, with printable strings.

simple-type-printable-equatable clj/s

Like gen/simple-type-printable, but only generates objects that can be equal to other objects (e.g., not a NaN).

size-bounded-bigint clj

Generates an integer (long or bigint) bounded exclusively by ±2^(6*size).

sized clj/s

(sized sized-gen)

Creates a generator that depends on the size parameter. sized-gen is a function that takes an integer and returns a generator.

Examples:

;; generates vectors of booleans where the length always exactly
;; matches the `size` parameter
(gen/sample (gen/sized (fn [size] (gen/vector gen/boolean size))))
=> ([]
    [false]
    [true true]
    [false true false]
    [false true true true]
    [false false true true false]
    [false true false true true false]
    [true false true true true false false]
    [true true false false false true false false]
    [false false false true true false true false true])

small-integer clj/s

Generates a positive or negative integer bounded by the generator's size parameter. Shrinks to zero.

sorted-set clj/s

(sorted-set gen)

(sorted-set gen opts)

Generates a sorted set of elements from the given generator.

If the generator cannot or is unlikely to produce enough distinct elements, this generator will fail in the same way as such-that.

Available options:

:num-elements the fixed size of generated set :min-elements the min size of generated set :max-elements the max size of generated set :max-tries the number of times the generator will be tried before failing when it does not produce distinct elements (default 10) :ex-fn a function of one arg that will be called if test.check cannot generate enough distinct values; it will be passed a map with :gen, :num-elements, and :max-tries and should return an exception

string clj/s

Generates strings. May generate unprintable characters.

string-alpha-numeric clj/s deprecated

Deprecated - use string-alphanumeric instead.

Generates alphanumeric strings.

string-alphanumeric clj/s

Generates alphanumeric strings.

string-ascii clj/s

Generates ascii strings.

such-that clj/s

(such-that pred gen)

(such-that pred gen max-tries-or-opts)

Creates a generator that generates values from gen that satisfy predicate pred. Care is needed to ensure there is a high chance gen will satisfy pred. By default, such-that will try 10 times to generate a value that satisfies the predicate. If no value passes this predicate after this number of iterations, a runtime exception will be thrown. Note also that each time such-that retries, it will increase the size parameter.

Examples:

;; generate non-empty vectors of integers
;; (note, gen/not-empty does exactly this)
(gen/such-that not-empty (gen/vector gen/small-integer))

You can customize such-that by passing an optional third argument, which can either be an integer representing the maximum number of times test.check will try to generate a value matching the predicate, or a map:

:max-tries  positive integer, the maximum number of tries (default 10)
:ex-fn      a function of one arg that will be called if test.check cannot
            generate a matching value; it will be passed a map with `:gen`,
            `:pred`, and `:max-tries` and should return an exception

symbol clj/s

Generates symbols without namespaces.

symbol-ns clj/s

Generates symbols with namespaces.

tuple clj/s

(tuple & generators)

Creates a generator that returns a vector, whose elements are chosen from the generators in the same position. The individual elements shrink according to their generator, but the vector will never shrink in count.

Examples:

(def t (tuple gen/small-integer gen/boolean))
(sample t)
;; => ([1 true] [2 true] [2 false] [1 false] [0 true] [-2 false] [-6 false]
;; =>  [3 true] [-4 false] [9 true]))

uuid clj/s

Generates a random type-4 UUID. Does not shrink.

vector clj/s

(vector generator)

(vector generator num-elements)

(vector generator min-elements max-elements)

Creates a generator of vectors whose elements are chosen from generator. The count of the vector will be bounded by the size generator parameter.

vector-distinct clj/s

(vector-distinct gen)

(vector-distinct gen opts)

Generates a vector of elements from the given generator, with the guarantee that the elements will be distinct.

If the generator cannot or is unlikely to produce enough distinct elements, this generator will fail in the same way as such-that.

Available options:

:num-elements the fixed size of generated vectors :min-elements the min size of generated vectors :max-elements the max size of generated vectors :max-tries the number of times the generator will be tried before failing when it does not produce distinct elements (default 10) :ex-fn a function of one arg that will be called if test.check cannot generate enough distinct values; it will be passed a map with :gen, :num-elements, and :max-tries and should return an exception

vector-distinct-by clj/s

(vector-distinct-by key-fn gen)

(vector-distinct-by key-fn gen opts)

Generates a vector of elements from the given generator, with the guarantee that (map key-fn the-vector) will be distinct.

If the generator cannot or is unlikely to produce enough distinct elements, this generator will fail in the same way as such-that.

Available options:

:num-elements the fixed size of generated vectors :min-elements the min size of generated vectors :max-elements the max size of generated vectors :max-tries the number of times the generator will be tried before failing when it does not produce distinct elements (default 10) :ex-fn a function of one arg that will be called if test.check cannot generate enough distinct values; it will be passed a map with :gen, :num-elements, and :max-tries and should return an exception