org.scalatest.Documenter.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
import org.scalactic.source
/*
*
* A Documenter is essentially
* used to wrap a Reporter and provide easy ways to send markup text
* to that Reporter via a MarkupProvided event.
* Documenter contains an apply method that takes a string.
* The Documenter will forward the passed string to the Reporter as the text
* parameter of an MarkupProvided event.
*
*
*
* Here's an example of using an Documenter in a Suite
* subclass:
*
*
*
* import org.scalatest._
*
* class MySuite extends Suite {
* def testAddition(markup: Documenter) {
* assert(1 + 1 === 2)
* markup("Addition *seems* to work")
* }
* }
*
*
*
* As of 2.0, the only built-in reporter that presents markup text is the HTML reporter.
* If you run this Suite and specify the HTML reporter, you will see the message
* included in the HTML report:
*
*
*
* scala> (new MySuite).execute()
* - testAddition(Informer)
* + Addition seems to work
*
*
*
* Traits FunSuite, Spec, FlatSpec, WordSpec, FeatureSpec, and
* their sister traits in org.scalatest.fixture package declare an implicit markup method that returns
* an Documenter.
* Here's an example of a Spec that uses markup:
*
*
*
* import org.scalatest.refspec.RefSpec
* import scala.collection.mutable.Stack
*
* class StackSpec extends RefSpec {
*
* markup("""
*
* Stack Specification
* ===================
*
* A `Stack` is a data structure that allows you to store and retrieve objects in
* a last-in-first-out (LIFO) fashion. `Stack`s (both this class and its immutable
* cousin) are not commonly used in Scala, because a `List` gives you
* the same basic functionality. Pushing an object onto a `Stack` maps to consing
* a new element onto the front of a `List`. Peaking at the top of the `Stack` maps to
* to a `head`. Popping an object off of a `Stack` maps to a `head` followed by a `tail`.
* Nevertheless, using a `Stack` instead of a `List` can clarify your intent
* to readers of your code.
*
* """)
*
* describe("A Stack") {
*
* it("should pop values in last-in-first-out order") {
* val stack = new Stack[Int]
* stack.push(1)
* stack.push(2)
* assert(stack.pop() === 2)
* assert(stack.pop() === 1)
* }
*
* it("should throw NoSuchElementException if an empty stack is popped") {
* val emptyStack = new Stack[String]
* assertThrows[NoSuchElementException] {
* emptyStack.pop()
* }
* }
* }
* }
*
*
*
* Were you to run this FeatureSpec in the interpreter, you would see the following output:
*
*
*
* scala> (new ArithmeticFeatureSpec).run()
* Feature: Integer arithmetic
* Scenario: addition
* Given two integers
* When they are added
* Then the result is the sum of the two numbers
* Scenario: subtraction
* Given two integers
* When one is subtracted from the other
* Then the result is the difference of the two numbers
*
*
* @author Bill Venners
*/
/**
* Trait to which markup text tests can be reported.
*
*
* Note: Documenter will be described in more detail in a future 2.0 milestone release. As of this release
* you can't see its effects yet.
*
*
* @author Bill Venners
*/
trait Documenter {
/**
* Provide documentation to the Reporter.
*
* @param text an string of markup text that will be forwarded to the wrapped Reporter
* via a MarkupProvided event.
*
* @throws NullArgumentException if message reference is null
*/
def apply(text: String)(implicit pos: source.Position): Unit
}