Tagging your tests

ScalaTest allows you to define arbitrary test categories, to "tag" tests as belonging to those categories, and filter tests to run based on their tags. For example, you could tag some tests as being slow and chose to exclude the slow tests during some runs. ScalaTest supports one tag by default: ignore. You can tag a test as ignored to "switch it off" temporarily.

Tagging tests as ignored

To support the common use case of “temporarily” disabling a test, with the good intention of resurrecting the test at a later time, each style trait provides a way to tag tests as ignored. For example, in a AnyFlatSpec you can change an it or an in to ignore:

import org.scalatest.flatspec.AnyFlatSpec
import scala.collection.mutable.Stack

class StackSpec extends AnyFlatSpec {

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

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

If you run this version of StackSpec in the Scala interpreter with:

scala> (new StackSpec).execute()

It will run only the first test and report that the second test was ignored:

A Stack
- should pop values in last-in-first-out order
- should throw NoSuchElementException if an empty stack is popped !!! IGNORED !!!

Defining and using your own tags

Each style trait provides a way to tag tests. To tag tests in a AnyFlatSpec, for example, you pass objects that extend abstract class org.scalatest.Tag to taggedAs just before the in. Class Tag takes one parameter, a string name. Here's how you might define tags to mark tests that require a database:

import org.scalatest.Tag

object DbTest extends Tag("com.mycompany.tags.DbTest")

Given this definitions, you could tag AnyFlatSpec tests like this:

import org.scalatest.flatspec.AnyFlatSpec
import org.scalatest.tagobjects.Slow

class ExampleSpec extends AnyFlatSpec {

  "The Scala language" must "add correctly" taggedAs(Slow) in {
      val sum = 1 + 1
      assert(sum === 2)
    }

  it must "subtract correctly" taggedAs(Slow, DbTest) in {
    val diff = 4 - 1
    assert(diff === 3)
  }
}

This code marks both tests with the org.scalatest.tagobjects.Slow tag, and test "The Scala language should subtract correctly" with the com.mycompany.tags.DbTest tag.

When executing a suite, tests can optionally be included and/or excluded (i.e., filtered) based on their tags. Here's how:

• filter tests via the Runner
• filter tests via ScalaTest's ant task

Next, learn about running your tests.