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

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

 tempFile should be a ('file) // dynamic: uses reflection
 tempFile should be a (file)  // type safe: only works on Files; 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 BePropertyMatchers:

 trait CustomMatchers {
 
   class FileBePropertyMatcher extends BePropertyMatcher[java.io.File] {
     def apply(left: java.io.File) = BePropertyMatchResult(left.isFile, "file")
   }
 
   class DirectoryBePropertyMatcher extends BePropertyMatcher[java.io.File] {
     def apply(left: java.io.File) = BePropertyMatchResult(left.isDirectory, "directory")
   }
 
   val file = new FileBePropertyMatcher
   val directory = new DirectoryBePropertyMatcher
 }
 

Because the type parameter of these two BePropertyMatchers is java.io.File, they can only be used with instances of that type. (The compiler will enforce this.) All they do is create a BePropertyMatchResult whose matches field is true if and only if the Boolean property is true. The second field, propertyName, is simply the string name of the property. The file and directory vals create variables that can be used in matcher expressions that test whether a java.io.File is a file or a directory. Here's an example:

 class ExampleSpec extends Spec with ShouldMatchers with CustomMatchers {
 
   describe("A temp file") {
 
     it("should be a file, not a directory") {
 
       val tempFile = java.io.File.createTempFile("delete", "me")
 
       try {
         tempFile should be a (file)
         tempFile should not be a (directory)
       }
       finally {
         tempFile.delete()
       }
     }
   }
 }
 

These matches should succeed, but if for example the first match, tempFile should be a (file), were to fail, you would get an error message like:

 /tmp/delme1234me was not a file
 

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