Retryable

Tag annotation that indicates a test is a candidate for retrying on either failure, cancellation, or both.

Note: This is actually an annotation defined in Java, not a Scala trait. It must be defined in Java instead of Scala so it will be accessible at runtime. It has been inserted into Scaladoc by pretending it is a trait.

This tag annotation is intended to be used in conjunction with trait Retries, to identify tests that are candidates for retrying.

If you wish to mark all tests in a test class as being candidates for retries, you can annotate the test class with @Retryable, like this:

package org.scalatest.examples.flatspec.retryableall

import org.scalatest._
import tags.Retryable

@Retryable
class SetSpec extends FlatSpec with Retries {

  override def withFixture(test: NoArgTest) = {
    if (isRetryable(test))
      withRetry { super.withFixture(test) }
    else
      super.withFixture(test)
  }

  "An empty Set" should "have size 0" in {
    assert(Set.empty.size === 0)
  }

  it should "produce NoSuchElementException when head is invoked" in {
    intercept[NoSuchElementException] {
      Set.empty.head
    }
  }
}

When you mark a test class with a tag annotation, ScalaTest will mark each test defined in that class with that tag. Thus, marking the SetSpec in the above example with the @Retryable tag annotation means that both tests in the class are candidates for retrying.

Another use case for @Retryable is to mark test methods as being candidates for retries in traits Spec and fixture.Spec. Here's an example:

package org.scalatest.examples.spec.disk

import org.scalatest._
import tags.Disk

class SetSpec extends Spec with Retries {

  override def withFixture(test: NoArgTest) = {
    if (isRetryable(test))
      withRetry { super.withFixture(test) }
    else
      super.withFixture(test)
  }

  @Retryable def `an empty Set should have size 0` {
    assert(Set.empty.size === 0)
  }

  def `invoking head on an empty Set should produce NoSuchElementException` {
    intercept[NoSuchElementException] {
      Set.empty.head
    }
  }
}

The main use case of annotating a test or suite of tests is to select or deselect them during runs by supplying tags to include and/or exclude. For more information, see the relevant section in the documentation of object Runner.