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 OrIncludeWord 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. OrIncludeWord
  2. AnyRef
  3. Any
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. All

Instance Constructors

  1. new OrIncludeWord()

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. final def asInstanceOf[T0]: T0
    Definition Classes
    Any
  5. def clone(): AnyRef
    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  6. final def eq(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  7. def equals(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  8. def finalize(): Unit
    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @throws( classOf[java.lang.Throwable] )
  9. final def getClass(): Class[_]
    Definition Classes
    AnyRef → Any
  10. def hashCode(): Int
    Definition Classes
    AnyRef → Any
  11. final def isInstanceOf[T0]: Boolean
    Definition Classes
    Any
  12. final def ne(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  13. final def notify(): Unit
    Definition Classes
    AnyRef
  14. final def notifyAll(): Unit
    Definition Classes
    AnyRef
  15. def regex(regex: Regex): Matcher[T with String]

    This method enables the following syntax:

    This method enables the following syntax:

    aMatcher or include regex (decimal)
                        ^
    

  16. def regex(regexWithGroups: RegexWithGroups): Matcher[T with String]

    This method enables the following syntax:

    This method enables the following syntax:

    aMatcher or include regex ("a(b*)c" withGroup "bb")
                        ^
    

  17. def regex(regexString: String): Matcher[T with String]

    This method enables the following syntax:

    This method enables the following syntax:

    aMatcher or include regex (decimal)
                        ^
    

  18. final def synchronized[T0](arg0: ⇒ T0): T0
    Definition Classes
    AnyRef
  19. def toString(): String
    Definition Classes
    AnyRef → Any
  20. final def wait(): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  21. final def wait(arg0: Long, arg1: Int): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  22. final def wait(arg0: Long): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )

Inherited from AnyRef

Inherited from Any

Ungrouped