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)
}