org.scalacheck

Define an arbitrary generator for properties

The Arbitrary module defines implicit generator instances for common types.

The implicit definitions of Arbitrary provide type-directed Gens so they are available for properties, generators, or other definitions of Arbitrary.

ScalaCheck expects an implicit Arbitrary instance is in scope for Props that are defined with functions, like Prop.forAll and so on.

For instance, the definition for Arbitrary[Boolean] is used by Prop.forAll to automatically provide a Gen[Boolean] when one of the parameters is a Boolean:

Prop.forAll { (b: Boolean) =>
  b || !b
}

Thanks to Arbitrary, you don't need to provide an explicit Gen instance to Prop.forAll. For instance, this is unnecessary:

val genBool: Gen[Boolean] = Gen.oneOf(true,false)
Prop.forAll(genBool) { (b: Boolean) =>
  b || !b
}

Since an arbitrary Gen for Boolean is defined in Arbitrary, it can be summoned with Arbitrary.arbitrary in cases where you need to provide one explicitly:

val genBool: Gen[Boolean] = Arbitrary.arbitrary[Boolean]
val genSmallInt: Gen[Int] = Gen.choose(0, 9)
Prop.forAll(genBool, genSmallInt) { (b: Boolean, i: Int) =>
  i < 10 && b || !b
}

For a user-defined MyClass, writing the following requires that there exists an implicit Arbitrary[MyClass] instance:

Prop.forAll { (myClass: MyClass) =>
  ...
}

The implicit definition of Arbitrary[MyClass] would look like:

implicit val arbMyClass: Arbitrary[MyClass] = Arbitrary {
  ...
}

The factory method Arbitrary(...) expects a generator of type Gen[MyClass] then it will return an instance of Arbitrary[MyClass].

A generator produces values for Props

This module provides:

1. Definitions for non-arbitrary generators,

2. Factories to construct generators,

3. Methods to modify a generator, and

4. Various combinators for producing generators of values for more complex data types.

Explicit generators aren't required to write Props:

Prop.forAll { (n: Int) =>
  n == n
}

The Prop above is defined with parameters only and without an explicit generator, because generators are implicitly provided by Arbitrary for various data types.

However, it's not uncommon to need to write explicit custom generators:

val genInt: Gen[Int] = Gen.choose(1,10)
Prop.forAll(genInt) { (n: Int) =>
  1 <= n && n <= 10
}

This is a simple definition of a generator for booleans:

val genBool: Gen[Boolean] = Gen.oneOf(true,false)

The above definition isn't necessary, though. The same boolean generator is defined in Arbitrary as an implicit declaration for automatically parameterizing Props. Instead, use the generator that is defined in Arbitrary and available from the polymorphic method Arbitrary.arbitrary with an explicit type parameter:

val genBool: Gen[Boolean] = Arbitrary.arbitrary[Boolean]

Alternatively, this is a boolean generator, but one that always produces true:

val genBool = Gen.const(true)

This is a generator of booleans that is true at a 2-to-1 ratio:

val genBool = Gen.frequency(2 -> true, 1 -> false)

This is a boolean generator that will produce true 75% of the time:

val genBool = Gen.prob(0.75)

For more information on designing custom generators and the motivations for doing so, see chapter 6, Generators in Detail, of the book ScalaCheck: The Definitive Guide (2013) by Rickard Nilsson published by Artima Press.

This is an example of a custom generator for integers:

val genSmallInt: Gen[Int] = Gen.choose(-100,100)

This can be used to generate different collections of zero or more small integers:

val genListOfInts: Gen[List[Int]] = Gen.listOf(genSmallInt)

val genSeqOfInts: Gen[Seq[Int]] = Gen.someOf(-100 to 100)

val genVectorOfInts: Gen[Vector[Int]] = Gen.containerOf[Vector,Int](genSmallInt)

val genMap: Gen[Map[Int,Boolean]] = Gen.mapOf(Gen.zip(genSmallInt, genBool))

val genOptionalInt: Gen[Option[Int]] = Gen.option(genSmallInt)

Or collections of one or more small integers:

val genListOfInts: Gen[List[Int]] = Gen.nonEmptyListOf(genSmallInt)

val genSeqOfInts: Gen[Seq[Int]] = Gen.atLeastOne(-100 to 100)

val genVectorOfInts: Gen[Vector[Int]] = Gen.nonEmptyContainerOf[Vector,Int](genSmallInt)

val genMap: Gen[Map[Int,Boolean]] = Gen.nonEmptyMap(Gen.zip(genSmallInt, genBool))

val genOptionalInt: Gen[Option[Int]] = Gen.some(genSmallInt)

The class methods for Gen should be familiar with those in the Scala collections API:

• map - Apply a function to generated values

• flatMap - Apply a function that returns a generator

• filter - Use values that satisfy a predicate

The Gen class also supports for-comprehensions to compose complex generators:

val genPerson = for {
  firstName <- Gen.oneOf("Alan", "Ada", "Alonzo")
  lastName <- Gen.oneOf("Lovelace", "Turing", "Church")
  age <- Gen.choose(0,100) if (age >= 18)
} yield Person(firstName, lastName, age)

Constructors and factories for generators:

• const - Always generates a single value

• oneOf - Generate a value from a list of values

• atLeastOne - Generate a collection with at least one value from a list

• someOf - Generate a collection with zero or more values from a list

• choose - Generate numeric values in an (inclusive) range

• frequency - Choose from multiple values with a weighted distribution

Combinators of generators:

• buildableOf - Generates a collection with a generator

• buildableOfN - Generates a collection of at most n elements

• nonEmptyBuildableOf - Generates a non-empty collection

• containerOf - Generates a collection with a generator

• containerOfN - Generates a collection of at most n elements

• nonEmptyContainerOf - Generates a non-empty collection

• either - Generate a disjoint union of scala.util.Either

• infiniteLazyList - Generates an infinite lazy list

• infiniteStream - Generates an infinite stream

• listOf - Generates a list of random length

• listOfN - Generates a list of at most n elements

• nonEmptyListOf - Generates a non-empty list of random length.

• mapOf - Generates a scala.collection.Map

• mapOfN - Generates a scala.collection.Map with at most n elements

• nonEmptyMap - Generates a non-empty map of random length

• option - Generate values of scala.Some and scala.None

• pick - A generator that randomly picks n elements from a list

• sequence - Sequences generators.

• some - A generator of scala.Some

• someOf - A generator that picks a random number of elements from a list

• stringOf - Generate string of characters

• stringOfN - Generate string of at most n characters

• nonEmptyStringOf - Generate a non-empty string of characters

Methods for working with Gen internals:

• resize - Creates a resized version of a generator

• parameterized - Generator with the parameters

• size - Generate with the value of the default size parameter

• sized - Build a generator using the default size parameter

Methods for probabilistic generators:

• exponential - Generate numbers according to an exponential distribution

• gaussian - Generates numbers according to a Gaussian distribution

• geometric - Generates numbers according to a geometric distribution

• poisson - Generates numbers according to a Poisson distribution

• prob - Generates a boolean for the probability of true

Definitions for generating various, non-arbitrary, common values of strings and characters:

• alphaChar - Generates an alpha character

• alphaStr - Generates a string of alpha characters

• numChar - Generates a numerical character

• numStr - Generates a string of digits

• alphaNumChar - Generates an alphanumerical character

• alphaNumStr - Generates a string of alphanumerical characters

• alphaLowerChar - Generates a lower-case alpha character

• alphaLowerStr - Generates a string of lower-case alpha characters

• alphaUpperChar - Generates an upper-case alpha character

• alphaUpperStr - Generates a string of upper-case alpha characters

• asciiChar - Generates an ASCII character

• asciiStr - Generates a string of ASCII characters

• identifier - Generates an identifier

• uuid - Generates a UUID

• hexChar - Generates a character of a hexadecimal digit

• hexStr - Generates a string of hexadecimal digits

Definitions for generating arbitrary values of commonly used types in Scala are defined elsewhere, see Arbitrary.

There are a couple of factory methods that are for advanced uses of generators:

• delay - Generate a value of an expression by-name

• lzy - Lazily generate a value of an expression

• fail - Fail to generate any values of a type

• recursive - A fixed point generator

• resultOf - Generate values with a function or class

• zip - Generate tuples

Represents a collection of properties, with convenient methods for checking all properties at once.

Properties are added in the following way:

object MyProps extends Properties("MyProps") {
  property("myProp1") = forAll { (n:Int, m:Int) =>
    n+m == m+n
  }
}