org.scalatest.events.Formatter.scala Maven / Gradle / Ivy

/*
 * Copyright 2001-2013 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.events


/**
 * Abstract class for the optional formatter objects that must be passed to the Events reported
 * during a ScalaTest run.
 */
sealed abstract class Formatter extends Product with Serializable

/**
 * A Formatter that indicates reporters may wish to suppress reporting of an Event.
 * "Suppress" means that the event won't be reported to the user.
 *
 * 
 * An example is that specification-style suites, such as FunSpec, generate output that reads
 * more like a specification. One aspect of this is that generally only a single event should be reported
 * for each test, so that output can appear like this:
 * 
 *
 *  * A Stack (when newly created)
 * - should be empty
 * - should complain when popped
 * 
 *
 * 
 * ScalaTest suites should generate two events per test, a TestStarting event and either
 * a TestSucceeded or a TestFailed event. The FunSpec trait does report both events,
 * but passes a MotionToSuppress along with the TestStarting event. As a result,
 * The TestStarting events have no effect on the output. Each TestSucceeded or
 * TestFailed event, which is sent with an IndentedText formatter instead of
 * a MotionToSuppress, will generate output, such as "- should be empty".
 * 
 *
 * 
 * Reporters may choose to ignore a MotionToSuppress. For example, an XML reporter may
 * want to report everything about every event that is fired during a concurrent run, so that the
 * events can be reordered later by reading the complete, but unordered, information from an XML file.
 * In this case, the XML reporter would actually report events that were fired with a MotionToSuppress,
 * including indicating that the report included a motion to suppress.
 * 
 *
 * @author Bill Venners
 */
final case object MotionToSuppress extends Formatter

/**
 * A Formatter providing information that enables reporters to create more stylized output.
 *
 * 
 * An example is that specification-style suites, such as FunSpec, generate output that reads
 * more like a specification, for instance:
 * 
 *
 *  * A Stack (when newly created)
 * - should be empty
 * - should complain when popped
 * 
 *
 * 
 * This output might be generated by ScalaTest's standard out reporter. Each of these lines would be
 * taken from the IndentedText's formattedText parameter. Were this same run
 * to be reported in HTML or in a GUI, the output would be based on the rawText and the
 * indentationLevel. Here's what the IndentedText values would be for each event:
 * 
 *
 * 
 * InfoProvided reported with an:
 *  *   IndentedText(
 *     formattedText = "A Stack (when newly created)",
 *     rawText = "A Stack (when newly created)",
 *     indentationLevel = 0
 *   )
 * 
 * 
 * TestSucceeded reported with an:
 *  *   IndentedText(
 *     formattedText = "- should be empty",
 *     rawText = "should be empty",
 *     indentationLevel = 1
 *   )
 * 
 * 
 * TestSucceeded reported with an:
 *  *   IndentedText(
 *     formattedText = "- should complain when popped",
 *     rawText = "should complain when popped",
 *     indentationLevel = 1
 *   )
 * 
 * 
 * 
 *
 * 
 * One possible way this information could be presented in HTML, for example, is this:
 * 
 *
 * 
 * A Stack (when newly created)
 * 

 * should be empty
 * should complain when popped
 * 
 * 
 *
 * @param formattedText a localized string suitable for presenting to a user by printing it straight to an output stream
 * @param rawText a localized string suitable for presenting to the user after in some way being indented by the
 *        value specified as the indentationLevel parameter
 * @param indentationLevel a zero or positive integer representing an indentation level for the indented text
 *
 * @throws IllegalArgumentException if the specified indentationLevel is less than zero
 */
final case class IndentedText(formattedText: String, rawText: String, indentationLevel: Int) extends Formatter {
  require(indentationLevel >= 0, "indentationLevel was less than zero: " + indentationLevel)
}