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

Getting started with Spec

In a Spec, you combine tests with text that specifies the behavior being tested. You can describe the subject being specified and tested with describe clauses and place text that describes the behavior expected of the subject in it clauses. The code of the test appears in curly braces after the it and its text. The structure looks like this:

import org.scalatest.Spec

class ExampleSpec extends Spec {

  describe("A Stack") {

    it("should pop values in last-in-first-out order") (pending)

    it("should throw NoSuchElementException if an empty stack is popped") (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 Spec 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.Spec
import scala.collection.mutable.Stack

class ExampleSpec extends Spec {

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

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

import org.scalatest.Spec
import org.scalatest.matchers.MustMatchers
import scala.collection.mutable.Stack

class ExampleSpec extends Spec with MustMatchers {

  describe("A Stack") {

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

    it("should throw NoSuchElementException if an empty stack is popped") {
      val emptyStack = new Stack[String]
      evaluating { emptyStack.pop() } must 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.