0
# ScalaTest
1
2
ScalaTest is a comprehensive testing framework for Scala and Java programmers, providing multiple testing styles, powerful matcher capabilities, and extensive support for asynchronous testing. It includes Scalactic, a library for constraints, equality, and functional error handling.
3
4
## Package Information
5
6
- **Package Name**: org.scalatest:scalatest_2.13
7
- **Package Type**: maven
8
- **Language**: Scala
9
- **Installation**: `libraryDependencies += "org.scalatest" %% "scalatest" % "3.2.19" % "test"`
10
11
## Core Imports
12
13
```scala
14
import org.scalatest._
15
import org.scalatest.matchers._
16
import org.scalactic._
17
```
18
19
For specific test styles:
20
21
```scala
22
import org.scalatest.funsuite.AnyFunSuite
23
import org.scalatest.flatspec.AnyFlatSpec
24
import org.scalatest.funspec.AnyFunSpec
25
import org.scalatest.wordspec.AnyWordSpec
26
import org.scalatest.freespec.AnyFreeSpec
27
import org.scalatest.propspec.AnyPropSpec
28
import org.scalatest.featurespec.AnyFeatureSpec
29
```
30
31
## Basic Usage
32
33
```scala
34
import org.scalatest.funsuite.AnyFunSuite
35
import org.scalatest.matchers.should.Matchers
36
37
class BasicTestSuite extends AnyFunSuite with Matchers {
38
test("basic math operations") {
39
val result = 2 + 2
40
result should equal (4)
41
result should be > 3
42
result should be < 5
43
}
44
45
test("string operations") {
46
val message = "Hello, World!"
47
message should include ("World")
48
message should startWith ("Hello")
49
message should have length 13
50
}
51
}
52
```
53
54
## Architecture
55
56
ScalaTest is built around several key components:
57
58
- **Test Styles**: Multiple testing styles (FunSuite, FlatSpec, FunSpec, WordSpec, etc.) to match different preferences
59
- **Trait Stacking**: Modular design allowing mixing of traits for different behaviors
60
- **Matcher System**: Powerful matchers for assertions with readable error messages
61
- **Scalactic Integration**: Built-in support for constraints, equality, and error handling
62
- **Async Support**: First-class support for asynchronous testing with Futures
63
- **Property-Based Testing**: Built-in generators and property checking capabilities
64
65
## Capabilities
66
67
### Test Styles
68
69
Different approaches to writing tests, each with their own syntax and organization patterns.
70
71
```scala { .api }
72
trait Suite {
73
def run(testName: Option[String], args: Args): Status
74
def testNames: Set[String]
75
def tags: Map[String, Set[String]]
76
}
77
78
abstract class AnyFunSuite extends Suite with TestSuite with Assertions
79
abstract class AnyFlatSpec extends Suite with TestSuite with Assertions
80
abstract class AnyFunSpec extends Suite with TestSuite with Assertions
81
abstract class AnyWordSpec extends Suite with TestSuite with Assertions
82
abstract class AnyFreeSpec extends Suite with TestSuite with Assertions
83
abstract class AnyPropSpec extends Suite with TestSuite with Assertions
84
abstract class AnyFeatureSpec extends Suite with TestSuite with Assertions
85
```
86
87
[Test Styles](./test-styles.md)
88
89
### Matchers and Assertions
90
91
Powerful assertion and matcher system for readable test code and informative failure messages.
92
93
```scala { .api }
94
trait Assertions {
95
def assert(condition: Boolean): Assertion
96
def assert(condition: Boolean, clue: Any): Assertion
97
def fail(): Nothing
98
def fail(message: String): Nothing
99
def pending: Assertion with PendingStatement
100
}
101
102
trait Matchers extends Assertions {
103
def equal(right: Any): Matcher[Any]
104
def be(right: Any): Matcher[Any]
105
def contain(element: Any): Matcher[Any]
106
def have(resultOfLengthWordApplication: ResultOfLengthWordApplication): Matcher[Any]
107
}
108
```
109
110
[Matchers and Assertions](./matchers.md)
111
112
### Scalactic Support
113
114
Functional programming utilities for equality, constraints, and error handling.
115
116
```scala { .api }
117
sealed abstract class Or[+G, +B] extends Product with Serializable
118
final case class Good[+G](get: G) extends Or[G, Nothing]
119
final case class Bad[+B](get: B) extends Or[Nothing, B]
120
121
def attempt[R](f: => R): R Or Throwable
122
123
trait Equality[A] {
124
def areEqual(a: A, b: Any): Boolean
125
}
126
127
trait Equivalence[T] {
128
def equiv(a: T, b: T): Boolean
129
}
130
```
131
132
[Scalactic](./scalactic.md)
133
134
### Asynchronous Testing
135
136
Support for testing asynchronous code with Futures and custom execution contexts.
137
138
```scala { .api }
139
trait AsyncTestSuite extends Suite {
140
type FixtureParam = Unit
141
def withFixture(test: OneArgAsyncTest): FutureOutcome
142
}
143
144
class FutureOutcome(underlying: Future[Outcome]) {
145
def map(f: Outcome => Outcome): FutureOutcome
146
def flatMap(f: Outcome => FutureOutcome): FutureOutcome
147
def transform(f: Try[Outcome] => Try[Outcome]): FutureOutcome
148
}
149
```
150
151
[Asynchronous Testing](./async.md)
152
153
### Property-Based Testing
154
155
Built-in support for property-based testing with generators and test data.
156
157
```scala { .api }
158
trait PropertyChecks {
159
def forAll[A](gen: Generator[A])(fun: A => Assertion): Assertion
160
def forAll[A](table: TableFor1[A])(fun: A => Assertion): Assertion
161
}
162
163
trait Generator[T] {
164
def next(szp: SizeParam, edges: List[T], rnd: Randomizer): (RoseTree[T], Randomizer)
165
def map[U](f: T => U): Generator[U]
166
def flatMap[U](f: T => Generator[U]): Generator[U]
167
}
168
```
169
170
[Property-Based Testing](./property.md)
171
172
### Fixtures and Lifecycle
173
174
Support for test fixtures and suite lifecycle management.
175
176
```scala { .api }
177
trait BeforeAndAfterEach extends SuiteMixin {
178
def beforeEach(): Unit
179
def afterEach(): Unit
180
}
181
182
trait BeforeAndAfterAll extends SuiteMixin {
183
def beforeAll(): Unit
184
def afterAll(): Unit
185
}
186
187
trait FixtureTestSuite extends TestSuite {
188
type FixtureParam
189
def withFixture(test: OneArgTest): Outcome
190
}
191
```
192
193
[Fixtures and Lifecycle](./fixtures.md)
194
195
### Test Execution and Events
196
197
Core test execution infrastructure and event reporting system.
198
199
```scala { .api }
200
trait Reporter {
201
def apply(event: Event): Unit
202
}
203
204
sealed abstract class Event extends Serializable with Ordered[Event]
205
case class TestStarting(ordinal: Ordinal, suiteName: String, testName: String) extends Event
206
case class TestSucceeded(ordinal: Ordinal, suiteName: String, testName: String) extends Event
207
case class TestFailed(ordinal: Ordinal, suiteName: String, testName: String, throwable: Option[Throwable]) extends Event
208
209
trait Stopper {
210
def apply(): Boolean
211
}
212
213
trait Distributor {
214
def apply(suite: Suite, args: Args): Status
215
}
216
```
217
218
### Suite Discovery and Tools
219
220
Test discovery and execution tools for integration with build systems.
221
222
```scala { .api }
223
object Suite {
224
def getSimpleNameOfAnObjectsClass(o: AnyRef): String
225
def checkForPublicNoArgConstructor(clazz: java.lang.Class[_]): Unit
226
}
227
228
trait Finders extends Annotation {
229
def value(): String
230
}
231
```
232
233
## Types
234
235
```scala { .api }
236
type Assertion = compatible.Assertion
237
238
sealed abstract class Outcome extends Product with Serializable
239
case object Succeeded extends Outcome
240
final case class Failed(exception: Throwable) extends Outcome
241
final case class Canceled(exception: Throwable) extends Outcome
242
case object Pending extends Outcome
243
244
trait Status {
245
def succeeds(): Boolean
246
def isCompleted(): Boolean
247
def waitUntilCompleted(): Unit
248
}
249
250
case class Args(
251
reporter: Reporter,
252
stopper: Stopper = Stopper.default,
253
filter: Filter = Filter(),
254
configMap: ConfigMap = ConfigMap.empty,
255
distributor: Option[Distributor] = None,
256
tracker: Tracker = Tracker.default,
257
chosenStyles: Set[String] = Set.empty,
258
runTestInNewInstance: Boolean = false,
259
distributedTestSorter: Option[DistributedTestSorter] = None,
260
distributedSuiteSorter: Option[DistributedSuiteSorter] = None
261
)
262
```