0
# ScalaTest
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: org.scalatest:scalatest_2.12
7
- **Package Type**: Maven
8
- **Language**: Scala
9
- **Installation**: Add to build.sbt: `libraryDependencies += "org.scalatest" %% "scalatest" % "3.2.19" % "test"`
10

11
## Core Imports
12

13
```scala
14
import org.scalatest.funsuite.AnyFunSuite
15
import org.scalatest.matchers.should.Matchers
16
```
17

18
For asynchronous testing:
19

20
```scala
21
import org.scalatest.funsuite.AsyncFunSuite
22
import scala.concurrent.Future
23
```
24

25
For advanced matchers:
26

27
```scala
28
import org.scalatest.matchers.should.Matchers
29
import org.scalatest.matchers.must.Matchers.convertToMustWrapper
30
```
31

32
## Basic Usage
33

34
```scala
35
import org.scalatest.funsuite.AnyFunSuite
36
import org.scalatest.matchers.should.Matchers
37

38
class CalculatorSpec extends AnyFunSuite with Matchers {
39
  
40
  test("Calculator should add two numbers correctly") {
41
    val calculator = new Calculator()
42
    val result = calculator.add(2, 3)
43
    
44
    result should equal(5)
45
    result should be > 4
46
    result should be <= 5
47
  }
48
  
49
  test("Calculator should handle zero correctly") {
50
    val calculator = new Calculator()
51
    calculator.add(0, 5) should equal(5)
52
    calculator.add(-3, 3) should equal(0)  
53
  }
54
}
55
```
56

57
## Architecture
58

59
ScalaTest is built around several key architectural components:
60

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

68
## Capabilities
69

70
### Test Suite Styles
71

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

74
```scala { .api }
75
// Function-based testing (xUnit-style)
76
abstract class AnyFunSuite extends Suite
77

78
// Flat specification style
79
abstract class AnyFlatSpec extends Suite  
80

81
// Word-based specification style
82
abstract class AnyWordSpec extends Suite
83

84
// Free-form specification style  
85
abstract class AnyFreeSpec extends Suite
86

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

90
// Feature specification style (BDD/Gherkin-like)
91
abstract class AnyFeatureSpec extends Suite
92
```
93

94
[Test Suite Styles](./test-styles.md)
95

96
### Assertions and Matchers
97

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

100
```scala { .api }
101
trait Assertions {
102
  def assert(condition: Boolean): Assertion
103
  def assert(condition: Boolean, clue: Any): Assertion
104
  def assertResult[T](expected: T)(actual: T): Assertion
105
  def assertThrows[T <: AnyRef](f: => Any): T
106
  def fail(): Nothing
107
  def fail(message: String): Nothing
108
  def cancel(): Nothing
109
  def cancel(message: String): Nothing
110
  def pending: Assertion with PendingStatement
111
  def succeed: Assertion
112
}
113

114
trait Matchers {
115
  def equal[T](right: T): Matcher[T]
116
  def be[T](right: T): Matcher[T]  
117
  def contain[T](right: T): Matcher[GenTraversable[T]]
118
  def startWith(right: String): Matcher[String]
119
  def endWith(right: String): Matcher[String]
120
  def include(right: String): Matcher[String]
121
}
122
```
123

124
[Assertions](./assertions.md) | [Matchers](./matchers.md)
125

126
### Asynchronous Testing
127

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

130
```scala { .api }
131
trait ScalaFutures extends PatienceConfiguration {
132
  def whenReady[T](future: Future[T])(fun: T => Unit): Unit
133
  implicit def convertScalaFuture[T](future: Future[T]): FutureValue[T]
134
}
135

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

140
trait TimeLimits {
141
  def failAfter[T](timeout: Span)(f: => T): T
142
}
143
```
144

145
[Asynchronous Testing](./async.md)
146

147
### Fixtures and Lifecycle
148

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

151
```scala { .api }
152
trait BeforeAndAfter {
153
  protected def before(): Unit
154
  protected def after(): Unit  
155
}
156

157
trait BeforeAndAfterEach {
158
  protected def beforeEach(): Unit
159
  protected def afterEach(): Unit
160
}
161

162
trait BeforeAndAfterAll {
163
  protected def beforeAll(): Unit
164
  protected def afterAll(): Unit
165
}
166
```
167

168
[Fixtures](./fixtures.md)
169

170
### Advanced Testing Utilities
171

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

174
```scala { .api }
175
trait Inspectors {
176
  def forAll[E](xs: GenTraversable[E])(fun: E => Unit): Unit
177
  def forAtLeast[E](min: Int, xs: GenTraversable[E])(fun: E => Unit): Unit
178
  def forAtMost[E](max: Int, xs: GenTraversable[E])(fun: E => Unit): Unit
179
  def forBetween[E](from: Int, upTo: Int, xs: GenTraversable[E])(fun: E => Unit): Unit
180
}
181

182
trait PrivateMethodTester {
183
  def invokePrivate(target: AnyRef, methodName: Symbol, args: Any*): Any
184
}
185
```
186

187
[Advanced Utilities](./advanced.md)
188

189
## Types
190

191
```scala { .api }
192
// Core assertion result type
193
type Assertion = org.scalatest.compatible.Assertion
194

195
// Base trait for all test suites
196
trait Suite {
197
  def run(testName: Option[String], args: Args): Status
198
  def testNames: Set[String]
199
  def nestedSuites: IndexedSeq[Suite]
200
  def tags: Map[String, Set[String]]
201
}
202

203
// Test execution configuration
204
case class Args(
205
  reporter: Reporter,
206
  stopper: Stopper = Stopper.default,
207
  filter: Filter = Filter.default,
208
  configMap: ConfigMap = ConfigMap.empty,
209
  distributor: Option[Distributor] = None,
210
  tracker: Tracker = Tracker.default,
211
  chosenStyles: Set[String] = Set.empty,
212
  runTestInNewInstance: Boolean = false,
213
  distributedTestSorter: Option[DistributedTestSorter] = None,
214
  summaryCounter: Option[SummaryCounter] = None
215
)
216

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

220
// Matcher result containing success/failure information
221
case class MatchResult(
222
  matches: Boolean,
223
  failureMessage: String, 
224
  negatedFailureMessage: String,
225
  midSentenceFailureMessage: String = "",
226
  midSentenceNegatedFailureMessage: String = ""
227
)
228

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

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

235
// WordSpec DSL wrapper for string contexts
236
trait WordSpecStringWrapper {
237
  def when(description: String): WordSpecStringWrapper
238
  def should(description: String): WordSpecStringWrapper
239
  def must(description: String): WordSpecStringWrapper
240
  def can(description: String): WordSpecStringWrapper
241
  def which(description: String): WordSpecStringWrapper
242
  def in(testFun: => Any): Unit
243
}
244

245
// Configuration and execution types
246
type ConfigMap = Map[String, Any]
247
type Status = org.scalatest.Status
248
type Reporter = org.scalatest.Reporter
249
type Stopper = org.scalatest.Stopper
250
type Filter = org.scalatest.Filter
251
type Distributor = org.scalatest.Distributor  
252
type Tracker = org.scalatest.Tracker
253
type DistributedTestSorter = org.scalatest.DistributedTestSorter
254
type SummaryCounter = org.scalatest.SummaryCounter
255
```