Trait/Object

org.scalatest.matchers

BeMatcher

Related Docs: object BeMatcher | package matchers

Permalink

trait BeMatcher[-T] extends (T) ⇒ MatchResult

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.

Self Type
BeMatcher[T]
Source
BeMatcher.scala
Linear Supertypes
(T) ⇒ MatchResult, AnyRef, Any
Ordering
  1. Alphabetic
  2. By Inheritance
Inherited
  1. BeMatcher
  2. Function1
  3. AnyRef
  4. Any
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. All

Abstract Value Members

  1. abstract def apply(left: T): MatchResult

    Permalink

    Check to see if the specified object, left, matches, and report the result in the returned MatchResult.

    Check to see if the specified object, left, matches, and report the result in the returned MatchResult. The parameter is named left, because it is usually the value to the left of a should or must invocation. For example, in:

    num should be (odd)
    

    The be (odd) expression results in a regular Matcher that holds a reference to odd, the BeMatcher passed to be. The should method invokes apply on this matcher, passing in num, which is therefore the "left" value. The matcher will pass num (the left value) to the BeMatcher's apply method.

    left

    the value against which to match

    returns

    the MatchResult that represents the result of the match

    Definition Classes
    BeMatcher → Function1

Concrete Value Members

  1. final def !=(arg0: Any): Boolean

    Permalink
    Definition Classes
    AnyRef → Any
  2. final def ##(): Int

    Permalink
    Definition Classes
    AnyRef → Any
  3. final def ==(arg0: Any): Boolean

    Permalink
    Definition Classes
    AnyRef → Any
  4. def andThen[A](g: (MatchResult) ⇒ A): (T) ⇒ A

    Permalink
    Definition Classes
    Function1
    Annotations
    @unspecialized()
  5. final def asInstanceOf[T0]: T0

    Permalink
    Definition Classes
    Any
  6. def clone(): AnyRef

    Permalink
    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  7. def compose[U](g: (U) ⇒ T): BeMatcher[U]

    Permalink

    Compose this BeMatcher with the passed function, returning a new BeMatcher.

    Compose this BeMatcher with the passed function, returning a new BeMatcher.

    This method overrides compose on Function1 to return a more specific function type of BeMatcher. For example, given an odd matcher defined like this:

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

    You could use odd like this:

    3 should be (odd)
    4 should not be (odd)
    

    If for some odd reason, you wanted a BeMatcher[String] that checked whether a string, when converted to an Int, was odd, you could make one by composing odd with a function that converts a string to an Int, like this:

    val oddAsInt = odd compose { (s: String) => s.toInt }
    

    Now you have a BeMatcher[String] whose apply method first invokes the converter function to convert the passed string to an Int, then passes the resulting Int to odd. Thus, you could use oddAsInt like this:

    "3" should be (oddAsInt)
    "4" should not be (oddAsInt)
    

    Definition Classes
    BeMatcher → Function1
  8. final def eq(arg0: AnyRef): Boolean

    Permalink
    Definition Classes
    AnyRef
  9. def equals(arg0: Any): Boolean

    Permalink
    Definition Classes
    AnyRef → Any
  10. def finalize(): Unit

    Permalink
    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @throws( classOf[java.lang.Throwable] )
  11. final def getClass(): Class[_]

    Permalink
    Definition Classes
    AnyRef → Any
  12. def hashCode(): Int

    Permalink
    Definition Classes
    AnyRef → Any
  13. final def isInstanceOf[T0]: Boolean

    Permalink
    Definition Classes
    Any
  14. final def ne(arg0: AnyRef): Boolean

    Permalink
    Definition Classes
    AnyRef
  15. final def notify(): Unit

    Permalink
    Definition Classes
    AnyRef
  16. final def notifyAll(): Unit

    Permalink
    Definition Classes
    AnyRef
  17. final def synchronized[T0](arg0: ⇒ T0): T0

    Permalink
    Definition Classes
    AnyRef
  18. def toString(): String

    Permalink
    Definition Classes
    Function1 → AnyRef → Any
  19. final def wait(): Unit

    Permalink
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  20. final def wait(arg0: Long, arg1: Int): Unit

    Permalink
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  21. final def wait(arg0: Long): Unit

    Permalink
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )

Inherited from (T) ⇒ MatchResult

Inherited from AnyRef

Inherited from Any

Ungrouped