Packages

Definition Classes: root

Definition Classes: root

ScalaTest's main traits, classes, and other members, including members supporting ScalaTest's DSL for the Scala interpreter.

Definition Classes: org

package prop

Scalatest support for Property-based testing.

Introduction to Property-based Testing

In traditional unit testing, you write tests that describe precisely what the test will do: create these objects, wire them together, call these functions, assert on the results, and so on. It is clear and deterministic, but also limited, because it only covers the exact situations you think to test. In most cases, it is not feasible to test all of the possible combinations of data that might arise in real-world use.

Property-based testing works the other way around. You describe properties -- rules that you expect your classes to live by -- and describe how to test those properties. The test system then generates relatively large amounts of synthetic data (with an emphasis on edge cases that tend to make things break), so that you can see if the properties hold true in these situations.

As a result, property-based testing is scientific in the purest sense: you are stating a hypothesis about how things should work (the property), and the system is trying to falsify that hypothesis. If the tests pass, that doesn't prove the property holds, but it at least gives you some confidence that you are probably correct.

Property-based testing is deliberately a bit random: while the edge cases get tried upfront, the system also usually generates a number of random values to try out. This makes things a bit non-deterministic -- each run will be tried with somewhat different data. To make it easier to debug, and to build regression tests, the system provides tools to re-run a failed test with precisely the same data.

Background

TODO: Bill should insert a brief section on QuickCheck, ScalaCheck, etc, and how this system is similar and different.

Using Property Checks

In order to use the tools described here, you should import this package:

import org.scalatest._
import org.scalatest.prop._

This library is designed to work well with the types defined in Scalactic, and some functions take types such as PosZInt as parameters. So it can also be helpful to import those with:

import org.scalactic.anyvals._

In order to call forAll, the function that actually performs property checks, you will need to either extend or import GeneratorDrivenPropertyChecks, like this:

class DocExamples extends FlatSpec with Matchers with GeneratorDrivenPropertyChecks {

There's nothing special about FlatSpec, though -- you may use any of ScalaTest's styles with property checks. GeneratorDrivenPropertyChecks extends CommonGenerators, so it also provides access to the many utilities found there.

What Does a Property Look Like?

Let's check a simple property of Strings -- that if you concatenate a String to itself, its length will be doubled:

"Strings" should "have the correct length when doubled" in {
  forAll { (s: String) =>
    val s2 = s * 2
    s2.length should equal (s.length * 2)
  }
}

(Note that the examples here are all using the FlatSpec style, but will work the same way with any of ScalaTest's styles.)

As the name of the tests suggests, the property we are testing is the length of a String that has been doubled.

The test begins with forAll. This is usually the way you'll want to begin property checks, and that line can be read as, "For all Strings, the following should be true".

The test harness will generate a number of Strings, with various contents and lengths. For each one, we compute s * 2. (* is a function on String, which appends the String to itself as many times as you specify.) And then we check that the length of the doubled String is twice the length of the original one.

Using Specific Generators

Let's try a more general version of this test, multiplying arbitrary Strings by arbitrary multipliers:

"Strings" should "have the correct length when multiplied" in {
  forAll { (s: String, n: PosZInt) =>
    val s2 = s * n.value
    s2.length should equal (s.length * n.value)
  }
}

Again, you can read the first line of the test as "For all Strings, and all non-negative Integers, the following should be true". (PosZInt is a type defined in Scalactic, which can be any positive integer, including zero. It is appropriate to use here, since multiplying a String by a negative number doesn't make sense.)

This intuitively makes sense, but when we try to run it, we get a JVM Out of Memory error! Why? Because the test system tries to test with the "edge cases" first, and one of the more important edge cases is Int.MaxValue. It is trying to multiply a String by that, which is far larger than the memory of even a big computer, and crashing.

So we want to constrain our test to sane values of n, so that it doesn't crash. We can do this by using more specific Generators.

When we write a forAll test like the above, ScalaTest has to generate the values to be tested -- the semi-random Strings, Ints and other types that you are testing. It does this by calling on an implicit Generator for the desired type. The Generator generates values to test, starting with the edge cases and then moving on to randomly-selected values.

ScalaTest has built-in Generators for many major types, including String and PosZInt, but these Generators are generic: they will try any value, including values that can break your test, as shown above. But it also provides tools to let you be more specific.

Here is the fixed version of the above test:

"Strings" should "have the correct length when multiplied" in {
  forAll(strings, posZIntsBetween(0, 1000))
  { (s: String, n: PosZInt) =>
    val s2 = s * n.value
    s2.length should equal (s.length * n.value)
  }
}

This is using a variant of forAll, which lets you specify the Generators to use instead of just picking the implicit one. CommonGenerators.strings is the built-in Generator for Strings, the same one you were getting implicitly. (The other built-ins can be found in CommonGenerators. They are mixed into GeneratorDrivenPropertyChecks, so they are readily available.)

But CommonGenerators.posZIntsBetween is a function that creates a Generator that selects from the given values. In this case, it will create a Generator that only creates numbers from 0 to 1000 -- small enough to not blow up our computer's memory. If you try this test, this runs correctly.

The moral of the story is that, while using the built-in Generators is very convenient, and works most of the time, you should think about the data you are trying to test, and pick or create a more-specific Generator when the test calls for it.

CommonGenerators contains many functions that are helpful in common cases. In particular:

xxsBetween (where xxs might be Int, Long, Float or most other significant numeric types) gives you a value of the desired type in the given range, as in the posZIntsBetween() example above.
CommonGenerators.specificValue and CommonGenerators.specificValues create Generators that produce either one specific value every time, or one of several values randomly. This is useful for enumerations and types that behave like enumerations.
CommonGenerators.evenly and CommonGenerators.frequency create higher-level Generators that call other Generators, either more or less equally or with a distribution you define.

Testing Your Own Types

Testing the built-in types isn't very interesting, though. Usually, you have your own types that you want to check the properties of. So let's build up an example piece by piece.

Say you have this simple type:

sealed trait Shape {
  def area: Double
}
case class Rectangle(width: Int, height: Int) extends Shape {
  require(width > 0)
  require(height > 0)
  def area: Double = width * height
}

Let's confirm a nice straightforward property that is surely true: that the area is greater than zero:

"Rectangles" should "have a positive area" in {
   forAll { (w: PosInt, h: PosInt) =>
     val rect = Rectangle(w, h)
     rect.area should be > 0.0
   }
 }

Note that, even though our class takes ordinary Ints as parameters (and checks the values at runtime), it is actually easier to generate the legal values using Scalactic's PosInt type.

This should work, right? Actually, it doesn't -- if we run it a few times, we quickly hit an error!

[info] Rectangles
[info] - should have a positive area *** FAILED ***
[info]   GeneratorDrivenPropertyCheckFailedException was thrown during property evaluation.
[info]    (DocExamples.scala:42)
[info]     Falsified after 2 successful property evaluations.
[info]     Location: (DocExamples.scala:42)
[info]     Occurred when passed generated values (
[info]       None = PosInt(399455539),
[info]       None = PosInt(703518968)
[info]     )
[info]     Init Seed: 1568878346200

TODO: fix the above error to reflect the better errors we should get when we merge in the code being forward-ported from 3.0.5.

Looking at it, we can see that the numbers being used are pretty large. What happens when we multiply them together?

scala> 399455539 * 703518968
res0: Int = -2046258840

We're hitting an Int overflow problem here: the numbers are too big to multiply together and still get an Int. So we have to fix our area function:

case class Rectangle(width: Int, height: Int) extends Shape {
  require(width > 0)
  require(height > 0)
  def area: Double = width.toLong * height.toLong
}

Now, when we run our property check, it consistently passes. Excellent -- we've caught a bug, because ScalaTest tried sufficiently large numbers.

Composing Your Own Generators

Doing things as shown above works, but having to generate the parameters and construct a Rectangle every time is a nuisance. What we really want is to create our own Generator that just hands us Rectangles, the same way we can do for PosInt. Fortunately, this is easy.

Generators can be composed in for comprehensions. So we can create our own Generator for Rectangle like this:

implicit val rectGenerator = for {
  w <- posInts
  h <- posInts
}
  yield Rectangle(w, h)

Taking that line by line:

w <- posInts

CommonGenerators.posInts is the built-in Generator for positive Ints. So this line puts a randomly-generated positive Int in w, and

h <- posInts

this line puts another one in h. Finally, this line:

yield Rectangle(w, h)

combines w and h to make a Rectangle.

That's pretty much all you need in order to build any normal case class -- just build it out of the Generators for the type of each field. (And if the fields are complex data structures themselves, build Generators for them the same way, until you are just using primitives.)

Now, our property check becomes simpler:

"Generated Rectangles" should "have a positive area" in {
   forAll { (rect: Rectangle) =>
     rect.area should be > 0.0
   }
 }

That's about as close to plain English as we can reasonably hope for!

Filtering Values with whenever()

Sometimes, not all of your generated values make sense for the property you want to check -- you know (via external information) that some of these values will never come up. In cases like this, you can create a custom Generator that only creates the values you do want, but it's often easier to just use Whenever.whenever. (Whenever is mixed into GeneratorDrivenPropertyChecks, so this is available when you need it.)

The Whenever.whenever function can be used inside of GeneratorDrivenPropertyChecks.forAll. It says that only the filtered values should be used, and anything else should be discarded. For example, look at this property:

"Fractions" should "get smaller when squared" in {
  forAll { (n: Float) =>
    whenever(n > 0 && n < 1) {
      (n * n) should be < n
    }
  }
}

We are testing a property of numbers less than 1, so we filter away everything that is not the numbers we want. This property check succeeds, because we've screened out the values that would make it fail.

Discard Limits

You shouldn't push Whenever.whenever too far, though. This system is all about trying random data, but if too much of the random data simply isn't usable, you can't get valid answers, and the system tracks that.

For example, consider this apparently-reasonable test:

"Space Chars" should "not also be letters" in {
  forAll { (c: Char) =>
    whenever (c.isSpaceChar) {
      assert(!c.isLetter)
    }
  }
}

Although the property is true, this test will fail with an error like this:

[info] Lowercase Chars
[info] - should upper-case correctly *** FAILED ***
[info]   Gave up after 0 successful property evaluations. 49 evaluations were discarded.
[info]   Init Seed: 1568855247784

Because the vast majority of Chars are not spaces, nearly all of the generated values are being discarded. As a result, the system gives up after a while. In cases like this, you usually should write a custom Generator instead.

The proportion of how many discards to permit, relative to the number of successful checks, is configuration-controllable. See GeneratorDrivenPropertyChecks for more details.

Randomization

The point of Generator is to create pseudo-random values for checking properties. But it turns out to be very inconvenient if those values are actually random -- that would mean that, when a property check fails occasionally, you have no good way to invoke that specific set of circumstances again for debugging. We want "randomness", but we also want it to be deterministic, and reproducible when you need it.

To support this, all "randomness" in ScalaTest's property checking system uses the Randomizer class. You start by creating a Randomizer using an initial seed value, and call that to get your "random" value. Each call to a Randomizer function returns a new Randomizer, which you should use to fetch the next value.

GeneratorDrivenPropertyChecks.forAll uses Randomizer under the hood: each time you run a forAll-based test, it will automatically create a new Randomizer, which by default is seeded based on the current system time. You can override this, as discussed below.

Since Randomizer is actually deterministic (the "random" values are unobvious, but will always be the same given the same initial seed), this means that re-running a test with the same seed will produce the same values.

If you need random data for your own Generators and property checks, you should use Randomizer in the same way; that way, your tests will also be re-runnable, when needed for debugging.

Debugging, and Re-running a Failed Property Check

In Testing Your Own Types above, we found to our surprise that the property check failed with this error:

[info] Rectangles
[info] - should have a positive area *** FAILED ***
[info]   GeneratorDrivenPropertyCheckFailedException was thrown during property evaluation.
[info]    (DocExamples.scala:42)
[info]     Falsified after 2 successful property evaluations.
[info]     Location: (DocExamples.scala:42)
[info]     Occurred when passed generated values (
[info]       None = PosInt(399455539),
[info]       None = PosInt(703518968)
[info]     )
[info]     Init Seed: 1568878346200

There must be a bug here -- but once we've fixed it, how can we make sure that we are re-testing exactly the same case that failed?

This is where the pseudo-random nature of Randomizer comes in, and why it is so important to use it consistently. So long as all of our "random" data comes from that, then all we need to do is re-run with the same seed.

That's why the Init Seed shown in the message above is crucial. We can re-use that seed -- and therefore get exactly the same "random" data -- by using the -S flag to ScalaTest.

So you can run this command in sbt to re-run exactly the same property check:

testOnly *DocExamples -- -z "have a positive area" -S 1568878346200

Taking that apart:

testOnly *DocExamples says that we only want to run suites whose paths end with DocExamples
-z "have a positive area" says to only run tests whose names include that string.
-S 1568878346200 says to run all tests with a "random" seed of 1568878346200

By combining these flags, you can re-run exactly the property check you need, with the right random seed to make sure you are re-creating the failed test. You should get exactly the same failure over and over until you fix the bug, and then you can confirm your fix with confidence.

Configuration

In general, forAll() works well out of the box. But you can tune several configuration parameters when needed. See GeneratorDrivenPropertyChecks for info on how to set configuration parameters for your test.

Table-Driven Properties

Sometimes, you want something in between traditional hard-coded unit tests and Generator-driven, randomized tests. Instead, you sometimes want to check your properties against a specific set of inputs.

(This is particularly useful for regression tests, when you have found certain inputs that have caused problems in the past, and want to make sure that they get consistently re-tested.)

ScalaTest supports these, by mixing in TableDrivenPropertyChecks. See the documentation for that class for the full details.

Definition Classes: scalatest

GeneratorDrivenPropertyChecks

TableDrivenPropertyChecks

Generator

Companion object Generator

trait Generator[T] extends AnyRef

Base type for all Generators.

A Generator produces a stream of values of a particular type. This is usually a mix of randomly-created values (generally built using a Randomizer), as well as some well-known edge cases that tend to cause bugs in real-world code.

For example, consider an intGenerator that produces a sequence of Ints. Some of these will be taken from Randomizer.nextInt, which may result in any possible Int, so the values will be a very random mix of numbers. But it will also produce the known edge cases of Int:

Int.MinValue, the smallest possible Int
Int.MaxValue, the largest possible Int
-1
0
1

The list of appropriate edge cases will vary from type to type, but they should be chosen so as to exercise the type broadly, and at extremes.

Creating Your Own Generators

Generator.intGenerator, and Generators for many other basic types, are already built into the system, so you can just use them. You can (and should) define Generators for your own types, as well.

In most cases, you do not need to write Generators from scratch -- Generators for most non-primitive types can be composed using for comprehensions, as described in the section Composing Your Own Generators in the documentation for the org.scalatest.prop pacakge. You can also often create them using the CommonGenerators.instancesOf method. You should only need to write a Generator from scratch for relatively primitive types, that aren't composed of other types.

If you decide that you do need to build a Generator from scratch, here is a rough outline of how to go about it.

First, look at the source code for some of the Generators in the Generator companion object. These follow a pretty standard pattern, that you will likely want to follow.

Size

Your Generator may optionally have a concept of size. What this means varies from type to type: for a String it might be the number of characters, whereas for a List it might be the number of elements. The test system will try using the Generator with a variety of sizes; you can control the maximum and minimum sizes via Configuration.

Decide whether the concept of size is relevant for your type. If it is relevant, you should mix the HavingSize or HavingLength trait into your Generator, and you'll want to take it into account in your next and shrink functions.

Randomization

The Generator should do all of its "random" data generation using the Randomizer instance passed in to it, and should return the next Randomizer with its results. Randomizer produces intentionally pseudo-random data: it looks reasonably random, but is actually entirely deterministic based on the seed used to initialize it. By consistently using Randomizer, the Generator can be re-run, producing the same values, when given an identically-seeded Randomizer. This can often make debugging much easier, since it allows you to reproduce your "random" failures.

So figure out how to create a pseudo-random value of your type using Randomizer. This will likely involve writing a function similar to the various nextT() functions inside of Randomizer itself.

next()

Using this randomization function, write a first draft of your Generator, filling in the next() method. This is the only required method, and should suffice to start playing with your Generator. Once this is working, you have a useful Generator.

Edges

The edges are the edge cases for this type. You may have as many or as few edge cases as seem appropriate, but most types involve at least a few. Edges are generally values that are particularly big/full, or particularly small/empty. The test system will prioritize applying the edge cases to the property, since they are assumed to be the values most likely to cause failures.

Figure out some appropriate edge cases for your type. Override initEdges() to return those, and enhance next() to produce them ahead of the random values. Identifying these will tend to make your property checks more effective, by catching these edge cases early.

Canonicals

Now figure out some canonical values for your type -- a few common, ordinary values that are frequently worth testing. These will be used when shrinking your type in higher-order Generators, so it is helpful to have some. Override the canonicals() method to return these.

Canonicals should always be in order from "smallest" to less-small, in the shrinking sense. This is not the same thing as starting with the lowest number, though! For example, the canonicals for Generator.byteGenerator are:

private val byteCanonicals: List[Byte] = List(0, 1, -1, 2, -2, 3, -3)

Zero is "smallest" -- the most-shrunk Byte.

Shrinking

Optionally but preferably, your Generator can have a concept of shrinking. This starts with a value that is known to cause the property evaluation to fail, and produces a list of smaller/simpler values, to see if those also fail. So for example, if a String of length 15 causes a failure, its Generator could try Strings of length 3, and then 1, and then 0, to see if those also cause failure.

You to not have to implement the Generator.shrink method, but it is helpful to do so when it makes sense; the test system will use that to produce smaller, easier-to-debug examples when something fails.

One important rule: the values returned from shrink must always be smaller than -- not equal to -- the values passed in. Otherwise, an infinite loop can result. Also, similar to Canonicals, the "smallest" values should be returned at the front of this Iterator, with less-small values later.

T: the type that this Generator produces

Self Type: Generator[T]
Source: Generator.scala

Linear Supertypes

AnyRef, Any

Ordering

Alphabetic
By Inheritance

Inherited

Generator
AnyRef
Any

Hide All
Show All

Visibility

Public
All

Abstract Value Members

abstract def next(szp: SizeParam, edges: List[T], rnd: Randomizer): (T, List[T], Randomizer)
Produce the next value for this Generator.
Produce the next value for this Generator.
This is the heart and soul of Generator -- it is the one function that you are required to implement when creating a new one. It takes several fields describing the state of the current evaluation, and returns the next value to try, along with the new state.
The state consists of three fields:
- The size to generate, if that is meaningful for this Generator.
- The remaining edge cases that need to be generated. In general, if this List is non-empty, you should simply return the next item on the List.
- The current Randomizer. If you need to generate random information, use this to do so.
This function returns a Tuple of three fields:
- The next value of type T to try evaluating.
- The remaining edges without the one that you are using. That is, if this function received a non-empty edges List, it should usually return the head as the next value, and the tail as the remainder after that.
- If you used the passed-in Randomizer, return the one you got back from that function. (Note that all Randomizer functions return a new Randomizer. If you didn't use it, just return the one that was passed in.
szp
the size to generate, if that is relevant for this Generator
edges
the remaining edge cases to be tried
rnd
the Randomizer to use if you need "random" data
returns
a Tuple of the next value, the remaining edges, and the resulting Randomizer, as described above.

Concrete Value Members

final def !=(arg0: Any): Boolean
Definition Classes
AnyRef → Any
final def ##(): Int
Definition Classes
AnyRef → Any
final def ==(arg0: Any): Boolean
Definition Classes
AnyRef → Any
final def asInstanceOf[T0]: T0
Definition Classes
Any
def canonicals(rnd: Randomizer): (Iterator[T], Randomizer)
Some simple, "ordinary" values of type T.
Some simple, "ordinary" values of type T.
canonicals are used for certain higher-order functions, mainly during shrink. For example, when the system is trying to simplify a List[T], it will look for canonical values of T to try putting into that simpler list, to see if that still causes the property to fail.
For example, a few of the common types provide these canonicals:
- Int: 0, 1, -1, 2, -2, 3, -3
- Char: the letters and digits
- String: single-charactor Strings of the letter and digits
You do not have to provide canonicals for a Generator. By default, this simply returns an empty Iterator.
This function takes a Randomizer to use as a parameter, in case canonical generation for this type has a random element to it. If you use this Randomizer, return the next one. If you don't use it, just use the passed-in one.
rnd
a Randomizer to use if this function requires any random data
returns
the canonical values for this type (if any), and the next Randomizer
def clone(): AnyRef
Attributes
protected[java.lang]
Definition Classes
AnyRef
Annotations
@throws(classOf[java.lang.CloneNotSupportedException]) @native()
final def eq(arg0: AnyRef): Boolean
Definition Classes
AnyRef
def equals(arg0: AnyRef): Boolean
Definition Classes
AnyRef → Any
def filter(f: (T) => Boolean): Generator[T]
Support for filtering in for comprehensions.
Support for filtering in for comprehensions.
This means the same thing is does for all standard Scala Monads: it applies a filter function to this Generator. If you use an if clause in a for comprehension, this is the function that will be called.
It is closely related to Generator.withFilter, but is the older form.
The default implementation of this has a safety check, such that if an enormous number of values (100000 by default) are rejected by the filter in a row, it aborts in order to prevent infinite loops. If this occurs, you should probably rewrite your generator to not use a filter.
You generally should not need to override this.
f
the actual filter function, which takes a value of type T and says whether to include it or not
returns
a Generator that only produces values that pass this filter.
def finalize(): Unit
Attributes
protected[java.lang]
Definition Classes
AnyRef
Annotations
@throws(classOf[java.lang.Throwable])
def flatMap[U](f: (T) => Generator[U]): Generator[U]
The usual Monad function, to allow Generators to be composed together.
The usual Monad function, to allow Generators to be composed together.
This is primarily here to support the ability to create new Generators easily using for comprehensions. For example, say that you needed a Generator that produces a Tuple of an Int and a Float. You can write that easily:
```
val tupleGen =
  for {
    a <- Generator.intGenerator
    b <- Generator.floatGenerator
  }
    yield (a, b)
```
That is, flatMap takes a function that returns a Generator, and combines it with this Generator, to produce a new Generator. That function may make use of a value from this Generator (that is part of the standard contract of flatMap), but usually does not.
U
the type produced by the other Generator
f
a function that takes a value from this Generator, and returns another Generator
returns
a Generator that is this one and the other one, composed together
final def getClass(): Class[_ <: AnyRef]
Definition Classes
AnyRef → Any
Annotations
@native()
def hashCode(): Int
Definition Classes
AnyRef → Any
Annotations
@native()
def initEdges(maxLength: PosZInt, rnd: Randomizer): (List[T], Randomizer)
Prepare a list of edge-case values ("edges") for testing this type.
Prepare a list of edge-case values ("edges") for testing this type.
The contents of this list are entirely up to the Generator. It is allowed to be empty, but it is a good idea to think about whether there are appropriate edge cases for this type. (By default, this is empty, so you can get your Generator working first, and think about edge cases after that.)
It is common, but not required, to randomize the order of the edge cases here. If so, you should use the Randomizer.shuffle function for this, so that the order is reproducible if something fails. If you don't use the Randomizer, just return it unchanged as part of the returned tuple.
Note the maxLength parameter. This is the number of tests to be run in total. So the list of returned edges should be no longer than this.
maxLength
the maximum size of the returned List
rnd
the Randomizer that should be used if you want randomization of the edges
returns
a Tuple: the list of edges, and the next Randomizer
final def isInstanceOf[T0]: Boolean
Definition Classes
Any
def map[U](f: (T) => U): Generator[U]
Given a function from types T to U, return a new Generator that produces values of type U.
Given a function from types T to U, return a new Generator that produces values of type U.
For example, say that you needed a Generator that only creates even Ints. We already have Generator.intGenerator, so one way to write this would be:
```
val evenGen: Generator[Int] = Generator.intGenerator.map { i =>
  val mod = i % 2
  if ((mod == 1) || (mod == -1))
    // It is odd, so the one before it is even:
    i - 1
  else
    // Already even
    i
}
```
This often makes it much easier to create a new Generator, if you have an existing one you can base it on.
U
the type of Generator you want to create
f
a function from T to U
returns
a new Generator, based on this one and the given transformation function
final def ne(arg0: AnyRef): Boolean
Definition Classes
AnyRef
final def notify(): Unit
Definition Classes
AnyRef
Annotations
@native()
final def notifyAll(): Unit
Definition Classes
AnyRef
Annotations
@native()
def sample: T
Fetch a generated value of type T.
Fetch a generated value of type T.
sample allows you to experiment with this Generator in a convenient, ad-hoc way. Each time you call it, it will create a new Randomizer and a random size, and then calls next to generate a value.
You should not need to override this method; it is here to let you play with your Generator as you build it, and see what sort of values are actually coming out.
returns
a generated value of type T
def samples(length: PosInt): List[T]
Generate a number of values of type T.
Generate a number of values of type T.
This is essentially the same as sample, and all the same comments apply, but this will generate as many values as you ask for.
length
the number of values to generate
returns
a List of size length, of randomly-generated values
def shrink(value: T, rnd: Randomizer): (Iterator[T], Randomizer)
Given a value of type T, produce some smaller/simpler values if that makes sense.
Given a value of type T, produce some smaller/simpler values if that makes sense.
When a property evaluation fails, the test system tries to simplify the failing case, to make debugging easier. How this simplification works depends on the type of Generator. For example, if it is a Generator of Lists, it might try with shorter Lists; if it is a Generator of Strings, it might try with shorter Strings.
The critical rule is that the values returned from shrink must be smaller/simpler than the passed-in value, and must not include the passed-in value. This is to ensure that the simplification process will always complete, and not go into an infinite loop.
This function receives a Randomizer, in case there is a random element to the simplification process. If you use the Randomizer, you should return the next one; if not, simply return the passed-in one.
You do not have to implement this function. If you do not, it will return an empty Iterator, and the test system will not try to simplify failing values of this type.
This function returns a Tuple. The first element should be an Iterator that returns simplified values, and is empty when there are no more. The second element is the next Randomizer, as discussed above.
value
a value that failed property evaluation
rnd
a Randomizer to use, if you need random data for the shrinking process
returns
a Tuple of the shrunk values and the next Randomizer
final def synchronized[T0](arg0: => T0): T0
Definition Classes
AnyRef
def toString(): String
Definition Classes
AnyRef → Any
final def wait(): Unit
Definition Classes
AnyRef
Annotations
@throws(classOf[java.lang.InterruptedException])
final def wait(arg0: Long, arg1: Int): Unit
Definition Classes
AnyRef
Annotations
@throws(classOf[java.lang.InterruptedException])
final def wait(arg0: Long): Unit
Definition Classes
AnyRef
Annotations
@throws(classOf[java.lang.InterruptedException]) @native()
def withFilter(f: (T) => Boolean): Generator[T]
Support for filtering in for comprehensions.
Support for filtering in for comprehensions.
This means the same thing is does for all standard Scala Monads: it applies a filter function to this Generator. If you use an if clause in a for comprehension, this is the function that will be called.
The default implementation of this has a safety check, such that if an enormous number of values (100000 by default) are rejected by the filter in a row, it aborts in order to prevent infinite loops. If this occurs, you should probably rewrite your generator to not use a filter.
You generally should not need to override this.
f
the actual filter function, which takes a value of type T and says whether to include it or not
returns
a Generator that only produces values that pass this filter.

Packages

Introduction to Property-based Testing

Background

Using Property Checks

What Does a Property Look Like?

Using Specific Generators

Testing Your Own Types

Composing Your Own Generators

Filtering Values with whenever()

Discard Limits

Randomization

Debugging, and Re-running a Failed Property Check

Configuration

Table-Driven Properties

Generator

Companion object Generator

trait Generator[T] extends AnyRef

Creating Your Own Generators

Size

Randomization

next()

Edges

Canonicals

Shrinking

Abstract Value Members

Concrete Value Members

Inherited from AnyRef

Inherited from Any

Ungrouped

Packages

Introduction to Property-based Testing

Background

Using Property Checks

What Does a Property Look Like?

Using Specific Generators

Testing Your Own Types

Composing Your Own Generators

Filtering Values with whenever()

Discard Limits

Randomization

Debugging, and Re-running a Failed Property Check

Configuration

Table-Driven Properties

Generator

Companion object Generator

trait Generator[T] extends AnyRef

Creating Your Own Generators

Size

Randomization

next()

Edges

Canonicals

Shrinking

Abstract Value Members

Concrete Value Members

Inherited from AnyRef

Inherited from Any

Ungrouped

Generator