0
# ScalaTest
1

2
ScalaTest is a comprehensive testing framework for Scala that provides multiple testing styles, powerful assertion capabilities, and extensive matcher libraries. It offers eight different testing styles to accommodate different preferences and requirements, from function-based tests to full BDD specifications. ScalaTest also includes Scalactic, a library for functional programming idioms and better error messages.
3

4
## Package Information
5

6
- **Package Name**: org.scalatest:scalatest_2.11
7
- **Package Type**: Maven (SBT)
8
- **Language**: Scala (cross-compiled for 2.10, 2.11, 2.12, 2.13)
9
- **Version**: 3.2.19
10
- **Platforms**: JVM, JavaScript (Scala.js), Native (Scala Native)
11
- **Installation (SBT)**: `libraryDependencies += "org.scalatest" %% "scalatest" % "3.2.19" % Test`
12
- **Installation (Maven)**: 
13
  ```xml
14
  <dependency>
15
    <groupId>org.scalatest</groupId>
16
    <artifactId>scalatest_2.11</artifactId>
17
    <version>3.2.19</version>
18
    <scope>test</scope>
19
  </dependency>
20
  ```
21

22
## Core Imports
23

24
```scala { .api }
25
import org.scalatest._
26
import org.scalatest.matchers.should.Matchers
27
import org.scalactic._
28
```
29

30
For specific test styles:
31
```scala { .api }
32
import org.scalatest.funsuite.AnyFunSuite
33
import org.scalatest.flatspec.AnyFlatSpec
34
import org.scalatest.wordspec.AnyWordSpec
35
import org.scalatest.freespec.AnyFreeSpec
36
import org.scalatest.featurespec.AnyFeatureSpec
37
import org.scalatest.funspec.AnyFunSpec
38
import org.scalatest.propspec.AnyPropSpec
39
import org.scalatest.refspec.RefSpec
40
```
41

42
## Basic Usage
43

44
### Simple Function-Based Test (FunSuite)
45
```scala
46
import org.scalatest.funsuite.AnyFunSuite
47

48
class CalculatorSuite extends AnyFunSuite {
49
  test("addition should work correctly") {
50
    assert(1 + 1 === 2)
51
  }
52
  
53
  test("division should handle zero denominator") {
54
    assertThrows[ArithmeticException] {
55
      1 / 0
56
    }
57
  }
58
}
59
```
60

61
### BDD-Style Specification (FlatSpec)
62
```scala
63
import org.scalatest.flatspec.AnyFlatSpec
64
import org.scalatest.matchers.should.Matchers
65

66
class StackSpec extends AnyFlatSpec with Matchers {
67
  "A Stack" should "pop values in last-in-first-out order" in {
68
    val stack = Stack()
69
    stack.push(1)
70
    stack.push(2)
71
    stack.pop() should be(2)
72
    stack.pop() should be(1)
73
  }
74
  
75
  it should "throw NoSuchElementException if an empty stack is popped" in {
76
    val emptyStack = Stack()
77
    a [NoSuchElementException] should be thrownBy {
78
      emptyStack.pop()
79
    }
80
  }
81
}
82
```
83

84
### Scalactic Or Type for Error Handling
85
```scala
86
import org.scalactic._
87

88
def divide(x: Int, y: Int): Int Or String = {
89
  if (y == 0) Bad("Cannot divide by zero")
90
  else Good(x / y)
91
}
92

93
val result = divide(10, 2)
94
result match {
95
  case Good(value) => println(s"Result: $value")
96
  case Bad(error) => println(s"Error: $error")
97
}
98
```
99

100
## Architecture
101

102
ScalaTest follows a modular architecture with several key components:
103

104
- **Core Framework**: Base traits (`Suite`, `Assertions`) providing lifecycle and assertion capabilities
105
- **Test Styles**: Eight different styles (FunSuite, FlatSpec, WordSpec, etc.) offering varied syntax and organization
106
- **Matcher System**: Rich DSL for expressing expectations with natural language constructs
107
- **Scalactic Utilities**: Functional programming helpers including the `Or` type for error handling
108
- **Runner System**: Command-line and programmatic test execution with flexible reporting
109
- **Async Support**: Future-based testing with built-in timeout and error handling
110

111
## Version Information
112

113
```scala { .api }
114
val ScalaTestVersion: String  // "3.2.19"
115
val ScalacticVersion: String  // Scalactic version
116
```
117

118
## Capabilities
119

120
### Test Styles
121

122
ScalaTest offers eight distinct testing styles to accommodate different preferences and use cases.
123

124
```scala { .api }
125
// Function-based testing
126
class MyFunSuite extends AnyFunSuite
127
test("test name") { /* test code */ }
128

129
// BDD flat specification  
130
class MyFlatSpec extends AnyFlatSpec
131
"subject" should "behavior" in { /* test code */ }
132

133
// Word-based specification
134
class MyWordSpec extends AnyWordSpec
135
"subject" when { "condition" should { "behavior" in { /* test code */ } } }
136
```
137

138
[Test Styles](./test-styles.md)
139

140
### Assertions and Matchers
141

142
Comprehensive assertion capabilities with macro-enhanced error messages and natural language matcher DSL.
143

144
```scala { .api }
145
// Core assertions
146
def assert(condition: Boolean): Assertion
147
def assertResult(expected: Any)(actual: Any): Assertion
148
def assertThrows[T <: AnyRef](code: => Any): Assertion
149

150
// Should matchers DSL
151
value should equal(expected)
152
value should be > 5
153
collection should contain("element")
154
```
155

156
[Assertions and Matchers](./assertions-matchers.md)
157

158
### Scalactic Utilities
159

160
Functional programming utilities including the Or type for railway-oriented programming and equality abstractions.
161

162
```scala { .api }
163
// Or type for error handling
164
sealed abstract class Or[+G, +B]
165
case class Good[G](value: G) extends Or[G, Nothing]
166
case class Bad[B](value: B) extends Or[Nothing, B]
167

168
// Safe execution
169
def attempt[R](f: => R): R Or Throwable
170
```
171

172
[Scalactic Utilities](./scalactic-utilities.md)
173

174
### Test Execution and Configuration
175

176
Programmatic and command-line test execution with extensive configuration options and reporting formats.
177

178
```scala { .api }
179
// Test execution
180
def run(testName: Option[String], args: Args): Status
181
object Runner { def main(args: Array[String]): Unit }
182

183
// Configuration
184
type ConfigMap = Map[String, Any]
185
case class Args(reporter: Reporter, stopper: Stopper, filter: Filter, ...)
186
```
187

188
[Test Execution](./test-execution.md)
189

190
### Async Testing
191

192
Future-based asynchronous testing support with automatic timeout handling and assertion integration.
193

194
```scala { .api }
195
// Async test suites return Future[Assertion]
196
class MyAsyncFunSuite extends AsyncFunSuite
197
test("async test") {
198
  Future { assert(true) }
199
}
200

201
// ScalaFutures trait for Future handling
202
trait ScalaFutures {
203
  def whenReady[T](future: Future[T])(fun: T => Unit): Unit
204
}
205
```
206

207
[Async Testing](./async-testing.md)
208

209
## Types
210

211
### Core Types
212

213
```scala { .api }
214
// Result of assertions
215
type Assertion = compatible.Assertion
216
val succeed: Assertion
217

218
// Test lifecycle
219
trait Suite {
220
  def run(testName: Option[String], args: Args): Status
221
  def testNames: Set[String]
222
  def nestedSuites: IndexedSeq[Suite]
223
}
224

225
// Test metadata
226
case class TestData(
227
  name: String,
228
  configMap: ConfigMap,
229
  scopes: Vector[String],
230
  text: String,
231
  tags: Set[String],
232
  pos: Option[source.Position]
233
)
234
```
235

236
### Configuration Types
237

238
```scala { .api }
239
// Test execution arguments
240
case class Args(
241
  reporter: Reporter,
242
  stopper: Stopper,
243
  filter: Filter,
244
  configMap: ConfigMap,
245
  distributor: Option[Distributor],
246
  tracker: Tracker,
247
  chosenStyles: Set[String],
248
  runTestInNewInstance: Boolean,
249
  distributedTestSorter: Option[DistributedTestSorter],
250
  summaryCounter: SummaryCounter
251
)
252

253
// Test filtering
254
class Filter(
255
  tagsToInclude: Option[Set[String]] = None,
256
  tagsToExclude: Set[String] = Set.empty,
257
  excludeNestedSuites: Boolean = false,
258
  dynaTags: DynaTags = DynaTags(Map.empty, Map.empty)
259
)
260

261
// Test execution status
262
sealed trait Status {
263
  def isCompleted: Boolean
264
  def succeeds(): Boolean
265
  def unreportedException: Option[Throwable]
266
}
267
```
268

269
### Scalactic Types
270

271
```scala { .api }
272
// Error handling type
273
sealed abstract class Or[+G, +B] {
274
  def isGood: Boolean
275
  def isBad: Boolean
276
  def get: G
277
  def getOrElse[H >: G](alternative: => H): H
278
  def map[H](f: G => H): H Or B
279
  def flatMap[H, C >: B](f: G => H Or C): H Or C
280
}
281

282
// Equality abstractions
283
trait Equality[T] {
284
  def areEqual(a: T, b: Any): Boolean
285
}
286

287
// Error message type
288
type ErrorMessage = String
289
```