org.scalatest.matchers

# BeMatcher

#### 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 `BeMatcher`s, 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 `BeMatcher`s 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 `BeMatcher`s 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]

Linear Supertypes
(T) ⇒ MatchResult, AnyRef, Any
Ordering

1. Alphabetic
2. By inheritance

Inherited

1. Hide All
2. Show all

1. BeMatcher
2. Function1
3. AnyRef
4. Any

Visibility

1. Public
2. All

### Abstract Value Members

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

   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

   Attributes
     abstract
   Definition Classes
     BeMatcher → Function1

### Concrete Value Members

1. #### def != (arg0: AnyRef): Boolean

   Attributes
     final
   Definition Classes
     AnyRef

2. #### def != (arg0: Any): Boolean

   Attributes
     final
   Definition Classes
     Any

3. #### def ## (): Int

   Attributes
     final
   Definition Classes
     AnyRef → Any

4. #### def == (arg0: AnyRef): Boolean

   Attributes
     final
   Definition Classes
     AnyRef

5. #### def == (arg0: Any): Boolean

   Attributes
     final
   Definition Classes
     Any

6. #### def andThen [A] (g: (MatchResult) ⇒ A): (T) ⇒ A

   Definition Classes
     Function1

7. #### def asInstanceOf [T0] : T0

   Attributes
     final
   Definition Classes
     Any

8. #### def clone (): AnyRef

   Attributes
     protected[lang]
   Definition Classes
     AnyRef
   Annotations
     @throws()

9. #### def compose [U] (g: (U) ⇒ T): BeMatcher[U]

   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

10. #### def eq (arg0: AnyRef): Boolean

    Attributes
      final
    Definition Classes
      AnyRef

11. #### def equals (arg0: Any): Boolean

    Definition Classes
      AnyRef → Any

12. #### def finalize (): Unit

    Attributes
      protected[lang]
    Definition Classes
      AnyRef
    Annotations
      @throws()

13. #### def getClass (): java.lang.Class[_]

    Attributes
      final
    Definition Classes
      AnyRef

14. #### def hashCode (): Int

    Definition Classes
      AnyRef → Any

15. #### def isInstanceOf [T0] : Boolean

    Attributes
      final
    Definition Classes
      Any

16. #### def ne (arg0: AnyRef): Boolean

    Attributes
      final
    Definition Classes
      AnyRef

17. #### def notify (): Unit

    Attributes
      final
    Definition Classes
      AnyRef

18. #### def notifyAll (): Unit

    Attributes
      final
    Definition Classes
      AnyRef

19. #### def synchronized [T0] (arg0: ⇒ T0): T0

    Attributes
      final
    Definition Classes
      AnyRef

20. #### def toString (): String

    Definition Classes
      Function1 → AnyRef → Any

21. #### def wait (): Unit

    Attributes
      final
    Definition Classes
      AnyRef
    Annotations
      @throws()

22. #### def wait (arg0: Long, arg1: Int): Unit

    Attributes
      final
    Definition Classes
      AnyRef
    Annotations
      @throws()

23. #### def wait (arg0: Long): Unit

    Attributes
      final
    Definition Classes
      AnyRef
    Annotations
      @throws()

### Inherited from (T) ⇒ MatchResult

### Inherited from AnyRef

### Inherited from Any