ScalaTest 3.1.0-SNAP13 < Back

Packages

package root
Definition Classes
root
package org
Definition Classes
root
package scalatest
ScalaTest's main traits, classes, and other members, including members supporting ScalaTest's DSL for the Scala interpreter.
ScalaTest's main traits, classes, and other members, including members supporting ScalaTest's DSL for the Scala interpreter.
Definition Classes
org
package compatible
Definition Classes
scalatest
package concurrent
ScalaTest's main traits, classes, and other members, including members supporting ScalaTest's DSL for the Scala interpreter.
ScalaTest's main traits, classes, and other members, including members supporting ScalaTest's DSL for the Scala interpreter.
Definition Classes
scalatest
package enablers
Definition Classes
scalatest
Aggregating
AggregatingHighPriorityImplicits
AggregatingImpls
AggregatingJavaImplicits
AggregatingStandardImplicits
Collecting
Containing
ContainingHighPriorityImplicits
ContainingImpls
ContainingStandardImplicits
Definition
Emptiness
Existence
ExpectationPropCheckerAsserting
ExpectationWheneverAsserting
FuturePropCheckerAsserting
Futuristic
InspectorAsserting
JavaContainingImplicits
KeyMapping
Length
Messaging
PropCheckerAsserting
Readability
Retrying
Sequencing
Size
Sortable
TableAsserting
Timed
UnitInspectorAsserting
UnitPropCheckerAsserting
UnitTableAsserting
UnitWheneverAsserting
ValueMapping
WheneverAsserting
Writability
package events
Definition Classes
scalatest
package exceptions
Definition Classes
scalatest
package featurespec
Definition Classes
scalatest
package fixture
Package fixture deprecated types.
Package fixture deprecated types.
Definition Classes
scalatest
package flatspec
Definition Classes
scalatest
package freespec
Definition Classes
scalatest
package funspec
Definition Classes
scalatest
package funsuite
Definition Classes
scalatest
package matchers
Definition Classes
scalatest
package path
Definition Classes
scalatest
package prop
Scalatest support for Property-based testing.
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
package propspec
Definition Classes
scalatest
package tagobjects
Definition Classes
scalatest
package time
Definition Classes
scalatest
package tools
Definition Classes
scalatest
package words
Definition Classes
scalatest
package wordspec
Definition Classes
scalatest

org.scalatest

enablers

package enablers

Ordering

Alphabetic

Visibility

Public
All

Type Members

trait Aggregating[-A] extends AnyRef
Typeclass that enables for aggregations certain contain syntax in the ScalaTest matchers DSL.
Typeclass that enables for aggregations certain contain syntax in the ScalaTest matchers DSL.
An Aggregating[A] provides access to the "aggregating nature" of type A in such a way that relevant contain matcher syntax can be used with type A. An A can be any type of aggregation—an object that in some way aggregates or brings together other objects. ScalaTest provides implicit implementations for several types out of the box in the Aggregating companion object:
- scala.collection.GenTraversable
- String
- Array
- java.util.Collection
- java.util.Map
The contain syntax enabled by this trait is:
- result should contain atLeastOneOf (1, 2, 3)
- result should contain atMostOneOf (1, 2, 3)
- result should contain only (1, 2, 3)
- result should contain allOf (1, 2, 3)
- result should contain theSameElementsAs (List(1, 2, 3))
You can enable the contain matcher syntax enabled by Aggregating on your own type U by defining an Aggregating[U] for the type and making it available implicitly.
Note, for an explanation of the difference between Containing and Aggregating, both of which enable contain matcher syntax, see the Containing versus Aggregating section of the main documentation for trait Containing.
trait AggregatingHighPriorityImplicits extends AggregatingStandardImplicits
trait AggregatingImpls extends AnyRef
trait AggregatingJavaImplicits extends AggregatingImpls
trait AggregatingStandardImplicits extends AggregatingJavaImplicits
trait Collecting[E, C] extends AnyRef
Supertrait for typeclasses that enable loneElement and inspectors syntax for collections.
Supertrait for typeclasses that enable loneElement and inspectors syntax for collections.
A Collecting[E, C] provides access to the "collecting nature" of type C in such a way that loneElement syntax can be used with type C. A C can be any type of "collecting", a type that in some way collects or brings together elements of type E. ScalaTest provides implicit implementations for several types. You can enable the contain matcher syntax on your own type U by defining an Collecting[E, U] for the type and making it available implicitly.
ScalaTest provides implicit Collecting instances for scala.collection.GenTraversable, Array, java.util.Collection and java.util.Map in the Collecting companion object.
trait Containing[-C] extends AnyRef
Supertrait for typeclasses that enable certain contain matcher syntax for containers.
Supertrait for typeclasses that enable certain contain matcher syntax for containers.
A Containing[C] provides access to the "containing nature" of type C in such a way that relevant contain matcher syntax can be used with type C. A C can be any type of "container," a type that in some way can contains one or more other objects. ScalaTest provides implicit implementations for several types. You can enable the contain matcher syntax on your own type U by defining an Containing[U] for the type and making it available implicitly.
ScalaTest provides implicit Containing instances for scala.collection.GenTraversable, java.util.Collection, java.util.Map, String, Array, and scala.Option in the Containing companion object.
Containing versus Aggregating
The difference between Containing and Aggregating is that Containing enables contain matcher syntax that makes sense for "box" types that can contain at most one value (for example, scala.Option), whereas Aggregating enables contain matcher syntax for full-blown collections and other aggregations of potentially more than one object. For example, it makes sense to make assertions like these, which are enabled by Containing, for scala.Option:
```
val option: Option[Int] = Some(7)
option should contain (7)
option should contain oneOf (6, 7, 8)
option should contain noneOf (3, 4, 5)
```
However, given a scala.Option can only ever contain at most one object, it doesn't make sense to make assertions like the following, which are enabled via Aggregation:
```
// Could never succeed, so does not compile
option should contain allOf (6, 7, 8)
```
The above assertion could never succceed, because an option cannot contain more than one value. By default the above statement does not compile, because contain allOf is enabled by Aggregating, and ScalaTest provides no implicit Aggregating instance for type scala.Option.
trait ContainingHighPriorityImplicits extends ContainingStandardImplicits
trait ContainingImpls extends AnyRef
trait ContainingStandardImplicits extends JavaContainingImplicits
trait Definition[-T] extends AnyRef
Supertrait for typeclasses that enable the be defined matcher syntax.
Supertrait for typeclasses that enable the be defined matcher syntax.
A Definition[T] provides access to the "definition nature" of type S in such a way that be defined matcher syntax can be used with type T. A T can be any type for which the concept of being defined makes sense, such as scala.Option. ScalaTest provides implicit implementation for scala.Option. You can enable the be defined matcher syntax on your own type U by defining a Definition[U] for the type and making it available implicitly.
ScalaTest provides an implicit Definition instance for scala.Option, arbitary object with isDefined() or isDefined in the Definition companion object.
trait Emptiness[-T] extends AnyRef
Supertrait for typeclasses that enable be empty matcher syntax.
Supertrait for typeclasses that enable be empty matcher syntax.
An Emptiness[T] provides access to the "emptiness" of type T in such a way that be empty matcher syntax can be used with type T. A T can be any type that in some way can be empty. ScalaTest provides implicit implementations for several types. You can enable the be empty matcher syntax on your own type U by defining an Emptiness[U] for the type and making it available implicitly.
ScalaTest provides implicit Emptiness instances for scala.collection.GenTraversable, java.util.Collection, java.util.Map, String, Array, and scala.Option in the Emptiness companion object.
trait Existence[-S] extends AnyRef
Supertrait for typeclasses that enable the exist matcher syntax.
Supertrait for typeclasses that enable the exist matcher syntax.
An Existence[S] provides access to the "existence nature" of type S in such a way that exist matcher syntax can be used with type S. A S can be any type for which the concept of existence makes sense, such as java.io.File. ScalaTest provides implicit implementations for java.io.File. You can enable the exist matcher syntax on your own type U by defining a Existence[U] for the type and making it available implicitly.
ScalaTest provides an implicit Existence instance for java.io.File in the Existence companion object.
abstract class ExpectationPropCheckerAsserting extends UnitPropCheckerAsserting
abstract class ExpectationWheneverAsserting extends UnitWheneverAsserting
Abstract class that in the future will hold an intermediate priority WheneverAsserting implicit, which will enable inspector expressions that have result type Expectation, a more composable form of assertion that returns a result instead of throwing an exception when it fails.
trait FuturePropCheckerAsserting extends AnyRef
trait Futuristic[T] extends AnyRef
Supertrait for Futureistic typeclasses.
Supertrait for Futureistic typeclasses.
Trait Futureistic is a typeclass trait for objects that can be used with the complete-lastly syntax of trait CompleteLastly.
trait InspectorAsserting[T] extends AnyRef
Supertrait for InspectorAsserting typeclasses, which are used to implement and determine the result type of Inspectors methods such as forAll, forBetween, etc.
Supertrait for InspectorAsserting typeclasses, which are used to implement and determine the result type of Inspectors methods such as forAll, forBetween, etc.
Currently, an inspector expression will have result type Assertion, if the function passed has result type Assertion, else it will have result type Unit.
trait JavaContainingImplicits extends ContainingImpls
trait KeyMapping[-M] extends AnyRef
Supertrait for typeclasses that enable contain key matcher syntax.
Supertrait for typeclasses that enable contain key matcher syntax.
A KeyMapping[M] provides access to the "key mapping nature" of type M in such a way that contain key matcher syntax can be used with type M. A M can be any type for which contain key syntax makes sense. ScalaTest provides implicit implementations for scala.collection.GenMap and java.util.Map. You can enable the contain key matcher syntax on your own type U by defining a KeyMapping[U] for the type and making it available implicitly.
ScalaTest provides implicit KeyMapping instances for scala.collection.GenMap, and java.util.Map in the KeyMapping companion object.

trait Length[T] extends AnyRef

Supertrait for Length typeclasses.

Trait Length is a typeclass trait for objects that can be queried for length. Objects of type T for which an implicit Length[T] is available can be used with the should have length syntax. In other words, this trait enables you to use the length checking syntax with arbitrary objects. As an example, the following Bridge class:

scala> import org.scalatest._
import org.scalatest._

scala> import enablers.Length
import enablers.Length

scala> import Matchers._
import Matchers._

scala> case class Bridge(span: Int)
defined class Bridge

Out of the box you can't use the should have length syntax with Bridge, because ScalaTest doesn't know that a bridge's span means its length:

scala> val bridge = new Bridge(2000)
bridge: Bridge = Bridge(2000)

scala> bridge should have length 2000
<console>:34: error: could not find implicit value for
    parameter len: org.scalatest.enablers.Length[Bridge]
      bridge should have length 2000
                         ^

You can teach this to ScalaTest, however, by defining an implicit Length[Bridge].

scala> implicit val lengthOfBridge: Length[Bridge] =
     |   new Length[Bridge] {
     |     def lengthOf(b: Bridge): Long = b.span
     |   }
lengthOfBridge: org.scalatest.enablers.Length[Bridge] = $anon$1@3fa27a4a

With the implicit Length[Bridge] in scope, you can now use ScalaTest's should have length syntax with Bridge instances:

scala> bridge should have length 2000
res4: org.scalatest.Assertion = Succeeded

scala> bridge should have length 2001
org.scalatest.exceptions.TestFailedException: Bridge(2000) had length 2000 instead of expected length 2001
  at org.scalatest.MatchersHelper$.newTestFailedException(MatchersHelper.scala:148)
  at org.scalatest.MatchersHelper$.indicateFailure(MatchersHelper.scala:366)
  at org.scalatest.Matchers$ResultOfHaveWordForExtent.length(Matchers.scala:2720)
  ... 43 elided

trait Messaging[T] extends AnyRef
Supertrait for Messaging typeclasses.
Supertrait for Messaging typeclasses.
Trait Messaging is a typeclass trait for objects that can be queried for message. Objects of type T for which an implicit Messaging[T] is available can be used with the should have message syntax. You can enable the have message matcher syntax on your own type U by defining a Messaging[U] for the type and making it available implicitly.
ScalaTest provides an implicit Messaging instance for java.lang.Throwable and arbitary object with message(), message, getMessage() or getMessage method in the Messaging companion object.
trait PropCheckerAsserting[T] extends AnyRef
trait Readability[-T] extends AnyRef
Supertrait for typeclasses that enable the be readable matcher syntax.
Supertrait for typeclasses that enable the be readable matcher syntax.
A Readability[T] provides access to the "readable nature" of type T in such a way that be readable matcher syntax can be used with type T. A T can be any type for which the concept of being readable makes sense, such as java.io.File. You can enable the be readable matcher syntax on your own type U by defining a Readability[U] for the type and making it available implicitly.
ScalaTest provides an implicit Readability instance for java.io.File and arbitary object with isReadable() or isReadable in the Readability companion object.
trait Retrying[T] extends AnyRef
Supertrait for Retrying typeclasses, which are used to implement and determine the behavior of Eventually methods.
Supertrait for Retrying typeclasses, which are used to implement and determine the behavior of Eventually methods.
Currently, implementations for anything type T and Future[T] is provided.
trait Sequencing[-S] extends AnyRef
Typeclass that enables for sequencing certain contain syntax in the ScalaTest matchers DSL.
Typeclass that enables for sequencing certain contain syntax in the ScalaTest matchers DSL.
An Sequencing[A] provides access to the "sequenching nature" of type A in such a way that relevant contain matcher syntax can be used with type A. An A can be any type of sequencing—an object that in some way brings together other objects in order. ScalaTest provides implicit implementations for several types out of the box in the Sequencing companion object:
- scala.collection.GenSeq
- scala.collection.SortedSet
- scala.collection.SortedMap
- Array
- java.util.List
- java.util.SortedSet
- java.util.SortedMap
- String
The contain syntax enabled by this trait is:
- result should contain inOrder (1, 2, 3)
- result should contain inOrderOnly (1, 2, 3)
- result should contain theSameElementsInOrderAs List(1, 2, 3)
You can enable the contain matcher syntax enabled by Sequencing on your own type U by defining an Sequencing[U] for the type and making it available implicitly.

trait Size[T] extends AnyRef

Supertrait for Size typeclasses.

Trait Size is a typeclass trait for objects that can be queried for size. Objects of type T for which an implicit Size[T] is available can be used with the should have size syntax. In other words, this trait enables you to use the size checking syntax with arbitrary objects. As an example, the following Bridge class:

scala> import org.scalatest._
import org.scalatest._

scala> import enablers.Size
import enablers.Size

scala> import Matchers._
import Matchers._

scala> case class Bridge(span: Int)
defined class Bridge

Out of the box you can't use the should have size syntax with Bridge, because ScalaTest doesn't know that a bridge's span means its size:

scala> val bridge = new Bridge(2000)
bridge: Bridge = Bridge(2000)

scala> bridge should have size 2000
<console>:34: error: could not find implicit value for
    parameter sz: org.scalatest.enablers.Size[Bridge]
      bridge should have size 2000
                         ^

You can teach this to ScalaTest, however, by defining an implicit Size[Bridge].

scala> implicit val sizeOfBridge: Size[Bridge] =
     |   new Size[Bridge] {
     |     def sizeOf(b: Bridge): Long = b.span
     |   }
sizeOfBridge: org.scalatest.enablers.Size[Bridge] = $anon$1@3fa27a4a

With the implicit Size[Bridge] in scope, you can now use ScalaTest's should have size syntax with Bridge instances:

scala> bridge should have size 2000
res4: org.scalatest.Assertion = Succeeded

scala> bridge should have size 2001
org.scalatest.exceptions.TestFailedException: Bridge(2000) had size 2000 instead of expected size 2001
  at org.scalatest.MatchersHelper$.newTestFailedException(MatchersHelper.scala:148)
  at org.scalatest.MatchersHelper$.indicateFailure(MatchersHelper.scala:366)
  at org.scalatest.Matchers$ResultOfHaveWordForExtent.size(Matchers.scala:2720)
  ... 43 elided

trait Sortable[-S] extends AnyRef
Supertrait for typeclasses that enable the be sorted matcher syntax.
Supertrait for typeclasses that enable the be sorted matcher syntax.
A Sortable[S] provides access to the "sortable nature" of type S in such a way that be sorted matcher syntax can be used with type S. An S can be any type for which the concept of being sorted makes sense, such as sequences. ScalaTest provides implicit implementations for several types. You can enable the be sorted matcher syntax on your own type U by defining a Sortable[U] for the type and making it available implicitly.
ScalaTest provides an implicit Sortable instance for types out of the box in the Sortable companion object:
- scala.collection.GenSeq
- Array
- java.util.List
trait TableAsserting[ASSERTION] extends AnyRef
Supertrait for TableAsserting typeclasses, which are used to implement and determine the result type of TableDrivenPropertyChecks's forAll, forEvery and exists method.
Supertrait for TableAsserting typeclasses, which are used to implement and determine the result type of TableDrivenPropertyChecks's forAll, forEvery and exists method.
Currently, an TableDrivenPropertyChecks expression will have result type Assertion, if the function passed has result type Assertion, else it will have result type Unit.
trait Timed[T] extends AnyRef
Trait that provides a timeoutAfter construct, which allows you to specify a timeout for an operation passed as a by-name parameter, as well as a way to signal/interrupt it if the operation exceeds its time limit.
abstract class UnitInspectorAsserting extends AnyRef
Class holding lowest priority InspectorAsserting implicit, which enables inspector expressions that have result type Unit.
abstract class UnitPropCheckerAsserting extends AnyRef
Class holding lowest priority CheckerAsserting implicit, which enables GeneratorDrivenPropertyChecks expressions that have result type Unit.
abstract class UnitTableAsserting extends AnyRef
Class holding lowest priority TableAsserting implicit, which enables TableDrivenPropertyChecks expressions that have result type Unit.
abstract class UnitWheneverAsserting extends AnyRef
Class holding lowest priority WheneverAsserting implicit, which enables Whenever expressions that have result type Unit.
trait ValueMapping[-M] extends AnyRef
Supertrait for typeclasses that enable contain value matcher syntax.
Supertrait for typeclasses that enable contain value matcher syntax.
A ValueMapping[M] provides access to the "value mapping nature" of type M in such a way that contain value matcher syntax can be used with type M. An M can be any type for which contain value syntax makes sense. ScalaTest provides implicit implementations for scala.collection.GenMap and java.util.Map. You can enable the contain value matcher syntax on your own type U by defining a ValueMapping[U] for the type and making it available implicitly.
ScalaTest provides implicit ValueMapping instances for scala.collection.GenMap, and java.util.Map in the ValueMapping companion object.
trait WheneverAsserting[T] extends AnyRef
Supertrait for WheneverAsserting typeclasses, which are used to implement and determine the result type of Whenever's whenever method.
Supertrait for WheneverAsserting typeclasses, which are used to implement and determine the result type of Whenever's whenever method.
Currently, an Whenever expression will have result type Assertion, if the function passed has result type Assertion, else it will have result type Unit.
trait Writability[-T] extends AnyRef
Supertrait for typeclasses that enable the be writable matcher syntax.
Supertrait for typeclasses that enable the be writable matcher syntax.
A Writability[T] provides access to the "writable nature" of type T in such a way that be writable matcher syntax can be used with type T. A T can be any type for which the concept of being writable makes sense, such as java.io.File. ScalaTest provides implicit implementation for java.io.File. You can enable the be writable matcher syntax on your own type U by defining a Writability[U] for the type and making it available implicitly.
ScalaTest provides an implicit Writability instance for java.io.File and arbitary object with isWritable() or isWritable in the Writability companion object.

Value Members

object Aggregating extends AggregatingHighPriorityImplicits
Companion object for Aggregating that provides implicit implementations for the following types:
Companion object for Aggregating that provides implicit implementations for the following types:
- scala.collection.GenTraversable
- String
- Array
- java.util.Collection
- java.util.Map
object Collecting
Companion object for Collecting that provides implicit implementations for the following types:
Companion object for Collecting that provides implicit implementations for the following types:
- scala.collection.GenTraversable
- Array
- java.util.Collection
- java.util.Map
object Containing extends ContainingHighPriorityImplicits
Companion object for Containing that provides implicit implementations for the following types:
Companion object for Containing that provides implicit implementations for the following types:
- scala.collection.GenTraversable
- String
- Array
- scala.Option
- java.util.Collection
- java.util.Map
object Definition
Companion object for Definition that provides implicit implementations for the following types:
Companion object for Definition that provides implicit implementations for the following types:
- scala.Option
- arbitary object with a isDefined() method that returns Boolean
- arbitary object with a parameterless isDefined method that returns Boolean
object Emptiness
Companion object for Emptiness that provides implicit implementations for the following types:
Companion object for Emptiness that provides implicit implementations for the following types:
- scala.collection.GenTraversable
- String
- Array
- scala.Option
- java.util.Collection
- java.util.Map
- arbitary object with a isEmpty() method that returns Boolean
- arbitary object with a parameterless isEmpty method that returns Boolean
object Existence
Companion object for Existence that provides implicit implementations for java.io.File.
object Futuristic
Companion object for trait Futuristic that contains implicit Futuristic providers for FutureOutcome and Future[T] for any type T.
object InspectorAsserting extends UnitInspectorAsserting
Companion object to InspectorAsserting that provides two implicit providers, a higher priority one for passed functions that have result type Assertion, which also yields result type Assertion, and one for any other type, which yields result type Unit.
object KeyMapping
Companion object for KeyMapping that provides implicit implementations for scala.collection.GenMap and java.util.Map.
object Length
Companion object for Length that provides implicit implementations for the following types:
Companion object for Length that provides implicit implementations for the following types:
- scala.collection.GenSeq
- String
- Array
- java.util.Collection
- arbitary object with a length() method that returns Int
- arbitary object with a parameterless length method that returns Int
- arbitary object with a getLength() method that returns Int
- arbitary object with a parameterless getLength method that returns Int
- arbitary object with a length() method that returns Long
- arbitary object with a parameterless length method that returns Long
- arbitary object with a getLength() method that returns Long
- arbitary object with a parameterless getLength method that returns Long
object Messaging
Companion object for Messaging that provides implicit implementations for the following types:
Companion object for Messaging that provides implicit implementations for the following types:
- java.lang.Throwable
- arbitary object with a message() method that returns String
- arbitary object with a parameterless message method that returns String
- arbitary object with a getMessage() method that returns String
- arbitary object with a parameterless getMessage method that returns String
object PropCheckerAsserting extends ExpectationPropCheckerAsserting with FuturePropCheckerAsserting
object Readability
Companion object for Readability that provides implicit implementations for the following types:
Companion object for Readability that provides implicit implementations for the following types:
- java.io.File
- arbitary object with a isReadable() method that returns Boolean
- arbitary object with a parameterless isReadable method that returns Boolean
object Retrying
Companion object that provides Retrying implementations for T and Future[T].
object Sequencing
Companion object for Sequencing that provides implicit implementations for the following types:
Companion object for Sequencing that provides implicit implementations for the following types:
- scala.collection.GenSeq
- scala.collection.SortedSet
- scala.collection.SortedMap
- Array
- java.util.List
- java.util.SortedSet
- java.util.SortedMap
- String
object Size
Companion object for Size that provides implicit implementations for the following types:
Companion object for Size that provides implicit implementations for the following types:
- scala.collection.GenTraversable
- String
- Array
- java.util.Collection
- java.util.Map
- arbitary object with a size() method that returns Int
- arbitary object with a parameterless size method that returns Int
- arbitary object with a getSize() method that returns Int
- arbitary object with a parameterless getSize method that returns Int
- arbitary object with a size() method that returns Long
- arbitary object with a parameterless size method that returns Long
- arbitary object with a getSize() method that returns Long
- arbitary object with a parameterless getSize method that returns Long
object Sortable
Companion object for Sortable that provides implicit implementations for the following types:
Companion object for Sortable that provides implicit implementations for the following types:
- scala.collection.GenSeq
- Array
- java.util.List
object TableAsserting extends UnitTableAsserting
Companion object to TableAsserting that provides two implicit providers, a higher priority one for passed functions that have result type Assertion, which also yields result type Assertion, and one for any other type, which yields result type Unit.
object Timed
Companion object for Timed typeclass that offers three implicit providers: one for FutureOutcome, one for Future of any type, and one for any other type.
Companion object for Timed typeclass that offers three implicit providers: one for FutureOutcome, one for Future of any type, and one for any other type.
The details are in the documentation for the implicit providers themselves (methods timed, timedFutureOf, and timedFutureOutcome), but in short if a time limit is exceeded:
- if the type T in Timed[T] is FutureOutcome the FutureOutcome returned by timeoutAfter will result in either Failed or Canceled
- if the type is Future[U], the Future[U] returned by timeoutAfter will fail with either a TestFailedDueToTimeoutException or a TestCanceledException.
- otherwise, the timeoutAfter method will itself complete abruptly with either TestFailedDueToTimeoutException or TestCanceledException.
 object ValueMappingCompanion object for ValueMapping that provides implicit implementations for scala.collection.GenMap and java.util.Map.
 object WheneverAsserting extends ExpectationWheneverAssertingCompanion object to WheneverAsserting that provides two implicit providers, a higher priority one for passed functions that have result type Assertion, which also yields result type Assertion, and one for any other type, which yields result type Unit.
 object WritabilityCompanion object for Writability that provides implicit implementations for the following types: Companion object for Writability that provides implicit implementations for the following types: java.io.File arbitary object with a isWritable() method that returns Boolean arbitary object with a parameterless isWritable method that returns Boolean

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

enablers

package enablers

Type Members

`Containing` versus `Aggregating`

Value Members

`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

enablers

package enablers

Type Members

Containing versus Aggregating

Value Members

Ungrouped

enablers

`Containing` versus `Aggregating`

`Ungrouped`