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 matchers
    Definition Classes
    scalatest
  • trait Matcher[-T] extends (T) ⇒ MatchResult

    Trait extended by objects that can match a value of the specified type.

    Trait extended by objects that can match a value of the specified type. The value to match is passed to the matcher's apply method. The result is a MatchResult. A matcher is, therefore, a function from the specified type, T, to a MatchResult.

    Creating custom matchers

    If none of the built-in matcher syntax satisfies a particular need you have, you can create custom Matchers that allow you to place your own syntax directly after should. For example, although you can ensure that a java.io.File has a name that ends with a particular extension like this:

    file.getName should endWith (".txt")
    

    You might prefer to create a custom Matcher[java.io.File] named endWithExtension, so you could write expressions like:

    file should endWithExtension ("txt")
    file should not endWithExtension "txt"
    file should (exist and endWithExtension ("txt"))
    

    One good way to organize custom matchers is to place them inside one or more traits that you can then mix into the suites that need them. Here's an example:

    import org.scalatest._
    import matchers._
    
    trait CustomMatchers {
    class FileEndsWithExtensionMatcher(expectedExtension: String) extends Matcher[java.io.File] {
    def apply(left: java.io.File) = { val name = left.getName MatchResult( name.endsWith(expectedExtension), s"""File $name did not end with extension "$expectedExtension"""", s"""File $name ended with extension "$expectedExtension"""" ) } }
    def endWithExtension(expectedExtension: String) = new FileEndsWithExtensionMatcher(expectedExtension) }
    // Make them easy to import with: // import CustomMatchers._ object CustomMatchers extends CustomMatchers

    Note: the CustomMatchers companion object exists to make it easy to bring the matchers defined in this trait into scope via importing, instead of mixing in the trait. The ability to import them is useful, for example, when you want to use the matchers defined in a trait in the Scala interpreter console.

    This trait contains one matcher class, FileEndsWithExtensionMatcher, and a def named endWithExtension that returns a new instance of FileEndsWithExtensionMatcher. Because the class extends Matcher[java.io.File], the compiler will only allow it be used to match against instances of java.io.File. A matcher must declare an apply method that takes the type decared in Matcher's type parameter, in this case java.io.File. The apply method will return a MatchResult whose matches field will indicate whether the match succeeded. The failureMessage field will provide a programmer-friendly error message indicating, in the event of a match failure, what caused the match to fail.

    The FileEndsWithExtensionMatcher matcher in this example determines success by determining if the passed java.io.File ends with the desired extension. It does this in the first argument passed to the MatchResult factory method:

    name.endsWith(expectedExtension)
    

    In other words, if the file name has the expected extension, this matcher matches. The next argument to MatchResult's factory method produces the failure message string:

    s"""File $name did not end with extension "$expectedExtension"""",
    

    For example, consider this matcher expression:

    import org.scalatest._
    import Matchers._
    import java.io.File
    import CustomMatchers._
    
    new File("essay.text") should endWithExtension ("txt")

    Because the passed java.io.File has the name essay.text, but the expected extension is "txt", the failure message would be:

    File essay.text did not have extension "txt"
    

    For more information on the fields in a MatchResult, including the subsequent field (or fields) that follow the failure message, please see the documentation for MatchResult.

    Creating dynamic matchers

    There are other ways to create new matchers besides defining one as shown above. For example, you might check that a file is hidden like this:

    new File("secret.txt") should be ('hidden)
    

    If you wanted to get rid of the tick mark, you could simply define hidden like this:

    val hidden = 'hidden
    

    Now you can check that an file is hidden without the tick mark:

    new File("secret.txt") should be (hidden)
    

    You could get rid of the parens with by using shouldBe:

    new File("secret.txt") shouldBe hidden
    

    Creating matchers using logical operators

    You can also use ScalaTest matchers' logical operators to combine existing matchers into new ones, like this:

    val beWithinTolerance = be >= 0 and be <= 10
    

    Now you could check that a number is within the tolerance (in this case, between 0 and 10, inclusive), like this:

    num should beWithinTolerance
    

    When defining a full blown matcher, one shorthand is to use one of the factory methods in Matcher's companion object. For example, instead of writing this:

    val beOdd =
      new Matcher[Int] {
        def apply(left: Int) =
          MatchResult(
            left % 2 == 1,
            left + " was not odd",
            left + " was odd"
          )
      }
    

    You could alternately write this:

    val beOdd =
      Matcher { (left: Int) =>
        MatchResult(
          left % 2 == 1,
          left + " was not odd",
          left + " was odd"
        )
      }
    

    Either way you define the beOdd matcher, you could use it like this:

    3 should beOdd
    4 should not (beOdd)
    

    Composing matchers

    You can also compose matchers. For example, the endWithExtension matcher from the example above can be more easily created by composing a function with the existing endWith matcher:

    scala> import org.scalatest._
    import org.scalatest._
    
    scala> import Matchers._
    import Matchers._
    
    scala> import java.io.File
    import java.io.File
    
    scala> def endWithExtension(ext: String) = endWith(ext) compose { (f: File) => f.getPath }
    endWithExtension: (ext: String)org.scalatest.matchers.Matcher[java.io.File]
    

    Now you have a Matcher[File] whose apply method first invokes the converter function to convert the passed File to a String, then passes the resulting String to endWith. Thus, you could use this version endWithExtension like the previous one:

    scala> new File("output.txt") should endWithExtension("txt")
    

    In addition, by composing twice, you can modify the type of both sides of a match statement with the same function, like this:

    scala> val f = be > (_: Int)
    f: Int => org.scalatest.matchers.Matcher[Int] = <function1>
    
    scala> val g = (_: String).toInt
    g: String => Int = <function1>
    
    scala> val beAsIntsGreaterThan = (f compose g) andThen (_ compose g)
    beAsIntsGreaterThan: String => org.scalatest.matchers.Matcher[String] = <function1>
    
    scala> "8" should beAsIntsGreaterThan ("7")
    

    At thsi point, however, the error message for the beAsIntsGreaterThan gives no hint that the Ints being compared were parsed from Strings:

    scala> "7" should beAsIntsGreaterThan ("8")
    org.scalatest.exceptions.TestFailedException: 7 was not greater than 8
    

    To modify error message, you can use trait MatcherProducers, which also provides a composeTwice method that performs the compose ... andThen ... compose operation:

    scala> import matchers._
    import matchers._
    
    scala> import MatcherProducers._
    import MatcherProducers._
    
    scala> val beAsIntsGreaterThan = f composeTwice g // means: (f compose g) andThen (_ compose g)
    beAsIntsGreaterThan: String => org.scalatest.matchers.Matcher[String] = <function1>
    
    scala> "8" should beAsIntsGreaterThan ("7")
    

    Of course, the error messages is still the same:

    scala> "7" should beAsIntsGreaterThan ("8")
    org.scalatest.exceptions.TestFailedException: 7 was not greater than 8
    

    To modify the error messages, you can use mapResult from MatcherProducers. Here's an example:

    scala> val beAsIntsGreaterThan =
      f composeTwice g mapResult { mr =>
        mr.copy(
          failureMessageArgs =
            mr.failureMessageArgs.map((LazyArg(_) { "\"" + _.toString + "\".toInt"})),
          negatedFailureMessageArgs =
            mr.negatedFailureMessageArgs.map((LazyArg(_) { "\"" + _.toString + "\".toInt"})),
          midSentenceFailureMessageArgs =
            mr.midSentenceFailureMessageArgs.map((LazyArg(_) { "\"" + _.toString + "\".toInt"})),
          midSentenceNegatedFailureMessageArgs =
            mr.midSentenceNegatedFailureMessageArgs.map((LazyArg(_) { "\"" + _.toString + "\".toInt"}))
        )
      }
    beAsIntsGreaterThan: String => org.scalatest.matchers.Matcher[String] = <function1>
    

    The mapResult method takes a function that accepts a MatchResult and produces a new MatchResult, which can contain modified arguments and modified error messages. In this example, the error messages are being modified by wrapping the old arguments in LazyArg instances that lazily apply the given prettification functions to the toString result of the old args. Now the error message is clearer:

    scala> "7" should beAsIntsGreaterThan ("8")
    org.scalatest.exceptions.TestFailedException: "7".toInt was not greater than "8".toInt
    

    Matcher's variance

    Matcher is contravariant in its type parameter, T, to make its use more flexible. As an example, consider the hierarchy:

    class Fruit
    class Orange extends Fruit
    class ValenciaOrange extends Orange
    

    Given an orange:

    val orange = Orange
    

    The expression "orange should" will, via an implicit conversion in Matchers, result in an object that has a should method that takes a Matcher[Orange]. If the static type of the matcher being passed to should is Matcher[Valencia] it shouldn't (and won't) compile. The reason it shouldn't compile is that the left value is an Orange, but not necessarily a Valencia, and a Matcher[Valencia] only knows how to match against a Valencia. The reason it won't compile is given that Matcher is contravariant in its type parameter, T, a Matcher[Valencia] is not a subtype of Matcher[Orange].

    By contrast, if the static type of the matcher being passed to should is Matcher[Fruit], it should (and will) compile. The reason it should compile is that given the left value is an Orange, it is also a Fruit, and a Matcher[Fruit] knows how to match against Fruits. The reason it will compile is that given that Matcher is contravariant in its type parameter, T, a Matcher[Fruit] is indeed a subtype of Matcher[Orange].

    Definition Classes
    matchers
  • AndBeWord
  • AndContainWord
  • AndEndWithWord
  • AndFullyMatchWord
  • AndHaveWord
  • AndIncludeWord
  • AndNotWord
  • AndStartWithWord
  • OrBeWord
  • OrContainWord
  • OrEndWithWord
  • OrFullyMatchWord
  • OrHaveWord
  • OrIncludeWord
  • OrNotWord
  • OrStartWithWord

final class AndContainWord extends AnyRef

This class is part of the ScalaTest matchers DSL. Please see the documentation for Matchers for an overview of the matchers DSL.

Source
Matcher.scala
Linear Supertypes
AnyRef, Any
Ordering
  1. Alphabetic
  2. By Inheritance
Inherited
  1. AndContainWord
  2. AnyRef
  3. Any
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. All

Instance Constructors

  1. new AndContainWord(prettifier: Prettifier, pos: Position)

Value Members

  1. final def !=(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  2. final def ##(): Int
    Definition Classes
    AnyRef → Any
  3. final def ==(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  4. def allElementsOf(elements: GenTraversable[Any]): MatcherFactory1[T, Aggregating]

    This method enables the following syntax:

    This method enables the following syntax:

    aMatcher and contain allElementsOf List(1, 2, 3)
                         ^
    

  5. def allOf(firstEle: Any, secondEle: Any, remainingEles: Any*): MatcherFactory1[T, Aggregating]

    This method enables the following syntax:

    This method enables the following syntax:

    aMatcher and contain allOf (1, 2, 3)
                         ^
    

  6. def apply[U](expectedElement: Any): MatcherFactory1[T with U, Containing]

    This method enables the following syntax:

    This method enables the following syntax:

    aMatcher and contain (3 - 1)
                         ^
    

  7. final def asInstanceOf[T0]: T0
    Definition Classes
    Any
  8. def atLeastOneElementOf(elements: GenTraversable[Any]): MatcherFactory1[T, Aggregating]

    This method enables the following syntax:

    This method enables the following syntax:

    aMatcher and contain atLeastOneElementOf (1, 2, 3)
                         ^
    

  9. def atLeastOneOf(firstEle: Any, secondEle: Any, remainingEles: Any*): MatcherFactory1[T, Aggregating]

    This method enables the following syntax:

    This method enables the following syntax:

    aMatcher and contain atLeastOneOf (1, 2, 3)
                         ^
    

  10. def atMostOneElementOf(elements: GenTraversable[Any]): MatcherFactory1[T, Aggregating]

    This method enables the following syntax:

    This method enables the following syntax:

    aMatcher and contain atMostOneElementOf List(1, 2, 3)
                         ^
    

  11. def atMostOneOf(firstEle: Any, secondEle: Any, remainingEles: Any*): MatcherFactory1[T, Aggregating]

    This method enables the following syntax:

    This method enables the following syntax:

    aMatcher and contain atMostOneOf (1, 2, 3)
                         ^
    

  12. def clone(): AnyRef
    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @native() @throws( ... )
  13. final def eq(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  14. def equals(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  15. def finalize(): Unit
    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @throws( classOf[java.lang.Throwable] )
  16. final def getClass(): Class[_]
    Definition Classes
    AnyRef → Any
    Annotations
    @native()
  17. def hashCode(): Int
    Definition Classes
    AnyRef → Any
    Annotations
    @native()
  18. def inOrder(firstEle: Any, secondEle: Any, remainingEles: Any*): MatcherFactory1[T, Sequencing]

    This method enables the following syntax:

    This method enables the following syntax:

    aMatcher and contain inOrder (1, 2, 3)
                         ^
    

  19. def inOrderElementsOf(elements: GenTraversable[Any]): MatcherFactory1[T, Sequencing]

    This method enables the following syntax:

    This method enables the following syntax:

    aMatcher and contain inOrderElementsOf List(1, 2, 3)
                         ^
    

  20. def inOrderOnly(firstEle: Any, secondEle: Any, remainingEles: Any*): MatcherFactory1[T, Sequencing]

    This method enables the following syntax:

    This method enables the following syntax:

    aMatcher and contain inOrderOnly (1, 2, 3)
                         ^
    

  21. final def isInstanceOf[T0]: Boolean
    Definition Classes
    Any
  22. def key(expectedKey: Any): MatcherFactory1[T, KeyMapping]

    This method enables the following syntax:

    This method enables the following syntax:

    aMatcher and contain key ("one")
                         ^
    

  23. final def ne(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  24. def noElementsOf(elements: GenTraversable[Any]): MatcherFactory1[T, Containing]

    This method enables the following syntax:

    This method enables the following syntax:

    aMatcher and contain noElementsOf (1, 2, 3)
                         ^
    

  25. def noneOf(firstEle: Any, secondEle: Any, remainingEles: Any*): MatcherFactory1[T, Containing]

    This method enables the following syntax:

    This method enables the following syntax:

    aMatcher and contain noneOf (1, 2, 3)
                         ^
    

  26. final def notify(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native()
  27. final def notifyAll(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native()
  28. def oneElementOf(elements: GenTraversable[Any]): MatcherFactory1[T, Containing]

    This method enables the following syntax:

    This method enables the following syntax:

    aMatcher and contain oneElementOf List(1, 2, 3)
                         ^
    

  29. def oneOf(firstEle: Any, secondEle: Any, remainingEles: Any*): MatcherFactory1[T, Containing]

    This method enables the following syntax:

    This method enables the following syntax:

    aMatcher and contain oneOf (1, 2, 3)
                         ^
    

  30. def only(right: Any*): MatcherFactory1[T, Aggregating]

    This method enables the following syntax:

    This method enables the following syntax:

    aMatcher and contain only (1, 2, 3)
                         ^
    

  31. final def synchronized[T0](arg0: ⇒ T0): T0
    Definition Classes
    AnyRef
  32. def theSameElementsAs(right: GenTraversable[_]): MatcherFactory1[T, Aggregating]

    This method enables the following syntax:

    This method enables the following syntax:

    aMatcher and contain theSameElementsAs List(1, 2, 3)
                         ^
    

  33. def theSameElementsInOrderAs(right: GenTraversable[_]): MatcherFactory1[T, Sequencing]

    This method enables the following syntax:

    This method enables the following syntax:

    aMatcher and contain theSameElementsInOrderAs List(1, 2, 3)
                         ^
    

  34. def toString(): String
    Definition Classes
    AnyRef → Any
  35. def value(expectedValue: Any): MatcherFactory1[T, ValueMapping]

    This method enables the following syntax:

    This method enables the following syntax:

    aMatcher and contain value (1)
                         ^
    

  36. final def wait(): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  37. final def wait(arg0: Long, arg1: Int): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  38. final def wait(arg0: Long): Unit
    Definition Classes
    AnyRef
    Annotations
    @native() @throws( ... )

Inherited from AnyRef

Inherited from Any

Ungrouped