kotest-assertions / io.kotest.properties / Gen

Gen

interface Gen<T>
Deprecated: Deprecated and will be removed in 5.0. Migrate to the new property test classes in 4.0

A Generator, or Gen is responsible for generating data to be used in property testing. Each generator will generate data for a specific type .

The idea behind property testing is the testing framework will automatically test a range of different values, including edge cases and random values.

There are two types of values to consider.

The first are values that should always be included - those edge cases values which are common sources of bugs. For example, a generator for Ints should always include values like zero, minus 1, positive 1, Int.MAX_VALUE and Int.MIN_VALUE.

Another example would be for a generator for enums. That should include all the values of the enum to ensure each value is tested.

The second set of values are random values, which are used to give us a greater breadth of values tested. The Int generator example should return a random int from across the entire integer range.

Functions

concat

Returns a new [Gen] which will return the values from this gen and only once values of this gen exhaust it will return the values from the supplied gen. The supplied gen must be a subtype of the type of this gen.

open fun <U : T> concat(gen: Gen<U>): Gen<T>

constants

Returns the values that should always be used if this generator is to give complete coverage.

abstract fun constants(): Iterable<T>

filter

Create a new Gen by filtering the output of this gen.

open fun filter(pred: (T) -> Boolean): Gen<T>

filterNot

open fun filterNot(f: (T) -> Boolean): Gen<T>

flatMap

Create a new Gen by mapping the output of this gen.

open fun <U> flatMap(f: (T) -> Gen<U>): Gen<U>

map

Create a new Gen by mapping the output of this gen.

open fun <U> map(f: (T) -> U): Gen<U>

merge

Returns a new [Gen] which will return the values from this gen and the values of the supplied gen together. The supplied gen must be a subtype of the type of this gen.

open fun <U : T> merge(gen: Gen<U>): Gen<T>

orNull

Create a new Gen which will return the values of this gen plus null.

open fun orNull(): Gen<T?>

random

Generate a random sequence of type T, that is compatible with the constraints of this generator.

abstract fun random(seed: Long? = null): Sequence<T>

shrinker

open fun shrinker(): Shrinker<T>?

Extension Functions

assertAll

fun <A> Gen<A>.assertAll(iterations: Int = 1000, fn: PropertyContext.(a: A) -> Unit): Unit
fun <A> Gen<A>.assertAll(iterations: Int = 1000, fn: PropertyContext.(a0: A, a1: A) -> Unit): Unit
fun <A> Gen<A>.assertAll(iterations: Int = 1000, fn: PropertyContext.(a0: A, a1: A, a2: A) -> Unit): Unit
fun <A> Gen<A>.assertAll(iterations: Int = 1000, fn: PropertyContext.(a0: A, a1: A, a2: A, a3: A) -> Unit): Unit
fun <A> Gen<A>.assertAll(iterations: Int = 1000, fn: PropertyContext.(a0: A, a1: A, a2: A, a3: A, a4: A) -> Unit): Unit
fun <A> Gen<A>.assertAll(iterations: Int = 1000, fn: PropertyContext.(a0: A, a1: A, a2: A, a3: A, a4: A, a5: A) -> Unit): Unit

assertNone

fun <A> Gen<A>.assertNone(iterations: Int = 1000, fn: PropertyContext.(a0: A) -> Unit): Unit
fun <A> Gen<A>.assertNone(iterations: Int = 1000, fn: PropertyContext.(a0: A, a1: A) -> Unit): Unit
fun <A> Gen<A>.assertNone(iterations: Int = 1000, fn: PropertyContext.(a0: A, a1: A, a2: A) -> Unit): Unit
fun <A> Gen<A>.assertNone(iterations: Int = 1000, fn: PropertyContext.(a0: A, a1: A, a2: A, a3: A) -> Unit): Unit
fun <A> Gen<A>.assertNone(iterations: Int = 1000, fn: PropertyContext.(a0: A, a1: A, a2: A, a3: A, a4: A) -> Unit): Unit
fun <A> Gen<A>.assertNone(iterations: Int = 1000, fn: PropertyContext.(a0: A, a1: A, a2: A, a3: A, a4: A, a5: A) -> Unit): Unit

filterIsInstance

Create a new Gen by keeping only instances of U generated by this gen. This is useful if you have a type hierarchy and only want to retain a particular subtype.

fun <T, U : T> Gen<T>.filterIsInstance(): Gen<U>

forAll

fun <A> Gen<A>.forAll(iterations: Int = 1000, fn: PropertyContext.(a0: A) -> Boolean): Unit
fun <A> Gen<A>.forAll(iterations: Int = 1000, fn: PropertyContext.(a0: A, a1: A) -> Boolean): Unit
fun <A> Gen<A>.forAll(iterations: Int = 1000, fn: PropertyContext.(a0: A, a1: A, a2: A) -> Boolean): Unit
fun <A> Gen<A>.forAll(iterations: Int = 1000, fn: PropertyContext.(a0: A, a1: A, a2: A, a3: A) -> Boolean): Unit
fun <A> Gen<A>.forAll(iterations: Int = 1000, fn: PropertyContext.(a0: A, a1: A, a2: A, a3: A, a4: A) -> Boolean): Unit
fun <A> Gen<A>.forAll(iterations: Int = 1000, fn: PropertyContext.(a0: A, a1: A, a2: A, a3: A, a4: A, a5: A) -> Boolean): Unit

forNone

fun <A> Gen<A>.forNone(iterations: Int = 1000, fn: PropertyContext.(a0: A) -> Boolean): Unit
fun <A> Gen<A>.forNone(iterations: Int = 1000, fn: PropertyContext.(a0: A, a1: A) -> Boolean): Unit
fun <A> Gen<A>.forNone(iterations: Int = 1000, fn: PropertyContext.(a0: A, a1: A, a2: A) -> Boolean): Unit
fun <A> Gen<A>.forNone(iterations: Int = 1000, fn: PropertyContext.(a0: A, a1: A, a2: A, a3: A) -> Boolean): Unit
fun <A> Gen<A>.forNone(iterations: Int = 1000, fn: PropertyContext.(a0: A, a1: A, a2: A, a3: A, a4: A) -> Boolean): Unit
fun <A> Gen<A>.forNone(iterations: Int = 1000, fn: PropertyContext.(a0: A, a1: A, a2: A, a3: A, a4: A, a5: A) -> Boolean): Unit

next

Draws a random value from this generator

fun <T> Gen<T>.next(predicate: (T) -> Boolean = { true }, seed: Long?): Tfun <T> Gen<T>.next(predicate: (T) -> Boolean = { true }): T

take

Draws amount values from this generator

fun <T> Gen<T>.take(amount: Int, seed: Long? = null): List<T>

uniqueRandoms

Creates a sequence of unique values from the contents of random, using seed to seed the random function.

fun <T> Gen<T>.uniqueRandoms(seed: Long? = null): Sequence<T>

verifyAll

fun <A> Gen<A>.verifyAll(iterations: Int = 1000, fn: PropertyContext.(a0: A) -> Boolean): Unit
fun <A> Gen<A>.verifyAll(iterations: Int = 1000, fn: PropertyContext.(a0: A, a1: A, a2: A) -> Boolean): Unit
fun <A> Gen<A>.verifyAll(iterations: Int = 1000, fn: PropertyContext.(a0: A, a1: A, a2: A, a3: A) -> Boolean): Unit
fun <A> Gen<A>.verifyAll(iterations: Int = 1000, fn: PropertyContext.(a0: A, a1: A, a2: A, a3: A, a4: A) -> Boolean): Unit
fun <A> Gen<A>.verifyAll(iterations: Int = 1000, fn: PropertyContext.(a0: A, a1: A, a2: A, a3: A, a4: A, a5: A) -> Boolean): Unit

verifyNone

fun <A> Gen<A>.verifyNone(iterations: Int = 1000, fn: PropertyContext.(a0: A) -> Boolean): Unit
fun <A> Gen<A>.verifyNone(iterations: Int = 1000, fn: PropertyContext.(a0: A, a1: A) -> Boolean): Unit
fun <A> Gen<A>.verifyNone(iterations: Int = 1000, fn: PropertyContext.(a0: A, a1: A, a2: A) -> Boolean): Unit
fun <A> Gen<A>.verifyNone(iterations: Int = 1000, fn: PropertyContext.(a0: A, a1: A, a2: A, a3: A) -> Boolean): Unit
fun <A> Gen<A>.verifyNone(iterations: Int = 1000, fn: PropertyContext.(a0: A, a1: A, a2: A, a3: A, a4: A) -> Boolean): Unit
fun <A> Gen<A>.verifyNone(iterations: Int = 1000, fn: PropertyContext.(a0: A, a1: A, a2: A, a3: A, a4: A, a5: A) -> Boolean): Unit

Companion Object Extension Functions

bigInteger

fun Gen.Companion.bigInteger(maxNumBits: Int = 32): Gen<BigInteger>

bind

fun <A, T> Gen.Companion.bind(gena: Gen<A>, createFn: (A) -> T): Gen<T>
fun <A, B, T> Gen.Companion.bind(gena: Gen<A>, genb: Gen<B>, createFn: (A, B) -> T): Gen<T>
fun <A, B, C, T> Gen.Companion.bind(gena: Gen<A>, genb: Gen<B>, genc: Gen<C>, createFn: (A, B, C) -> T): Gen<T>
fun <A, B, C, D, T> Gen.Companion.bind(gena: Gen<A>, genb: Gen<B>, genc: Gen<C>, gend: Gen<D>, createFn: (A, B, C, D) -> T): Gen<T>
fun <A, B, C, D, E, T> Gen.Companion.bind(gena: Gen<A>, genb: Gen<B>, genc: Gen<C>, gend: Gen<D>, gene: Gen<E>, createFn: (A, B, C, D, E) -> T): Gen<T>
fun <A, B, C, D, E, F, T> Gen.Companion.bind(gena: Gen<A>, genb: Gen<B>, genc: Gen<C>, gend: Gen<D>, gene: Gen<E>, genf: Gen<F>, createFn: (A, B, C, D, E, F) -> T): Gen<T>
fun <A, B, C, D, E, F, G, T> Gen.Companion.bind(gena: Gen<A>, genb: Gen<B>, genc: Gen<C>, gend: Gen<D>, gene: Gen<E>, genf: Gen<F>, geng: Gen<G>, createFn: (A, B, C, D, E, F, G) -> T): Gen<T>

bool

Returns both boolean values

fun Gen.Companion.bool(): Gen<Boolean>

byte

Returns a stream of values where each value is a randomly chosen Byte. The values always returned include the following edge cases: [Byte.MIN_VALUE, Byte.MAX_VALUE, 0]

fun Gen.Companion.byte(): Gen<Byte>

char

Returns a stream of randomly-chosen Chars. Custom characters can be generated by providing CharRanges. Distribution will be even across the ranges of Chars. For example: Gen.char('A'..'C', 'D'..'E') Ths will choose A, B, C, D, and E each 20% of the time.

fun Gen.Companion.char(range: CharRange, vararg ranges: CharRange): Gen<Char>

Returns a stream of randomly-chosen Chars. Custom characters can be generated by providing a list of CharRanges. Distribution will be even across the ranges of Chars. For example: Gen.char(listOf('A'..'C', 'D'..'E') Ths will choose A, B, C, D, and E each 20% of the time.

fun Gen.Companion.char(ranges: List<CharRange> = CharSets.BASIC_LATIN): Gen<Char>

choose

Returns a stream of values, where each value is a random Int between the given min and max.

fun Gen.Companion.choose(min: Int, max: Int): Gen<Int>

Returns a stream of values, where each value is a Long between the given min and max.

fun Gen.Companion.choose(min: Long, max: Long): Gen<Long>

Returns a stream of values based on weights:

fun <T : Any> Gen.Companion.choose(a: Pair<Int, T>, b: Pair<Int, T>, vararg cs: Pair<Int, T>): Gen<T>

constant

Returns a [Gen] which always returns the same value.

fun <T> Gen.Companion.constant(value: T): Gen<T>

create

Returns a stream of values, where each value is generated from the given function

fun <T> Gen.Companion.create(fn: () -> T): Gen<T>

default

fun <T> Gen.Companion.default(): Gen<T>

double

Returns a stream of values where each value is a randomly chosen Double.

fun Gen.Companion.double(): Gen<Double>

duration

Generates a stream of random Durations

fun Gen.Companion.duration(maxDuration: Duration = Duration.ofDays(10)): Gen<Duration>

enum

fun <T : Enum<T>> Gen.Companion.enum(): Gen<T>

factors

fun Gen.Companion.factors(k: Int): Gen<Int>

file

Returns a stream of values where each value is a randomly chosen created File object. The file objects do not necessarily exist on disk.

fun Gen.Companion.file(): Gen<File>

Returns a stream of values where each value is a randomly chosen File object from given directory. If the Directory does not exist, an empty sequence will be returned instead. If recursive is true(default value is false) it gives files from inner directories as well recursively.

fun Gen.Companion.file(directoryName: String, recursive: Boolean = false): Gen<File>

float

Returns a stream of values where each value is a randomly chosen Float.

fun Gen.Companion.float(): Gen<Float>

forClassName

fun Gen.Companion.forClassName(className: String): Gen<*>

from

Adapts a list into a generator, where random values will be picked. May not choose every item in the list.

fun <T> Gen.Companion.from(values: List<T>): Gen<T>fun <T> Gen.Companion.from(values: Array<T>): Gen<T>

int

Returns a stream of values where each value is a randomly chosen Int. The values always returned include the following edge cases: [Int.MIN_VALUE, Int.MAX_VALUE, 0, 1, -1]

fun Gen.Companion.int(): Gen<Int>

list

Returns a stream of values, where each value is a list of values generated by the underlying generator.

fun <T> Gen.Companion.list(gen: Gen<T>, maxSize: Int = 100): Gen<List<T>>

localDate

Generates a stream of random LocalDates

fun Gen.Companion.localDate(minYear: Int = 1970, maxYear: Int = 2030): Gen<LocalDate>

localDateTime

Generates a stream of random LocalDateTimes

fun Gen.Companion.localDateTime(minYear: Int = 1970, maxYear: Int = 2030): Gen<LocalDateTime>

localTime

Generates a stream of random LocalTimes

fun Gen.Companion.localTime(): Gen<LocalTime>

long

Returns a stream of values where each value is a randomly chosen long. The values returned always include the following edge cases: [Long.MIN_VALUE, Long.MAX_VALUE, 0, 1, -1]

fun Gen.Companion.long(): Gen<Long>

map

Returns a stream of values, where each value is a Map, which contains keys and values generated from the underlying generators.

fun <K, V> Gen.Companion.map(genK: Gen<K>, genV: Gen<V>, maxSize: Int = 100): Gen<Map<K, V>>fun <K, V> Gen.Companion.map(gen: Gen<Pair<K, V>>, maxSize: Int = 100): Gen<Map<K, V>>

multiples

fun Gen.Companion.multiples(k: Int, max: Int): Gen<Int>

nats

Returns a stream of values where each value is a randomly chosen natural number. The values returned always include the following edge cases: Int.MAX_VALUE

fun Gen.Companion.nats(): Gen<Int>

negativeDoubles

fun Gen.Companion.negativeDoubles(): Gen<Double>

negativeIntegers

Returns a stream of values where each value is a randomly chosen negative value. The values returned always include the following edge cases: Int.MIN_VALUE

fun Gen.Companion.negativeIntegers(): Gen<Int>

numericDoubles

Returns a Gen which is the same as Gen.double but does not include +INFINITY, -INFINITY or NaN.

fun Gen.Companion.numericDoubles(from: Double = Double.MIN_VALUE, to: Double = Double.MAX_VALUE): Gen<Double>

numericFloats

Returns a Gen which is the same as Gen.float but does not include +INFINITY, -INFINITY or NaN.

fun Gen.Companion.numericFloats(from: Float = Float.MIN_VALUE, to: Float = Float.MAX_VALUE): Gen<Float>

oneOf

fun <A> Gen.Companion.oneOf(vararg gens: Gen<out A>): Gen<A>

pair

Returns a stream of values, where each value is a pair generated by the underlying generators.

fun <K, V> Gen.Companion.pair(genK: Gen<K>, genV: Gen<V>): Gen<Pair<K, V>>

period

Generates a stream of random Periods

fun Gen.Companion.period(maxYear: Int = 10): Gen<Period>

positiveDoubles

fun Gen.Companion.positiveDoubles(): Gen<Double>

positiveIntegers

Returns a stream of values where each value is a randomly chosen positive value. The values returned always include the following edge cases: Int.MAX_VALUE

fun Gen.Companion.positiveIntegers(): Gen<Int>

regex

fun Gen.Companion.regex(regex: String): RegexpGen
fun Gen.Companion.regex(regex: Regex): RegexpGen

samples

Returns a Gen which returns the sample values in the same order as they are passed in, once all sample values are used it repeats elements from start.

fun <T> Gen.Companion.samples(vararg sampleValues: T): Gen<T>

set

Returns a stream of values, where each value is a set of values generated by the given generator.

fun <T> Gen.Companion.set(gen: Gen<T>, maxSize: Int = 100): Gen<Set<T>>

short

Returns a stream of values where each value is a randomly chosen Short. The values always returned include the following edge cases: [Short.MIN_VALUE, Short.MAX_VALUE, 0]

fun Gen.Companion.short(): Gen<Short>

string

Returns a stream of values where each value is a random printed string.

fun Gen.Companion.string(minSize: Int = 0, maxSize: Int = 100): Gen<String>

triple

Returns a [Gen] where each value is a [Triple] generated by a value from each of three supplied generators.

fun <A, B, C> Gen.Companion.triple(genA: Gen<A>, genB: Gen<B>, genC: Gen<C>): Gen<Triple<A, B, C>>

ubyte

Returns a stream of values where each value is a randomly chosen UByte. The values always returned include the following edge cases: [UByte.MIN_VALUE, UByte.MAX_VALUE]

fun Gen.Companion.ubyte(): Gen<Byte>

uint

Returns a stream of values where each value is a randomly chosen UInt. The values always returned include the following edge cases: [UInt.MIN_VALUE, UInt.MAX_VALUE]

fun Gen.Companion.uint(): Gen<UInt>

ulong

Returns a stream of values where each value is a randomly chosen ULong. The values returned always include the following edge cases: [ULong.MIN_VALUE, ULong.MAX_VALUE]

fun Gen.Companion.ulong(): Gen<ULong>

ushort

Returns a stream of values where each value is a randomly chosen UShort. The values always returned include the following edge cases: [UShort.MIN_VALUE, UShort.MAX_VALUE]

fun Gen.Companion.ushort(): Gen<UShort>

uuid

fun Gen.Companion.uuid(uuidVersion: UUIDVersion = UUIDVersion.V4, allowNilValue: Boolean = true): Gen<UUID>

Inheritors

BigIntegerGen

class BigIntegerGen : Gen<BigInteger>

RegexpGen

class RegexpGen : Gen<String>