Documenter

Trait to which markup text tests can be reported.

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.Spec
import scala.collection.mutable.Stack
class StackSpec extends Spec {
  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]
      intercept[NoSuchElementException] {
        emptyStack.pop()
      }
    }
  }
}

Were you to run this FeatureSpec in the interpreter, you would see the following messages included in the printed report:

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