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`.

authors:

1. Bill Venners

Inherited

1. Hide All
2. Show all

1. Function1
2. AnyRef
3. Any

Visibility

1. Public
2. All

### Value Members

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

   attributes: final
   definition classes: AnyRef

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

   `o != arg0` is the same as `!(o == (arg0))`.

   `o != arg0` is the same as `!(o == (arg0))`.

   arg0

     the object to compare against this object for dis-equality.

   returns

     `false` if the receiver object is equivalent to the argument; `true` otherwise.

   attributes: final
   definition classes: Any

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

   attributes: final
   definition classes: AnyRef → Any

4. #### def $asInstanceOf[T0](): T0

   attributes: final
   definition classes: AnyRef

5. #### def $isInstanceOf[T0](): Boolean

   attributes: final
   definition classes: AnyRef

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

   `o == arg0` is the same as `if (o eq null) arg0 eq null else o.equals(arg0)`.

   `o == arg0` is the same as `if (o eq null) arg0 eq null else o.equals(arg0)`.

   arg0

     the object to compare against this object for equality.

   returns

     `true` if the receiver object is equivalent to the argument; `false` otherwise.

   attributes: final
   definition classes: AnyRef

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

   `o == arg0` is the same as `o.equals(arg0)`.

   `o == arg0` is the same as `o.equals(arg0)`.

   arg0

     the object to compare against this object for equality.

   returns

     `true` if the receiver object is equivalent to the argument; `false` otherwise.

   attributes: final
   definition classes: Any

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

   definition classes: Function1

9. #### 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

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

    This method is used to cast the receiver object to be of type `T0`.

    This method is used to cast the receiver object to be of type `T0`.

    Note that the success of a cast at runtime is modulo Scala's erasure semantics. Therefore the expression`1.asInstanceOf[String]` will throw a `ClassCastException` at runtime, while the expression`List(1).asInstanceOf[List[String]]` will not. In the latter example, because the type argument is erased as part of compilation it is not possible to check whether the contents of the list are of the requested typed.

    returns

      the receiver object.

    attributes: final
    definition classes: Any

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

    This method creates and returns a copy of the receiver object.

    This method creates and returns a copy of the receiver object.

    The default implementation of the `clone` method is platform dependent.

    returns

      a copy of the receiver object.

    attributes: protected
    definition classes: AnyRef

12. #### def compose[A](g: (A) ⇒ T): (A) ⇒ MatchResult

    definition classes: Function1

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

    This method is used to test whether the argument (`arg0`) is a reference to the receiver object (`this`).

    This method is used to test whether the argument (`arg0`) is a reference to the receiver object (`this`).

    The `eq` method implements an [http://en.wikipedia.org/wiki/Equivalence_relation equivalence relation] on non-null instances of `AnyRef`: * It is reflexive: for any non-null instance `x` of type `AnyRef`, `x.eq(x)` returns `true`. * It is symmetric: for any non-null instances `x` and `y` of type `AnyRef`, `x.eq(y)` returns `true` if and only if `y.eq(x)` returns `true`. * It is transitive: for any non-null instances `x`, `y`, and `z` of type `AnyRef` if `x.eq(y)` returns `true` and `y.eq(z)` returns `true`, then `x.eq(z)` returns `true`.

    Additionally, the `eq` method has three other properties. * It is consistent: for any non-null instances `x` and `y` of type `AnyRef`, multiple invocations of `x.eq(y)` consistently returns `true` or consistently returns `false`. * For any non-null instance `x` of type `AnyRef`, `x.eq(null)` and `null.eq(x)` returns `false`. * `null.eq(null)` returns `true`.

    When overriding the `equals` or `hashCode` methods, it is important to ensure that their behavior is consistent with reference equality. Therefore, if two objects are references to each other (`o1 eq o2`), they should be equal to each other (`o1 == o2`) and they should hash to the same value (`o1.hashCode == o2.hashCode`).

    arg0

      the object to compare against this object for reference equality.

    returns

      `true` if the argument is a reference to the receiver object; `false` otherwise.

    attributes: final
    definition classes: AnyRef

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

    This method is used to compare the receiver object (`this`) with the argument object (`arg0`) for equivalence.

    This method is used to compare the receiver object (`this`) with the argument object (`arg0`) for equivalence.

    The default implementations of this method is an [http://en.wikipedia.org/wiki/Equivalence_relation equivalence relation]: * It is reflexive: for any instance `x` of type `Any`, `x.equals(x)` should return `true`. * It is symmetric: for any instances `x` and `y` of type `Any`, `x.equals(y)` should return `true` if and only if `y.equals(x)` returns `true`. * It is transitive: for any instances `x`, `y`, and `z` of type `AnyRef` if `x.equals(y)` returns `true` and `y.equals(z)` returns `true`, then `x.equals(z)` should return `true`.

    If you override this method, you should verify that your implementation remains an equivalence relation. Additionally, when overriding this method it is often necessary to override `hashCode` to ensure that objects that are "equal" (`o1.equals(o2)` returns `true`) hash to the same scala.Int (`o1.hashCode.equals(o2.hashCode)`).

    arg0

      the object to compare against this object for equality.

    returns

      `true` if the receiver object is equivalent to the argument; `false` otherwise.

    definition classes: AnyRef → Any

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

    This method is called by the garbage collector on the receiver object when garbage collection determines that there are no more references to the object.

    This method is called by the garbage collector on the receiver object when garbage collection determines that there are no more references to the object.

    The details of when and if the `finalize` method are invoked, as well as the interaction between `finalize`and non-local returns and exceptions, are all platform dependent.

    attributes: protected
    definition classes: AnyRef

16. #### def getClass(): java.lang.Class[_ <: java.lang.Object]

    Returns a representation that corresponds to the dynamic class of the receiver object.

    Returns a representation that corresponds to the dynamic class of the receiver object.

    The nature of the representation is platform dependent.

    returns

      a representation that corresponds to the dynamic class of the receiver object.

    attributes: final
    definition classes: AnyRef

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

    Returns a hash code value for the object.

    Returns a hash code value for the object.

    The default hashing algorithm is platform dependent.

    Note that it is allowed for two objects to have identical hash codes (`o1.hashCode.equals(o2.hashCode)`) yet not be equal (`o1.equals(o2)` returns `false`). A degenerate implementation could always return `0`. However, it is required that if two objects are equal (`o1.equals(o2)` returns `true`) that they have identical hash codes (`o1.hashCode.equals(o2.hashCode)`). Therefore, when overriding this method, be sure to verify that the behavior is consistent with the `equals` method.

    returns

      the hash code value for the object.

    definition classes: AnyRef → Any

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

    This method is used to test whether the dynamic type of the receiver object is `T0`.

    This method is used to test whether the dynamic type of the receiver object is `T0`.

    Note that the test result of the test is modulo Scala's erasure semantics. Therefore the expression`1.isInstanceOf[String]` will return `false`, while the expression `List(1).isInstanceOf[List[String]]` will return `true`. In the latter example, because the type argument is erased as part of compilation it is not possible to check whether the contents of the list are of the requested typed.

    returns

      `true` if the receiver object is an instance of erasure of type `T0`; `false` otherwise.

    attributes: final
    definition classes: Any

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

    `o.ne(arg0)` is the same as `!(o.eq(arg0))`.

    `o.ne(arg0)` is the same as `!(o.eq(arg0))`.

    arg0

      the object to compare against this object for reference dis-equality.

    returns

      `false` if the argument is not a reference to the receiver object; `true` otherwise.

    attributes: final
    definition classes: AnyRef

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

    Wakes up a single thread that is waiting on the receiver object's monitor.

    Wakes up a single thread that is waiting on the receiver object's monitor.

    attributes: final
    definition classes: AnyRef

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

    Wakes up all threads that are waiting on the receiver object's monitor.

    Wakes up all threads that are waiting on the receiver object's monitor.

    attributes: final
    definition classes: AnyRef

22. #### def synchronized[T0](arg0: T0): T0

    attributes: final
    definition classes: AnyRef

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

    Returns a string representation of the object.

    Returns a string representation of the object.

    The default representation is platform dependent.

    returns

      a string representation of the object.

    definition classes: Function1 → AnyRef → Any

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

    attributes: final
    definition classes: AnyRef

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

    attributes: final
    definition classes: AnyRef

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

    attributes: final
    definition classes: AnyRef