BeMatcher

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

Although BeMatcher and Matcher represent very similar concepts, they have no inheritance relationship because Matcher is intended for use right after should or must whereas BeMatcher is intended for use right after be.

As an example, you could create BeMatcher[Int] called odd that would match any odd Int, and one called even that would match any even Int. Given this pair of BeMatchers, you could check whether an Int was odd or even with expressions like:

num should be (odd)
num should not be (even)

Here's is how you might define the odd and even BeMatchers:

trait CustomMatchers {

  class OddMatcher extends BeMatcher[Int] {
    def apply(left: Int) =
      MatchResult(
        left % 2 == 1,
        left.toString + " was even",
        left.toString + " was odd"
      )
  }
  val odd = new OddMatcher
  val even = not (odd)
}

// Make them easy to import with:
// import CustomMatchers._
object CustomMatchers extends CustomMatchers

These BeMatchers are defined inside a trait to make them easy to mix into any suite or spec that needs them. The CustomMatchers companion object exists to make it easy to bring the BeMatchers 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.

Here's an rather contrived example of how you might use odd and even:

class DoubleYourPleasureSuite extends FunSuite with MustMatchers with CustomMatchers {

  def doubleYourPleasure(i: Int): Int = i * 2

  test("The doubleYourPleasure method must return proper odd or even values")

    val evenNum = 2
    evenNum must be (even)
    doubleYourPleasure(evenNum) must be (even)

    val oddNum = 3
    oddNum must be (odd)
    doubleYourPleasure(oddNum) must be (odd) // This will fail
  }
}

The last assertion in the above test will fail with this failure message:

6 was even

For more information on MatchResult and the meaning of its fields, please see the documentation for MatchResult. To understand why BeMatcher is contravariant in its type parameter, see the section entitled "Matcher's variance" in the documentation for Matcher.