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

  Classes and traits for matchers.

  Classes and traits for matchers.

  This package is released as part of the scalatest-matchers-core module.

  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

org.scalatest.matchers.Matcher

OrBeWord