0
# Specs2
1

2
Specs2 is a comprehensive testing framework and specification library for Scala that enables behavior-driven development (BDD) through executable specifications. It provides a rich domain-specific language for writing tests that read like natural language documentation, supports both mutable and immutable specification styles, and includes advanced matchers for various data types, custom matchers, and integration with property-based testing via ScalaCheck. The library offers multiple output formats including HTML, console, and JUnit XML reporting, making it suitable for both documentation generation and continuous integration environments.
3

4
## Package Information
5

6
- **Package Name**: org.specs2:specs2_2.10
7
- **Package Type**: maven
8
- **Language**: Scala 2.10
9
- **Installation**: `libraryDependencies += "org.specs2" %% "specs2" % "3.3.1" % "test"`
10

11
## Core Imports
12

13
```scala
14
import org.specs2._
15
import org.specs2.mutable._  // for mutable specifications
16
import org.specs2.matcher._  // for matchers
17
```
18

19
For Maven:
20
```xml
21
<dependency>
22
  <groupId>org.specs2</groupId>
23
  <artifactId>specs2_2.10</artifactId>
24
  <version>3.3.1</version>
25
  <scope>test</scope>
26
</dependency>
27
```
28

29
## Basic Usage
30

31
```scala
32
import org.specs2._
33

34
// Immutable (functional) specification style
35
class CalculatorSpec extends Specification { def is = s2"""
36
  Calculator should
37
    add two numbers correctly          $add
38
    subtract two numbers correctly     $subtract
39
    handle edge cases                  $edge
40
  """
41

42
  def add = {
43
    val calc = new Calculator
44
    calc.add(2, 3) must beEqualTo(5)
45
  }
46

47
  def subtract = {
48
    val calc = new Calculator  
49
    calc.subtract(5, 2) must beEqualTo(3)
50
  }
51

52
  def edge = {
53
    val calc = new Calculator
54
    calc.divide(1, 0) must throwA[ArithmeticException]
55
  }
56
}
57

58
// Mutable (imperative) specification style  
59
import org.specs2.mutable._
60

61
class CalculatorMutableSpec extends Specification {
62
  "Calculator" should {
63
    "add two numbers correctly" in {
64
      val calc = new Calculator
65
      calc.add(2, 3) must beEqualTo(5)
66
    }
67
    
68
    "subtract two numbers correctly" in {
69
      val calc = new Calculator
70
      calc.subtract(5, 2) must beEqualTo(3)
71
    }
72
  }
73
}
74
```
75

76
## Architecture
77

78
Specs2 is built around several key architectural patterns:
79

80
- **Dual API Design**: Both immutable (functional) and mutable (imperative) specification styles
81
- **Modular Architecture**: Clear separation between core, matchers, reporting, and integration modules
82
- **Fragment-Based Structure**: Specifications are composed of `Fragment` objects (text, examples, steps, actions)
83
- **Matcher System**: Type-safe matchers with composition and custom matcher creation capabilities
84
- **Scalaz Integration**: Functional programming abstractions for composition and error handling
85
- **Plugin Architecture**: Extensible through traits and integration modules
86

87
## Capabilities
88

89
### Core Specifications
90

91
Base specification classes and traits for creating both immutable and mutable test specifications. Provides the foundation for all test writing in specs2.
92

93
```scala { .api }
94
abstract class Specification extends SpecificationLike
95

96
trait SpecificationLike extends ImmutableSpecificationStructure 
97
  with SpecificationCreation with SpecificationFeatures
98

99
abstract class Spec extends SpecLike
100

101
trait SpecLike extends ImmutableSpecificationStructure 
102
  with S2StringContext1 with AcceptanceDsl1 with MustMatchers1
103
```
104

105
[Core Specifications](./core-specifications.md)
106

107
### Mutable Specifications
108

109
Mutable specification classes that use thrown expectations and imperative-style test definition. Ideal for developers who prefer traditional unit testing syntax.
110

111
```scala { .api }
112
// org.specs2.mutable package
113
abstract class Specification extends SpecificationLike
114

115
trait SpecificationLike extends SpecificationStructure 
116
  with SpecificationCreation with SpecificationFeatures
117

118
abstract class Spec extends SpecLike
119
```
120

121
[Mutable Specifications](./mutable-specifications.md)
122

123
### Matcher System
124

125
Comprehensive matcher system for assertions with type-safe composition, built-in matchers for common data types, and support for custom matchers.
126

127
```scala { .api }
128
trait Matcher[T] {
129
  def apply[S <: T](expectable: Expectable[S]): MatchResult[S]
130
  def and[S <: T](m: Matcher[S]): Matcher[S]
131
  def or[S <: T](m: Matcher[S]): Matcher[S]
132
  def not: Matcher[T]
133
}
134

135
trait Matchers extends AnyMatchers with StringMatchers 
136
  with TraversableMatchers with NumericMatchers
137
  with ExceptionMatchers with OptionMatchers
138
  with EitherMatchers with FutureMatchers
139
```
140

141
[Matcher System](./matcher-system.md)
142

143
### DSL Components
144

145
Domain-specific language components for creating readable and expressive test specifications with natural language syntax.
146

147
```scala { .api }
148
trait AcceptanceDsl extends FragmentsDsl with SpecStructureDsl 
149
  with TitleDsl with ExampleDsl with ReferenceDsl 
150
  with TagDsl with ActionDsl
151

152
trait ExampleDsl {
153
  def in[T: AsResult](t: => T): Fragment
154
  def >>[T: AsResult](t: => T): Fragment  
155
  def should[T: AsResult](t: => T): Fragment
156
  def can[T: AsResult](t: => T): Fragment
157
}
158
```
159

160
[DSL Components](./dsl-components.md)
161

162
### Test Execution and Configuration
163

164
Test runners, configuration options, and execution control for running specifications in various environments.
165

166
```scala { .api }
167
object Runner {
168
  def execute(actions: Action[Unit], arguments: Arguments, exit: Boolean): Unit
169
}
170

171
case class Arguments(
172
  plan: Boolean = false,
173
  skipAll: Boolean = false,
174
  stopOnFail: Boolean = false,
175
  sequential: Boolean = false,
176
  threadsNb: Int = Runtime.getRuntime.availableProcessors
177
)
178
```
179

180
[Test Execution](./test-execution.md)
181

182
### Reporting and HTML
183

184
Flexible reporting system with console, HTML, and markdown output formats for generating documentation and test reports.
185

186
```scala { .api }
187
trait Reporter {
188
  def report(spec: SpecificationStructure): Action[Unit]
189
}
190

191
trait TextPrinter extends Printer
192
trait MarkdownPrinter extends Printer
193
trait HtmlTemplate
194
```
195

196
[Reporting](./reporting.md)
197

198
### Integration Features
199

200
Integration modules for JUnit, ScalaCheck property-based testing, and mock frameworks like Mockito.
201

202
```scala { .api }
203
// JUnit integration
204
@RunWith(classOf[JUnitRunner])
205
abstract class SpecificationWithJUnit extends Specification
206

207
// ScalaCheck integration  
208
trait ScalaCheckProperty {
209
  def prop[T: Arbitrary](f: T => Boolean): Prop
210
}
211

212
// Mockito integration
213
trait Mockito {
214
  def mock[T: ClassTag]: T
215
}
216
```
217

218
[Integration Features](./integration-features.md)
219

220
## Common Patterns
221

222
### String Interpolation
223

224
Specs2 provides string interpolation for embedding tests directly in specification text:
225

226
```scala
227
class MySpec extends Specification { def is = s2"""
228
  This is a specification with embedded examples
229
    example 1 $e1
230
    example 2 $e2  
231
  """
232
  
233
  def e1 = 1 + 1 must beEqualTo(2)
234
  def e2 = "hello" must have size(5)
235
}
236
```
237

238
### Matchers Composition
239

240
Matchers can be composed using logical operators:
241

242
```scala
243
// AND composition
244
result must (beGreaterThan(0) and beLessThan(100))
245

246
// OR composition  
247
result must (beEqualTo("success") or beEqualTo("ok"))
248

249
// Negation
250
result must not(beEmpty)
251
```
252

253
### Custom Matchers
254

255
Create custom matchers for domain-specific assertions:
256

257
```scala
258
def beValidEmail = be matching("\\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Z|a-z]{2,}\\b".r) ^^ 
259
  ((_:String).toLowerCase, "a valid email address")
260

261
"user@example.com" must beValidEmail
262
```
263

264
## Types
265

266
```scala { .api }
267
// Core result types
268
sealed trait Result
269
case class Success(message: String = "") extends Result  
270
case class Failure(message: String) extends Result
271
case class Error(message: String, exception: Throwable) extends Result
272
case class Skipped(message: String = "") extends Result
273
case class Pending(message: String = "") extends Result
274

275
// Fragment types
276
sealed trait Fragment
277
case class Text(text: String) extends Fragment
278
case class Example(description: String, body: Execution) extends Fragment
279
case class Step(action: () => Any) extends Fragment
280
case class Action(action: () => Any) extends Fragment
281

282
// Matcher result types
283
case class MatchResult[T](
284
  expectable: Expectable[T],
285
  message: Message,
286
  negatedMessage: Message
287
)
288

289
case class Expectable[T](value: T, description: String)
290
```