org.scalatest.matchers

# HavePropertyMatcher

#### trait HavePropertyMatcher [-T, P] extends (T) ⇒ HavePropertyMatchResult[P]

Trait extended by matcher objects, which may appear after the word `have`, that can match against a property of the type specified by the `HavePropertyMatcher`'s second type parameter `P`.`HavePropertyMatcher`'s first type parameter, `T`, specifies the type that declares the property. The match will succeed if and only if the value of the property equals the specified value. The object containing the property is passed to the `HavePropertyMatcher`'s`apply` method. The result is a `HavePropertyMatchResult[P]`. A `HavePropertyMatcher` is, therefore, a function from the specified type, `T`, to a `HavePropertyMatchResult[P]`.

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

A `HavePropertyMatcher` essentially allows you to write statically typed property assertions similar to the dynamic ones that use symbols:

    book should have ('title ("Moby Dick")) // dynamic: uses reflection
    book should have (title ("Moby Dick"))  // type safe: only works on Books; no reflection used

One good way to organize custom matchers is to place them inside one or more traits that you can then mix into the suites or specs that need them. Here's an example that includes two methods that produce `HavePropertyMatcher`s:

    case class Book(val title: String, val author: String)trait CustomMatchers {  def title(expectedValue: String) =
        new HavePropertyMatcher[Book, String] {
          def apply(book: Book) =
            HavePropertyMatchResult(
              book.title == expectedValue,
              "title",
              expectedValue,
              book.title
            )
        }  def author(expectedValue: String) =
        new HavePropertyMatcher[Book, String] {
          def apply(book: Book) =
            HavePropertyMatchResult(
              book.author == expectedValue,
              "author",
              expectedValue,
              book.author
            )
        }
    }

Each time the `title` method is called, it returns a new `HavePropertyMatcher[Book, String]` that can be used to match against the `title` property of the `Book` passed to its `apply`method. Because the type parameter of these two `HavePropertyMatcher`s is `Book`, they can only be used with instances of that type. (The compiler will enforce this.) The match will succeed if the`title` property equals the value passed as `expectedValue`. If the match succeeds, the `matches` field of the returned `HavePropertyMatchResult` will be `true`. The second field, `propertyName`, is simply the string name of the property. The third and fourth fields, `expectedValue` and `actualValue` indicate the expected and actual values, respectively, for the property. Here's an example that uses these `HavePropertyMatchers`:

    class ExampleSpec extends Spec with ShouldMatchers with CustomMatchers {  describe("A book") {    it("should have the correct title and author") {      val book = Book("Moby Dick", "Melville")      book should have (
            title ("Moby Dick"),
            author ("Melville")
          )
        }
      }
    }

These matches should succeed, but if for example the first property, `title ("Moby Dick")`, were to fail, you would get an error message like:

    The title property had value "A Tale of Two Cities", instead of its expected value "Moby Dick",
    on object Book(A Tale of Two Cities,Dickens)

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

go to: companion
linear super types: (T) ⇒ HavePropertyMatchResult[P], AnyRef, Any
known subclasses: ResultOfSizeWordApplication, ResultOfLengthWordApplication
self type: HavePropertyMatcher[T, P]
Ordering

1. Alphabetic
2. By inheritance

Inherited

1. Hide All
2. Show all

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

Visibility

1. Public
2. All

Impl.

1. Concrete
2. Abstract

### 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: (HavePropertyMatchResult[P]) ⇒ A) : (T) ⇒ A

   definition classes: Function1

9. #### def apply (objectWithProperty: T) : HavePropertyMatchResult[P]

   Check to see if a property on the specified object, `objectWithProperty`, matches its expected value, and report the result in the returned `HavePropertyMatchResult`. The `objectWithProperty` is usually the value to the left of a `should` or `must` invocation. For example, `book`would be passed as the `objectWithProperty` in:

   Check to see if a property on the specified object, `objectWithProperty`, matches its expected value, and report the result in the returned `HavePropertyMatchResult`. The `objectWithProperty` is usually the value to the left of a `should` or `must` invocation. For example, `book`would be passed as the `objectWithProperty` in:

       book should have (title ("Moby Dick"))

   objectWithProperty

     the object with the property against which to match

   returns

     the `HavePropertyMatchResult` that represents the result of the match

   attributes: abstract
   definition classes: HavePropertyMatcher → 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 [U] (g: (U) ⇒ T) : HavePropertyMatcher[U, P]

    Compose this `HavePropertyMatcher` with the passed function, returning a new `HavePropertyMatcher`.

    Compose this `HavePropertyMatcher` with the passed function, returning a new `HavePropertyMatcher`.

    This method overrides `compose` on `Function1` to return a more specific function type of `HavePropertyMatcher`.

    definition classes: HavePropertyMatcher → 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[_]

    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

### Inherited from (T) ⇒ HavePropertyMatchResult[P]

### Inherited from AnyRef

### Inherited from Any