Home | Download | Quick Start | ScalaDoc | Community | About

Getting started with FlatSpec

In a FlatSpec, you combine tests with text that specifies the behavior being tested. You describe the subject being specified and tested with a string followed by a verb—either should, must, or can&mdash. After the verb you place a string that completes the rest of a sentence that describes some behavior required of the subject. Following this second string, you place an in and the code of the test in curly braces. If the test is pending, you can use is instead of in. If you have more behavior to describe for the same subject, you can use it instead of repeating the subject string. The structure looks like this:

import org.scalatest.FlatSpec

class ExampleSpec extends FlatSpec {

  "A Stack" should "pop values in last-in-first-out order" is (pending)

  it should "throw NoSuchElementException if an empty stack is popped" is (pending)
}

Here the subject being specified and tested is "A Stack". The tests are marked pending in the previous example to indicate the tests have not yet been implemented. You can compile this FlatSpec like this:

$ scalac -cp scalatest-1.0.jar ExampleSpec.scala

Here's how you run it:

$ scala -cp scalatest-1.0.jar org.scalatest.tools.Runner -p . -o -s ExampleSpec
Run starting. Expected test count is: 2
ExampleSpec:
A Stack 
- should pop values in last-in-first-out order (pending)
- should throw NoSuchElementException if an empty stack is popped (pending)
Run completed in 61 milliseconds.
Total number of tests run: 0
Suites: completed 1, aborted 0
Tests: succeeded 0, failed 0, ignored 0, pending 2
All tests passed.

Notice that the specification text appears in a readable form in the output. You could fill in the tests like this:

import org.scalatest.FlatSpec
import scala.collection.mutable.Stack

class ExampleSpec extends FlatSpec {

  "A Stack" should "pop values in last-in-first-out order" in {
    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" in {
    val emptyStack = new Stack[String]
    intercept[NoSuchElementException] {
      emptyStack.pop()
    }
  }
}

Or, if you prefer ScalaTest's matcher syntax, you can mix in ShouldMatchers or MustMatchers, like this:

import org.scalatest.FlatSpec
import org.scalatest.matchers.ShouldMatchers
import scala.collection.mutable.Stack

class ExampleSpec extends FlatSpec with ShouldMatchers {

  "A Stack" should "pop values in last-in-first-out order" in {
    val stack = new Stack[Int]
    stack.push(1)
    stack.push(2)
    stack.pop() should be === 2
    stack.pop() should be === 1
  }

  it should "throw NoSuchElementException if an empty stack is popped" in {
    val emptyStack = new Stack[String]
    evaluating { emptyStack.pop() } should produce [NoSuchElementException]
  }
}

Now when you run ExampleSpec you'll see the tests are no longer reported as pending:

$ scala -cp scalatest-1.0.jar org.scalatest.tools.Runner -p . -o -s ExampleSpec
Run starting. Expected test count is: 2
ExampleSpec:
A Stack 
- should pop values in last-in-first-out order
- should throw NoSuchElementException if an empty stack is popped
Run completed in 76 milliseconds.
Total number of tests run: 2
Suites: completed 1, aborted 0
Tests: succeeded 2, failed 0, ignored 0, pending 0
All tests passed.