or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced.mdassertions.mdasync.mdfixtures.mdindex.mdmatchers.mdtest-styles.md
tile.json

index.mddocs/

ScalaTest

ScalaTest is a comprehensive testing framework for Scala and Java applications that provides multiple testing styles including FunSuite, FlatSpec, WordSpec, FreeSpec, and FeatureSpec to accommodate different testing preferences and domain-specific languages. The framework offers powerful assertion libraries with custom matchers, property-based testing capabilities, fixture management, and parallel test execution support.

Package Information

  • Package Name: org.scalatest:scalatest_2.12
  • Package Type: Maven
  • Language: Scala
  • Installation: Add to build.sbt: libraryDependencies += "org.scalatest" %% "scalatest" % "3.2.19" % "test"

Core Imports

import org.scalatest.funsuite.AnyFunSuite
import org.scalatest.matchers.should.Matchers

For asynchronous testing:

import org.scalatest.funsuite.AsyncFunSuite
import scala.concurrent.Future

For advanced matchers:

import org.scalatest.matchers.should.Matchers
import org.scalatest.matchers.must.Matchers.convertToMustWrapper

Basic Usage

import org.scalatest.funsuite.AnyFunSuite
import org.scalatest.matchers.should.Matchers

class CalculatorSpec extends AnyFunSuite with Matchers {
  
  test("Calculator should add two numbers correctly") {
    val calculator = new Calculator()
    val result = calculator.add(2, 3)
    
    result should equal(5)
    result should be > 4
    result should be <= 5
  }
  
  test("Calculator should handle zero correctly") {
    val calculator = new Calculator()
    calculator.add(0, 5) should equal(5)
    calculator.add(-3, 3) should equal(0)  
  }
}

Architecture

ScalaTest is built around several key architectural components:

  • Suite Hierarchy: Base Suite trait that all test classes extend, providing common test execution infrastructure
  • Testing Styles: Multiple DSL styles (FunSuite, FlatSpec, WordSpec, etc.) to match different testing preferences and domain languages
  • Assertions Framework: Core assertion methods with enhanced error reporting and stack trace management
  • Matcher System: Extensive DSL for expressive test assertions with "should" and "must" syntaxes
  • Execution Engine: Parallel test execution, filtering, and lifecycle management with configurable reporters
  • Fixture Management: Multiple patterns for test setup/teardown including per-test and per-suite fixtures

Capabilities

Test Suite Styles

Core testing styles that provide different DSLs for writing tests, each optimized for different testing approaches and domain languages.

// Function-based testing (xUnit-style)
abstract class AnyFunSuite extends Suite

// Flat specification style
abstract class AnyFlatSpec extends Suite  

// Word-based specification style
abstract class AnyWordSpec extends Suite

// Free-form specification style  
abstract class AnyFreeSpec extends Suite

// Function specification style (RSpec-like)
abstract class AnyFunSpec extends Suite

// Feature specification style (BDD/Gherkin-like)
abstract class AnyFeatureSpec extends Suite

Test Suite Styles

Assertions and Matchers

Powerful assertion framework with expressive matcher DSL for readable and maintainable test assertions.

trait Assertions {
  def assert(condition: Boolean): Assertion
  def assert(condition: Boolean, clue: Any): Assertion
  def assertResult[T](expected: T)(actual: T): Assertion
  def assertThrows[T <: AnyRef](f: => Any): T
  def fail(): Nothing
  def fail(message: String): Nothing
  def cancel(): Nothing
  def cancel(message: String): Nothing
  def pending: Assertion with PendingStatement
  def succeed: Assertion
}

trait Matchers {
  def equal[T](right: T): Matcher[T]
  def be[T](right: T): Matcher[T]  
  def contain[T](right: T): Matcher[GenTraversable[T]]
  def startWith(right: String): Matcher[String]
  def endWith(right: String): Matcher[String]
  def include(right: String): Matcher[String]
}

Assertions | Matchers

Asynchronous Testing

Comprehensive support for testing asynchronous code including Futures, eventual consistency patterns, and time-based assertions.

trait ScalaFutures extends PatienceConfiguration {
  def whenReady[T](future: Future[T])(fun: T => Unit): Unit
  implicit def convertScalaFuture[T](future: Future[T]): FutureValue[T]
}

trait Eventually extends PatienceConfiguration {
  def eventually[T](f: => T): T
}

trait TimeLimits {
  def failAfter[T](timeout: Span)(f: => T): T
}

Asynchronous Testing

Fixtures and Lifecycle

Multiple patterns for managing test setup, teardown, and shared resources across test executions.

trait BeforeAndAfter {
  protected def before(): Unit
  protected def after(): Unit  
}

trait BeforeAndAfterEach {
  protected def beforeEach(): Unit
  protected def afterEach(): Unit
}

trait BeforeAndAfterAll {
  protected def beforeAll(): Unit
  protected def afterAll(): Unit
}

Fixtures

Advanced Testing Utilities

Specialized utilities for complex testing scenarios including bulk assertions, private method testing, and XML testing.

trait Inspectors {
  def forAll[E](xs: GenTraversable[E])(fun: E => Unit): Unit
  def forAtLeast[E](min: Int, xs: GenTraversable[E])(fun: E => Unit): Unit
  def forAtMost[E](max: Int, xs: GenTraversable[E])(fun: E => Unit): Unit
  def forBetween[E](from: Int, upTo: Int, xs: GenTraversable[E])(fun: E => Unit): Unit
}

trait PrivateMethodTester {
  def invokePrivate(target: AnyRef, methodName: Symbol, args: Any*): Any
}

Advanced Utilities

Types

// Core assertion result type
type Assertion = org.scalatest.compatible.Assertion

// Base trait for all test suites
trait Suite {
  def run(testName: Option[String], args: Args): Status
  def testNames: Set[String]
  def nestedSuites: IndexedSeq[Suite]
  def tags: Map[String, Set[String]]
}

// Test execution configuration
case class Args(
  reporter: Reporter,
  stopper: Stopper = Stopper.default,
  filter: Filter = Filter.default,
  configMap: ConfigMap = ConfigMap.empty,
  distributor: Option[Distributor] = None,
  tracker: Tracker = Tracker.default,
  chosenStyles: Set[String] = Set.empty,
  runTestInNewInstance: Boolean = false,
  distributedTestSorter: Option[DistributedTestSorter] = None,
  summaryCounter: Option[SummaryCounter] = None
)

// Time span representation for timeouts and patience
case class Span(length: Long, unit: TimeUnit)

// Matcher result containing success/failure information
case class MatchResult(
  matches: Boolean,
  failureMessage: String, 
  negatedFailureMessage: String,
  midSentenceFailureMessage: String = "",
  midSentenceNegatedFailureMessage: String = ""
)

// Time unit enumeration for time spans
type TimeUnit = java.util.concurrent.TimeUnit

// Collection types used in matchers and inspectors  
type GenTraversable[T] = scala.collection.GenTraversable[T]

// WordSpec DSL wrapper for string contexts
trait WordSpecStringWrapper {
  def when(description: String): WordSpecStringWrapper
  def should(description: String): WordSpecStringWrapper
  def must(description: String): WordSpecStringWrapper
  def can(description: String): WordSpecStringWrapper
  def which(description: String): WordSpecStringWrapper
  def in(testFun: => Any): Unit
}

// Configuration and execution types
type ConfigMap = Map[String, Any]
type Status = org.scalatest.Status
type Reporter = org.scalatest.Reporter
type Stopper = org.scalatest.Stopper
type Filter = org.scalatest.Filter
type Distributor = org.scalatest.Distributor  
type Tracker = org.scalatest.Tracker
type DistributedTestSorter = org.scalatest.DistributedTestSorter
type SummaryCounter = org.scalatest.SummaryCounter