Inspectors

Provides nestable inspector methods (or just inspectors) that enable assertions to be made about collections.

For example, the forAll method enables you to state that something should be true about all elements of a collection, such as that all elements should be positive:

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

scala> import Assertions._
import Assertions._

scala> import Inspectors._
import Inspectors._

scala> val xs = List(1, 2, 3, 4, 5)
xs: List[Int] = List(1, 2, 3, 4, 5)

scala> forAll (xs) { x => assert(x > 0) }

Or, with matchers:

scala> import Matchers._
import Matchers._

scala> forAll (xs) { x => x should be > 0 }

To make assertions about nested collections, you can nest the inspector method invocations. For example, given the following list of lists of Int:

scala> val yss =
     |   List(
     |     List(1, 2, 3),
     |     List(1, 2, 3),
     |     List(1, 2, 3)
     |   )
yss: List[List[Int]] = List(List(1, 2, 3), List(1, 2, 3), List(1, 2, 3))

You can assert that all Int elements in all nested lists are positive by nesting two forAll method invocations, like this:

scala> forAll (yss) { ys =>
     |   forAll (ys) { y => y should be > 0 }
     | }

The full list of inspector methods are:

forAll - succeeds if the assertion holds true for every element
forAtLeast - succeeds if the assertion holds true for at least the specified number of elements
forAtMost - succeeds if the assertion holds true for at most the specified number of elements
forBetween - succeeds if the assertion holds true for between the specified minimum and maximum number of elements, inclusive
forEvery - same as forAll, but lists all failing elements if it fails (whereas forAll just reports the first failing element)
forExactly - succeeds if the assertion holds true for exactly the specified number of elements

The error messages produced by inspector methods are designed to make sense no matter how deeply you nest the method invocations. Here's an example of a nested inspection that fails and the resulting error message:

scala> forAll (yss) { ys =>
     |   forAll (ys) { y => y should be < 2 }
     | }
org.scalatest.exceptions.TestFailedException: forAll failed, because:
  at index 0, forAll failed, because:
    at index 1, 2 was not less than 2 (<console>:20)
  in List(1, 2, 3) (<console>:20)
in List(List(1, 2, 3), List(1, 2, 3), List(1, 2, 3))
     at org.scalatest.InspectorsHelper$.doForAll(Inspectors.scala:146)
     ...

One way the error message is designed to help you understand the error is by using indentation that mimics the indentation of the source code (optimistically assuming the source will be nicely indented). The error message above indicates the outer forAll failed because its initial List (i.e., at index 0) failed the assertion, which was that all elements of that initial List[Int] at index 0 should be less than 2. This assertion failed because index 1 of that inner list contained the value 2, which was indeed “not less than 2.” The error message for the inner list is an indented line inside the error message for the outer list. The actual contents of each list are displayed at the end in inspector error messages, also indented appropriately. The actual contents are placed at the end so that for very large collections, the contents will not drown out and make it difficult to find the messages that describe actual causes of the failure.

The forAll and forEvery methods are similar in that both succeed only if the assertion holds for all elements of the collection. They differ in that forAll will only report the first element encountered that failed the assertion, but forEvery will report all elements that fail the assertion. The tradeoff is that while forEvery gives more information, it may take longer to run because it must inspect every element of the collection. The forAll method can simply stop inspecting once it encounters the first failing element. Here's an example that shows the difference in the forAll and forEvery error messages:

scala> forAll (xs) { x => x should be < 3 }
org.scalatest.exceptions.TestFailedException: forAll failed, because:
  at index 2, 3 was not less than 3 (<console>:18)
in List(1, 2, 3, 4, 5)
     at org.scalatest.InspectorsHelper$.doForAll(Inspectors.scala:146)
     ...

scala> forEvery (xs) { x => x should be < 3 }
org.scalatest.exceptions.TestFailedException: forEvery failed, because:
  at index 2, 3 was not less than 3 (<console>:18),
  at index 3, 4 was not less than 3 (<console>:18),
  at index 4, 5 was not less than 3 (<console>:18)
in List(1, 2, 3, 4, 5)
     at org.scalatest.InspectorsHelper$.doForEvery(Inspectors.scala:226)
     ...

Note that if you're using matchers, you can alternatively use inspector shorthands for writing non-nested inspections. Here's an example:

scala> all (xs) should be > 3
org.scalatest.exceptions.TestFailedException: 'all' inspection failed, because:
  at index 0, 1 was not greater than 3
in List(1, 2, 3, 4, 5)
     at org.scalatest.InspectorsHelper$.doForAll(Inspectors.scala:146)

You can use Inspectors on any scala.collection.GenTraversable, java.util.Collection, java.util.Map (with Entry), Array, or String. Here are some examples:

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

scala> import Inspectors._
import Inspectors._

scala> import Matchers._
import Matchers._

scala> forAll (Array(1, 2, 3)) { e => e should be < 5 }

scala> import collection.JavaConverters._
import collection.JavaConverters._

scala> val js = List(1, 2, 3).asJava
js: java.util.List[Int] = [1, 2, 3]

scala> forAll (js) { j => j should be < 5 }

scala> val jmap = Map("a" -> 1, "b" -> 2).asJava
jmap: java.util.Map[String,Int] = {a=1, b=2}

scala> forAtLeast(1, jmap) { e => e shouldBe Entry("b", 2) }

scala> forAtLeast(2, "hello, world!") { c => c shouldBe 'o' }

Source: Inspectors.scala

Linear Supertypes

AnyRef, Any

Known Subclasses

Inspectors

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 clone(): AnyRef

Attributes
protected[java.lang]
Definition Classes
AnyRef
Annotations
@throws( ... )
final def eq(arg0: AnyRef): Boolean

Definition Classes
AnyRef
def equals(arg0: Any): Boolean

Definition Classes
AnyRef → Any
def finalize(): Unit

Attributes
protected[java.lang]
Definition Classes
AnyRef
Annotations
@throws( classOf[java.lang.Throwable] )
def forAll(xs: String)(fun: (Char) ⇒ Assertion)(implicit collecting: Collecting[Char, String]): Assertion

Ensure that all characters in a given String pass the given inspection function, where "pass" means returning normally from the function (i.e., without throwing an exception).
Ensure that all characters in a given String pass the given inspection function, where "pass" means returning normally from the function (i.e., without throwing an exception).
The difference between forAll and forEvery is that forAll will stop on the first failure, while forEvery will continue to inspect all characters in the String after the first failure (and report all failures).
xs
the String
fun
the inspection function
collecting
the implicit Collecting that can transform xs into a scala.collection.GenTraversable
def forAll[K, V, JMAP[k, v] <: Map[k, v]](xs: JMAP[K, V])(fun: (Entry[K, V]) ⇒ Assertion)(implicit collecting: Collecting[Entry[K, V], JMAP[K, V]]): Assertion

Ensure that all elements in a given java.util.Map pass the given inspection function, where "pass" means returning normally from the function (i.e., without throwing an exception).
Ensure that all elements in a given java.util.Map pass the given inspection function, where "pass" means returning normally from the function (i.e., without throwing an exception).
The difference between forAll and forEvery is that forAll will stop on the first failure, while forEvery will continue to inspect all java.util.Map elements after the first failure (and report all failures).
K
the type of key in the Java Map
V
the type of value in the Java Map
JMAP
subtype of java.util.Map
xs
the java.util.Map
fun
the inspection function
collecting
the implicit Collecting that can transform xs into a scala.collection.GenTraversable
def forAll[E, C[_]](xs: C[E])(fun: (E) ⇒ Assertion)(implicit collecting: Collecting[E, C[E]]): Assertion

Ensure that all elements in a given collection pass the given inspection function, where "pass" means returning normally from the function (i.e., without throwing an exception).
Ensure that all elements in a given collection pass the given inspection function, where "pass" means returning normally from the function (i.e., without throwing an exception).
The difference between forAll and forEvery is that forAll will stop on the first failure, while forEvery will continue to inspect all elements after the first failure (and report all failures).
E
the type of element in the collection
C
the type of collection
xs
the collection of elements
fun
the inspection function
collecting
the implicit Collecting that can transform xs into a scala.collection.GenTraversable
def forAtLeast(min: Int, xs: String)(fun: (Char) ⇒ Assertion)(implicit collecting: Collecting[Char, String]): Assertion

Ensure that at least min number of characters in a given String pass the given inspection function.
Ensure that at least min number of characters in a given String pass the given inspection function.
min
the minimum number of characters in String that must pass the inspection function
xs
the String
fun
the inspection function
collecting
the implicit Collecting that can transform xs into a scala.collection.GenTraversable
def forAtLeast[K, V, JMAP[k, v] <: Map[k, v]](min: Int, xs: JMAP[K, V])(fun: (Entry[K, V]) ⇒ Assertion)(implicit collecting: Collecting[Entry[K, V], JMAP[K, V]]): Assertion

Ensure that at least min number of elements in a given java.util.Map pass the given inspection function.
Ensure that at least min number of elements in a given java.util.Map pass the given inspection function.
K
the type of key in the java.util.Map
V
the type of value in the java.util.Map
JMAP
subtype of java.util.Map
min
the minimum number of elements that must pass the inspection function
xs
the java.util.Map
fun
the inspection function
collecting
the implicit Collecting that can transform xs into a scala.collection.GenTraversable
def forAtLeast[E, C[_]](min: Int, xs: C[E])(fun: (E) ⇒ Assertion)(implicit collecting: Collecting[E, C[E]]): Assertion

Ensure that at least min number of elements of a given collection pass the given inspection function.
Ensure that at least min number of elements of a given collection pass the given inspection function.
E
the type of element in the collection
C
the type of collection
min
the minimum number of elements that must pass the inspection function
xs
the collection of elements
fun
the inspection function
collecting
the implicit Collecting that can transform xs into a scala.collection.GenTraversable
def forAtMost(max: Int, xs: String)(fun: (Char) ⇒ Assertion)(implicit collecting: Collecting[Char, String]): Assertion

Ensure that at most max number of characters in a given String pass the given inspection function.
Ensure that at most max number of characters in a given String pass the given inspection function.
max
the maximum number of characters in String that must pass the inspection function
xs
the String
fun
the inspection function
collecting
the implicit Collecting that can transform xs into a scala.collection.GenTraversable
def forAtMost[K, V, JMAP[k, v] <: Map[k, v]](max: Int, xs: JMAP[K, V])(fun: (Entry[K, V]) ⇒ Assertion)(implicit collecting: Collecting[Entry[K, V], JMAP[K, V]]): Assertion

Ensure that at most max number of elements in a given java.util.Map pass the given inspection function.
Ensure that at most max number of elements in a given java.util.Map pass the given inspection function.
K
the type of key in the java.util.Map
V
the type of value in the java.util.Map
JMAP
subtype of java.util.Map
max
the maximum number of elements in the java.util.Map that must pass the inspection function
xs
the java.util.Map
fun
the inspection function
collecting
the implicit Collecting that can transform xs into a scala.collection.GenTraversable
def forAtMost[E, C[_]](max: Int, xs: C[E])(fun: (E) ⇒ Assertion)(implicit collecting: Collecting[E, C[E]]): Assertion

Ensure that at most max number of elements of a given collection pass the given inspection function.
Ensure that at most max number of elements of a given collection pass the given inspection function.
E
the type of element in the collection
C
the type of collection
max
the maximum number of elements that must pass the inspection function
xs
the collection of elements
fun
the inspection function
collecting
the implicit Collecting that can transform xs into a scala.collection.GenTraversable
def forBetween(from: Int, upTo: Int, xs: String)(fun: (Char) ⇒ Assertion)(implicit collecting: Collecting[Char, String]): Assertion

Ensure the number of characters of a given String that pass the given inspection function is between from and upTo.
Ensure the number of characters of a given String that pass the given inspection function is between from and upTo.
from
the minimum number of characters in the String that must pass the inspection number
upTo
the maximum number of characters in the String that must pass the inspection number
xs
the String
fun
the inspection function
collecting
the implicit Collecting that can transform xs into a scala.collection.GenTraversable
def forBetween[K, V, JMAP[k, v] <: Map[k, v]](from: Int, upTo: Int, xs: JMAP[K, V])(fun: (Entry[K, V]) ⇒ Assertion)(implicit collecting: Collecting[Entry[K, V], JMAP[K, V]]): Assertion

Ensure the number of elements in a given java.util.Map that pass the given inspection function is between from and upTo.
Ensure the number of elements in a given java.util.Map that pass the given inspection function is between from and upTo.
K
the type of key in the java.util.Map
V
the type of value in the java.util.Map
JMAP
subtype of java.util.Map
from
the minimum number of elements in the java.util.Map that must pass the inspection number
upTo
the maximum number of elements in the java.util.Map that must pass the inspection number
xs
the java.util.Map
fun
the inspection function
collecting
the implicit Collecting that can transform xs into a scala.collection.GenTraversable
def forBetween[E, C[_]](from: Int, upTo: Int, xs: C[E])(fun: (E) ⇒ Assertion)(implicit collecting: Collecting[E, C[E]]): Assertion

Ensure the number of elements of a given collection that pass the given inspection function is between from and upTo.
Ensure the number of elements of a given collection that pass the given inspection function is between from and upTo.
E
the type of element in the collection
C
the type of collection
from
the minimum number of elements that must pass the inspection number
upTo
the maximum number of elements that must pass the inspection number
xs
the collection of elements
fun
the inspection function
collecting
the implicit Collecting that can transform xs into a scala.collection.GenTraversable
def forEvery(xs: String)(fun: (Char) ⇒ Assertion)(implicit collecting: Collecting[Char, String]): Assertion

Ensure that every character in a given String passes the given inspection function, where "pass" means returning normally from the function (i.e., without throwing an exception).
Ensure that every character in a given String passes the given inspection function, where "pass" means returning normally from the function (i.e., without throwing an exception).
The difference between forEvery and forAll is that forEvery will continue to inspect all characters in the String after first failure, and report all failures, whereas forAll will stop on (and only report) the first failure.
xs
the String
fun
the inspection function
collecting
the implicit Collecting that can transform xs into a scala.collection.GenTraversable
def forEvery[K, V, JMAP[k, v] <: Map[k, v]](xs: JMAP[K, V])(fun: (Entry[K, V]) ⇒ Assertion)(implicit collecting: Collecting[Entry[K, V], JMAP[K, V]]): Assertion

Ensure that every element in a given java.util.Map passes the given inspection function, where "pass" means returning normally from the function (i.e., without throwing an exception).
Ensure that every element in a given java.util.Map passes the given inspection function, where "pass" means returning normally from the function (i.e., without throwing an exception).
The difference between forEvery and forAll is that forEvery will continue to inspect all elements in the java.util.Map after first failure, and report all failures, whereas forAll will stop on (and only report) the first failure.
K
the type of key in the java.util.Map
V
the type of value in the java.util.Map
JMAP
subtype of java.util.Map
xs
the java.util.Map
fun
the inspection function
collecting
the implicit Collecting that can transform xs into a scala.collection.GenTraversable
def forEvery[E, C[_]](xs: C[E])(fun: (E) ⇒ Assertion)(implicit collecting: Collecting[E, C[E]]): Assertion

Ensure that every element in a given collection passes the given inspection function, where "pass" means returning normally from the function (i.e., without throwing an exception).
Ensure that every element in a given collection passes the given inspection function, where "pass" means returning normally from the function (i.e., without throwing an exception).
The difference between forEvery and forAll is that forEvery will continue to inspect all elements after first failure, and report all failures, whereas forAll will stop on (and only report) the first failure.
E
the type of element in the collection
C
the type of collection
xs
the collection of elements
fun
the inspection function
collecting
the implicit Collecting that can transform xs into a scala.collection.GenTraversable
def forExactly(succeededCount: Int, xs: String)(fun: (Char) ⇒ Assertion)(implicit collecting: Collecting[Char, String]): Assertion

Ensure that exactly succeededCount number of characters in a given String pass the given inspection function.
Ensure that exactly succeededCount number of characters in a given String pass the given inspection function.
succeededCount
the number of characters in the String that must pass the inspection function
xs
the String
fun
the inspection function
collecting
the implicit Collecting that can transform xs into a scala.collection.GenTraversable
def forExactly[K, V, JMAP[k, v] <: Map[k, v]](succeededCount: Int, xs: JMAP[K, V])(fun: (Entry[K, V]) ⇒ Assertion)(implicit collecting: Collecting[Entry[K, V], JMAP[K, V]]): Assertion

Ensure that exactly succeededCount number of elements in a given java.util.Map pass the given inspection function.
Ensure that exactly succeededCount number of elements in a given java.util.Map pass the given inspection function.
K
the type of key in the java.util.Map
V
the type of value in the java.util.Map
JMAP
subtype of java.util.Map
succeededCount
the number of elements in the java.util.Map that must pass the inspection function
xs
the java.util.Map
fun
the inspection function
collecting
the implicit Collecting that can transform xs into a scala.collection.GenTraversable
def forExactly[E, C[_]](succeededCount: Int, xs: C[E])(fun: (E) ⇒ Assertion)(implicit collecting: Collecting[E, C[E]]): Assertion

Ensure that exactly succeededCount number of elements of a given collection pass the given inspection function.
Ensure that exactly succeededCount number of elements of a given collection pass the given inspection function.
E
the type of element in the collection
C
the type of collection
succeededCount
the number of elements that must pass the inspection function
xs
the collection of elements
fun
the inspection function
collecting
the implicit Collecting that can transform xs into a scala.collection.GenTraversable
final def getClass(): Class[_]

Definition Classes
AnyRef → Any
def hashCode(): Int

Definition Classes
AnyRef → Any
final def isInstanceOf[T0]: Boolean

Definition Classes
Any
final def ne(arg0: AnyRef): Boolean

Definition Classes
AnyRef
final def notify(): Unit

Definition Classes
AnyRef
final def notifyAll(): Unit

Definition Classes
AnyRef
val stackDepthAdjustment: Int
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( ... )
final def wait(arg0: Long, arg1: Int): Unit

Definition Classes
AnyRef
Annotations
@throws( ... )
final def wait(arg0: Long): Unit

Definition Classes
AnyRef
Annotations
@throws( ... )

Related Docs: object Inspectors | package scalatest

trait Inspectors extends AnyRef

Value Members

final def !=(arg0: Any): Boolean

final def ##(): Int

final def ==(arg0: Any): Boolean

final def asInstanceOf[T0]: T0

def clone(): AnyRef

final def eq(arg0: AnyRef): Boolean

def equals(arg0: Any): Boolean

def finalize(): Unit

def forAll(xs: String)(fun: (Char) ⇒ Assertion)(implicit collecting: Collecting[Char, String]): Assertion

def forAll[K, V, JMAP[k, v] <: Map[k, v]](xs: JMAP[K, V])(fun: (Entry[K, V]) ⇒ Assertion)(implicit collecting: Collecting[Entry[K, V], JMAP[K, V]]): Assertion

def forAll[E, C[_]](xs: C[E])(fun: (E) ⇒ Assertion)(implicit collecting: Collecting[E, C[E]]): Assertion

def forAtLeast(min: Int, xs: String)(fun: (Char) ⇒ Assertion)(implicit collecting: Collecting[Char, String]): Assertion

def forAtLeast[K, V, JMAP[k, v] <: Map[k, v]](min: Int, xs: JMAP[K, V])(fun: (Entry[K, V]) ⇒ Assertion)(implicit collecting: Collecting[Entry[K, V], JMAP[K, V]]): Assertion

def forAtLeast[E, C[_]](min: Int, xs: C[E])(fun: (E) ⇒ Assertion)(implicit collecting: Collecting[E, C[E]]): Assertion

def forAtMost(max: Int, xs: String)(fun: (Char) ⇒ Assertion)(implicit collecting: Collecting[Char, String]): Assertion

def forAtMost[K, V, JMAP[k, v] <: Map[k, v]](max: Int, xs: JMAP[K, V])(fun: (Entry[K, V]) ⇒ Assertion)(implicit collecting: Collecting[Entry[K, V], JMAP[K, V]]): Assertion

def forAtMost[E, C[_]](max: Int, xs: C[E])(fun: (E) ⇒ Assertion)(implicit collecting: Collecting[E, C[E]]): Assertion

def forBetween(from: Int, upTo: Int, xs: String)(fun: (Char) ⇒ Assertion)(implicit collecting: Collecting[Char, String]): Assertion

def forBetween[K, V, JMAP[k, v] <: Map[k, v]](from: Int, upTo: Int, xs: JMAP[K, V])(fun: (Entry[K, V]) ⇒ Assertion)(implicit collecting: Collecting[Entry[K, V], JMAP[K, V]]): Assertion

def forBetween[E, C[_]](from: Int, upTo: Int, xs: C[E])(fun: (E) ⇒ Assertion)(implicit collecting: Collecting[E, C[E]]): Assertion

def forEvery(xs: String)(fun: (Char) ⇒ Assertion)(implicit collecting: Collecting[Char, String]): Assertion

def forEvery[K, V, JMAP[k, v] <: Map[k, v]](xs: JMAP[K, V])(fun: (Entry[K, V]) ⇒ Assertion)(implicit collecting: Collecting[Entry[K, V], JMAP[K, V]]): Assertion

def forEvery[E, C[_]](xs: C[E])(fun: (E) ⇒ Assertion)(implicit collecting: Collecting[E, C[E]]): Assertion

def forExactly(succeededCount: Int, xs: String)(fun: (Char) ⇒ Assertion)(implicit collecting: Collecting[Char, String]): Assertion

def forExactly[K, V, JMAP[k, v] <: Map[k, v]](succeededCount: Int, xs: JMAP[K, V])(fun: (Entry[K, V]) ⇒ Assertion)(implicit collecting: Collecting[Entry[K, V], JMAP[K, V]]): Assertion

def forExactly[E, C[_]](succeededCount: Int, xs: C[E])(fun: (E) ⇒ Assertion)(implicit collecting: Collecting[E, C[E]]): Assertion

final def getClass(): Class[_]

def hashCode(): Int

final def isInstanceOf[T0]: Boolean

final def ne(arg0: AnyRef): Boolean

final def notify(): Unit

final def notifyAll(): Unit

val stackDepthAdjustment: Int

final def synchronized[T0](arg0: ⇒ T0): T0

def toString(): String

final def wait(): Unit

final def wait(arg0: Long, arg1: Int): Unit

final def wait(arg0: Long): Unit

Inherited from AnyRef

Inherited from Any

Ungrouped