trait Inspectors extends AnyRef
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 elementforAtLeast
- succeeds if the assertion holds true for at least the specified number of elementsforAtMost
- succeeds if the assertion holds true for at most the specified number of elementsforBetween
- succeeds if the assertion holds true for between the specified minimum and maximum number of elements, inclusiveforEvery
- same asforAll
, but lists all failing elements if it fails (whereasforAll
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$.forAll(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$.forAll(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$.forEvery(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$.forAll(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
- Alphabetic
- By Inheritance
- Inspectors
- AnyRef
- Any
- Hide All
- Show All
- Public
- All
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[ASSERTION](xs: String)(fun: (Char) ⇒ ASSERTION)(implicit collecting: Collecting[Char, String], asserting: InspectorAsserting[ASSERTION], prettifier: Prettifier, pos: Position): Unit
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
andforEvery
is thatforAll
will stop on the first failure, whileforEvery
will continue to inspect all characters in theString
after the first failure (and report all failures).- xs
the
String
- fun
the inspection function
- collecting
the implicit
Collecting
that can transformxs
into ascala.collection.GenTraversable
-
def
forAll[K, V, JMAP[k, v] <: Map[k, v], ASSERTION](xs: JMAP[K, V])(fun: (Entry[K, V]) ⇒ ASSERTION)(implicit collecting: Collecting[Entry[K, V], JMAP[K, V]], asserting: InspectorAsserting[ASSERTION], prettifier: Prettifier, pos: Position): Result
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
andforEvery
is thatforAll
will stop on the first failure, whileforEvery
will continue to inspect alljava.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 transformxs
into ascala.collection.GenTraversable
-
def
forAll[E, C[_], ASSERTION](xs: C[E])(fun: (E) ⇒ ASSERTION)(implicit collecting: Collecting[E, C[E]], asserting: InspectorAsserting[ASSERTION], prettifier: Prettifier, pos: Position): Result
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
andforEvery
is thatforAll
will stop on the first failure, whileforEvery
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 transformxs
into ascala.collection.GenTraversable
-
def
forAtLeast[ASSERTION](min: Int, xs: String)(fun: (Char) ⇒ ASSERTION)(implicit collecting: Collecting[Char, String], asserting: InspectorAsserting[ASSERTION], prettifier: Prettifier, pos: Position): Result
Ensure that at least
min
number of characters in a givenString
pass the given inspection function.Ensure that at least
min
number of characters in a givenString
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 transformxs
into ascala.collection.GenTraversable
-
def
forAtLeast[K, V, JMAP[k, v] <: Map[k, v], ASSERTION](min: Int, xs: JMAP[K, V])(fun: (Entry[K, V]) ⇒ ASSERTION)(implicit collecting: Collecting[Entry[K, V], JMAP[K, V]], asserting: InspectorAsserting[ASSERTION], prettifier: Prettifier, pos: Position): Result
Ensure that at least
min
number of elements in a givenjava.util.Map
pass the given inspection function.Ensure that at least
min
number of elements in a givenjava.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 transformxs
into ascala.collection.GenTraversable
-
def
forAtLeast[E, C[_], ASSERTION](min: Int, xs: C[E])(fun: (E) ⇒ ASSERTION)(implicit collecting: Collecting[E, C[E]], asserting: InspectorAsserting[ASSERTION], prettifier: Prettifier, pos: Position): Result
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 transformxs
into ascala.collection.GenTraversable
-
def
forAtMost[ASSERTION](max: Int, xs: String)(fun: (Char) ⇒ ASSERTION)(implicit collecting: Collecting[Char, String], asserting: InspectorAsserting[ASSERTION], prettifier: Prettifier, pos: Position): Result
Ensure that at most
max
number of characters in a givenString
pass the given inspection function.Ensure that at most
max
number of characters in a givenString
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 transformxs
into ascala.collection.GenTraversable
-
def
forAtMost[K, V, JMAP[k, v] <: Map[k, v], ASSERTION](max: Int, xs: JMAP[K, V])(fun: (Entry[K, V]) ⇒ ASSERTION)(implicit collecting: Collecting[Entry[K, V], JMAP[K, V]], asserting: InspectorAsserting[ASSERTION], prettifier: Prettifier, pos: Position): Result
Ensure that at most
max
number of elements in a givenjava.util.Map
pass the given inspection function.Ensure that at most
max
number of elements in a givenjava.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 transformxs
into ascala.collection.GenTraversable
-
def
forAtMost[E, C[_], ASSERTION](max: Int, xs: C[E])(fun: (E) ⇒ ASSERTION)(implicit collecting: Collecting[E, C[E]], asserting: InspectorAsserting[ASSERTION], prettifier: Prettifier, pos: Position): Result
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 transformxs
into ascala.collection.GenTraversable
-
def
forBetween[ASSERTION](from: Int, upTo: Int, xs: String)(fun: (Char) ⇒ ASSERTION)(implicit collecting: Collecting[Char, String], asserting: InspectorAsserting[ASSERTION], prettifier: Prettifier, pos: Position): Result
Ensure the number of characters of a given
String
that pass the given inspection function is betweenfrom
andupTo
.Ensure the number of characters of a given
String
that pass the given inspection function is betweenfrom
andupTo
.- 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 transformxs
into ascala.collection.GenTraversable
-
def
forBetween[K, V, JMAP[k, v] <: Map[k, v], ASSERTION](from: Int, upTo: Int, xs: JMAP[K, V])(fun: (Entry[K, V]) ⇒ ASSERTION)(implicit collecting: Collecting[Entry[K, V], JMAP[K, V]], asserting: InspectorAsserting[ASSERTION], prettifier: Prettifier, pos: Position): Result
Ensure the number of elements in a given
java.util.Map
that pass the given inspection function is betweenfrom
andupTo
.Ensure the number of elements in a given
java.util.Map
that pass the given inspection function is betweenfrom
andupTo
.- 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 transformxs
into ascala.collection.GenTraversable
-
def
forBetween[E, C[_], ASSERTION](from: Int, upTo: Int, xs: C[E])(fun: (E) ⇒ ASSERTION)(implicit collecting: Collecting[E, C[E]], asserting: InspectorAsserting[ASSERTION], prettifier: Prettifier, pos: Position): Result
Ensure the number of elements of a given collection that pass the given inspection function is between
from
andupTo
.Ensure the number of elements of a given collection that pass the given inspection function is between
from
andupTo
.- 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 transformxs
into ascala.collection.GenTraversable
-
def
forEvery[ASSERTION](xs: String)(fun: (Char) ⇒ ASSERTION)(implicit collecting: Collecting[Char, String], asserting: InspectorAsserting[ASSERTION], prettifier: Prettifier, pos: Position): Result
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
andforAll
is thatforEvery
will continue to inspect all characters in theString
after first failure, and report all failures, whereasforAll
will stop on (and only report) the first failure.- xs
the
String
- fun
the inspection function
- collecting
the implicit
Collecting
that can transformxs
into ascala.collection.GenTraversable
-
def
forEvery[K, V, JMAP[k, v] <: Map[k, v], ASSERTION](xs: JMAP[K, V])(fun: (Entry[K, V]) ⇒ ASSERTION)(implicit collecting: Collecting[Entry[K, V], JMAP[K, V]], asserting: InspectorAsserting[ASSERTION], prettifier: Prettifier, pos: Position): Result
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
andforAll
is thatforEvery
will continue to inspect all elements in thejava.util.Map
after first failure, and report all failures, whereasforAll
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 transformxs
into ascala.collection.GenTraversable
-
def
forEvery[E, C[_], ASSERTION](xs: C[E])(fun: (E) ⇒ ASSERTION)(implicit collecting: Collecting[E, C[E]], asserting: InspectorAsserting[ASSERTION], prettifier: Prettifier, pos: Position): Result
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
andforAll
is thatforEvery
will continue to inspect all elements after first failure, and report all failures, whereasforAll
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 transformxs
into ascala.collection.GenTraversable
-
def
forExactly[ASSERTION](succeededCount: Int, xs: String)(fun: (Char) ⇒ ASSERTION)(implicit collecting: Collecting[Char, String], asserting: InspectorAsserting[ASSERTION], prettifier: Prettifier, pos: Position): Result
Ensure that exactly
succeededCount
number of characters in a givenString
pass the given inspection function.Ensure that exactly
succeededCount
number of characters in a givenString
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 transformxs
into ascala.collection.GenTraversable
-
def
forExactly[K, V, JMAP[k, v] <: Map[k, v], ASSERTION](succeededCount: Int, xs: JMAP[K, V])(fun: (Entry[K, V]) ⇒ ASSERTION)(implicit collecting: Collecting[Entry[K, V], JMAP[K, V]], asserting: InspectorAsserting[ASSERTION], prettifier: Prettifier, pos: Position): Result
Ensure that exactly
succeededCount
number of elements in a givenjava.util.Map
pass the given inspection function.Ensure that exactly
succeededCount
number of elements in a givenjava.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 transformxs
into ascala.collection.GenTraversable
-
def
forExactly[E, C[_], ASSERTION](succeededCount: Int, xs: C[E])(fun: (E) ⇒ ASSERTION)(implicit collecting: Collecting[E, C[E]], asserting: InspectorAsserting[ASSERTION], prettifier: Prettifier, pos: Position): Result
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 transformxs
into ascala.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
-
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( ... )