• Home
• org.scalatest
• scalatest_2.9.0
• 2.0.M6-SNAP3
• source code
• MatchResult.scala

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

org.scalatest.matchers.MatchResult.scala Maven / Gradle / Ivy

/*
 * Copyright 2001-2008 Artima, Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.scalatest.matchers
 
import org.scalatest._

/**
 * The result of a match operation, such as one performed by a Matcher or
 * BeMatcher, which 
 * contains one field that indicates whether the match succeeded and four fields that provide
 * failure messages to report under different circumstances.
 * 
 * 

 * A MatchResult's matches field indicates whether a match succeeded. If it succeeded,
 * matches will be true.
 * The other four fields contain failure message strings, one of which will be presented to the user in case of a match failure. If a match succeeds,
 * none of these strings will be used, because no failure message will be reported (i.e., because there was no failure
 * to report). If a match fails (matches is false), the failureMessage (or
 * midSentenceFailure—more on that below) will be reported to help the user understand what went wrong.
 * 
 *
 * 
Understanding negatedFailureMessage
 *
 * 

 * The negatedFailureMessage exists so that it can become the failureMessage if the matcher is inverted,
 * which happens, for instance, if it is passed to not. Here's an example:
 * 
 *
 * 
 * val equalSeven = equal (7)
 * val notEqualSeven = not (equalSeven)
 * 
 *
 * 

 * The Matcher[Int] that results from passing 7 to equal, which is assigned to the equalSeven
 * variable, will compare Ints passed to its
 * apply method with 7. If 7 is passed, the equalSeven match will succeed. If anything other than 7 is passed, it
 * will fail. By contrast, the notEqualSeven matcher, which results from passing equalSeven to not, does
 * just the opposite. If 7 is passed, the notEqualSeven match will fail. If anything other than 7 is passed, it will succeed.
 * 
 *
 * 

 * For example, if 8 is passed, equalSeven's MatchResult will contain:
 * 
 *
 * 
 *            expression: equalSeven(8)
 *               matches: false
 *        failureMessage: 8 did not equal 7
 * negatedFailureMessage: 8 equaled 7
 * 
 *
 * 

 * Although the negatedFailureMessage is nonsensical, it will not be reported to the user. Only the failureMessage,
 * which does actually explain what caused the failure, will be reported by the user. If you pass 8 to notEqualSeven's apply
 * method, by contrast, the failureMessage and negatedFailureMessage will be:
 * 
 *
 * 
 *            expression: notEqualSeven(8)
 *               matches: true
 *        failureMessage: 8 equaled 7
 * negatedFailureMessage: 8 did not equal 7
 * 
 *
 * 

 * Note that the messages are swapped from the equalSeven messages. This swapping was effectively performed by the not matcher,
 * which in addition to swapping the failureMessage and negatedFailureMessage, also inverted the
 * matches value. Thus when you pass the same value to both equalSeven and notEqualSeven the matches
 * field of one MatchResult will be true and the other false. Because the
 * matches field of the MatchResult returned by notEqualSeven(8) is true,
 * the nonsensical failureMessage, "8 equaled 7", will not be reported to the user.
 * 
 *
 * 

 * If 7 is passed, by contrast, the failureMessage and negatedFailureMessage of equalSeven
 * will be:
 * 
 *
 * 
 *            expression: equalSeven(7)
 *               matches: true
 *        failureMessage: 7 did not equal 7
 * negatedFailureMessage: 7 equaled 7
 * 
 *
 * 

 * In this case equalSeven's failureMessage is nonsensical, but because the match succeeded, the nonsensical message will
 * not be reported to the user.
 * If you pass 7 to notEqualSeven's apply
 * method, you'll get:
 * 
 *
 * 
 *            expression: notEqualSeven(7)
 *               matches: false
 *        failureMessage: 7 equaled 7
 * negatedFailureMessage: 7 did not equal 7
 * 
 *
 * 

 * Again the messages are swapped from the equalSeven messages, but this time, the failureMessage makes sense
 * and explains what went wrong: the notEqualSeven match failed because the number passed did in fact equal 7. Since
 * the match failed, this failure message, "7 equaled 7", will be reported to the user.
 * 
 *
 * 
Understanding the "midSentence" messages
 *
 * 

 * When a ScalaTest matcher expression that involves and or or fails, the failure message that
 * results is composed from the failure messages of the left and right matcher operatnds to and or or.
 * For example:
 * 
 *
 * 
 * 8 should (equal (7) or equal (9))
 * 
 *
 * 

 * This above expression would fail with the following failure message reported to the user:
 * 
 *
 * 
 * 8 did not equal 7, and 8 did not equal 9
 * 
 *
 * 

 * This works fine, but what if the failure messages being combined begin with a capital letter, such as:
 * 
 *
 * 
 * The name property did not equal "Ricky"
 * 
 *
 * 

 * A combination of two such failure messages might result in an abomination of English punctuation, such as:
 * 
 *
 * 
 * The name property did not equal "Ricky", and The name property did not equal "Bobby"
 * 
 *
 * 

 * Because ScalaTest is an internationalized application, taking all of its strings from a property file
 * enabling it to be localized, it isn't a good idea to force the first character to lower case. Besides,
 * it might actually represent a String value which should stay upper case. The midSentenceFailureMessage
 * exists for this situation. If the failure message is used at the beginning of the sentence, failureMessage
 * will be used. But if it appears mid-sentence, or at the end of the sentence, midSentenceFailureMessage
 * will be used. Given these failure message strings:
 * 
 *
 * 
 *            failureMessage: The name property did not equal "Bobby"
 * midSentenceFailureMessage: the name property did not equal "Bobby"
 * 
 *
 * 

 * The resulting failure of the or expression involving to matchers would make any English teacher proud:
 * 
 *
 * 
 * The name property did not equal "Ricky", and the name property did not equal "Bobby"
 * 
 *
 * @param matches indicates whether or not the matcher matched
 * @param failureMessage a failure message to report if a match fails
 * @param negatedFailureMessage a message with a meaning opposite to that of the failure message
 * @param midSentenceFailureMessage a failure message suitable for appearing mid-sentence
 * @param midSentenceNegatedFailureMessage a negated failure message suitable for appearing mid-sentence
 *
 * @author Bill Venners
 */
final case class MatchResult(
  matches: Boolean,
  failureMessage: String,
  negatedFailureMessage: String,
  midSentenceFailureMessage: String,
  midSentenceNegatedFailureMessage: String
) {

  /**
   * Constructs a new MatchResult with passed matches, failureMessage, and
   * negativeFailureMessage fields. The midSentenceFailureMessage will return the same
   * string as failureMessage, and the midSentenceNegatedFailureMessage will return the
   * same string as negatedFailureMessage.
   *
   * @param matches indicates whether or not the matcher matched
   * @param failureMessage a failure message to report if a match fails
   * @param negatedFailureMessage a message with a meaning opposite to that of the failure message
   */
  def this(matches: Boolean, failureMessage: String, negatedFailureMessage: String) =
    this(
      matches,
      failureMessage,
      negatedFailureMessage,
      failureMessage,
      negatedFailureMessage
    )
}

/**
 * Companion object for the MatchResult case class.
 *
 * @author Bill Venners
 */
object MatchResult {

/* Can't seem to redefine this to get the Scaladoc.
  /**
   * Factory method that constructs a new MatchResult with passed matches, failureMessage, 
   * negativeFailureMessage, midSentenceFailureMessage, and
   * midSentenceNegatedFailureMessage fields.
   *
   * @param matches indicates whether or not the matcher matched
   * @param failureMessage a failure message to report if a match fails
   * @param negatedFailureMessage a message with a meaning opposite to that of the failure message
   * @param midSentenceFailureMessage a failure message to report if a match fails
   * @param midSentenceNegatedFailureMessage a message with a meaning opposite to that of the failure message
   */
  def apply(matches: Boolean, failureMessage: String, negatedFailureMessage: String, midSentenceFailureMessage: String,
      midSentenceNegatedFailureMessage: String): MatchResult =
    new MatchResult(matches, failureMessage, negatedFailureMessage, midSentenceFailureMessage, midSentenceNegatedFailureMessage)
*/

  /**
   * Factory method that constructs a new MatchResult with passed matches, failureMessage, and
   * negativeFailureMessage fields. The midSentenceFailureMessage will return the same
   * string as failureMessage, and the midSentenceNegatedFailureMessage will return the
   * same string as negatedFailureMessage.
   *
   * @param matches indicates whether or not the matcher matched
   * @param failureMessage a failure message to report if a match fails
   * @param negatedFailureMessage a message with a meaning opposite to that of the failure message
   */
  def apply(matches: Boolean, failureMessage: String, negatedFailureMessage: String): MatchResult =
    new MatchResult(matches, failureMessage, negatedFailureMessage, failureMessage, negatedFailureMessage)
}