0
# specs2-scalacheck
1

2
specs2-scalacheck provides ScalaCheck integration for the specs2 testing framework, enabling property-based testing within specs2 specifications. It bridges ScalaCheck's powerful property generators and testing capabilities with specs2's expressive DSL and comprehensive reporting system.
3

4
## Package Information
5

6
- **Package Name**: specs2-scalacheck_2.12
7
- **Package Type**: maven
8
- **Language**: Scala
9
- **Installation**: Add to your `build.sbt`:
10
  ```scala
11
  libraryDependencies += "org.specs2" %% "specs2-scalacheck" % "3.10.0"
12
  ```
13

14
## Core Imports
15

16
```scala
17
import org.specs2.ScalaCheck
18
import org.specs2.scalacheck._
19
```
20

21
For specific functionality:
22

23
```scala
24
import org.specs2.scalacheck.{Parameters, ScalaCheckProperty}
25
```
26

27
## Basic Usage
28

29
```scala
30
import org.specs2.{Specification, ScalaCheck}
31
import org.scalacheck.{Arbitrary, Gen}
32

33
class MySpec extends Specification with ScalaCheck { def is = s2"""
34
  Basic property testing
35
    addition is commutative $commutativeAddition
36
    string reversal twice returns original $doubleReverse
37
"""
38

39
  def commutativeAddition = prop { (a: Int, b: Int) =>
40
    a + b must_== b + a
41
  }
42

43
  def doubleReverse = prop { (s: String) =>
44
    s.reverse.reverse must_== s
45
  }
46
}
47
```
48

49
## Architecture
50

51
specs2-scalacheck is built around several key components:
52

53
- **Property Creation**: Methods to create ScalaCheck properties from functions with 1-8 parameters
54
- **Parameter Configuration**: Comprehensive system for configuring test parameters with command line overrides
55
- **Property Checking**: Core execution engine that runs properties and formats results
56
- **Result Conversion**: Bidirectional conversion between ScalaCheck and specs2 result types
57
- **DSL Integration**: Seamless integration with specs2's specification DSL
58
- **Context Support**: Setup/teardown actions around property execution
59

60
## Capabilities
61

62
### Property Creation
63

64
Core functionality for creating ScalaCheck properties from test functions. Supports functions with 1-8 parameters with full typeclass customization.
65

66
```scala { .api }
67
trait ScalaCheckPropertyCreation {
68
  def prop[T, R](result: T => R)(implicit 
69
    arbitrary: Arbitrary[T], 
70
    shrink: Shrink[T], 
71
    pretty: T => Pretty, 
72
    prettyFreqMap: FreqMap[Set[Any]] => Pretty,
73
    asResult: AsResult[R], 
74
    parameters: Parameters
75
  ): ScalaCheckFunction1[T, R]
76
}
77
```
78

79
[Property Creation](./property-creation.md)
80

81
### Property Configuration
82

83
Comprehensive parameter configuration system with fluent API for setting test parameters, verbosity, and ScalaCheck settings.
84

85
```scala { .api }
86
case class Parameters(
87
  minTestsOk: Int = Test.Parameters.default.minSuccessfulTests,
88
  minSize: Int = Test.Parameters.default.minSize,
89
  maxDiscardRatio: Float = Test.Parameters.default.maxDiscardRatio,
90
  maxSize: Int = Test.Parameters.default.maxSize,
91
  workers: Int = Test.Parameters.default.workers,
92
  testCallback: Test.TestCallback = Test.Parameters.default.testCallback,
93
  loader: Option[ClassLoader] = Test.Parameters.default.customClassLoader,
94
  prettyParams: Pretty.Params = Pretty.defaultParams
95
)
96
```
97

98
[Property Configuration](./property-configuration.md)
99

100
### Property Execution and Checking
101

102
Core property checking functionality that executes ScalaCheck properties and converts results to specs2 format.
103

104
```scala { .api }
105
trait ScalaCheckPropertyCheck {
106
  def check(
107
    prop: Prop, 
108
    parameters: Parameters, 
109
    prettyFreqMap: FreqMap[Set[Any]] => Pretty
110
  ): Result
111
  
112
  def checkProperties(
113
    properties: Properties, 
114
    parameters: Parameters, 
115
    prettyFreqMap: FreqMap[Set[Any]] => Pretty
116
  ): Result
117
}
118
```
119

120
[Property Checking](./property-checking.md)
121

122
### Result Conversion
123

124
Bidirectional conversion system between ScalaCheck Prop/Properties and specs2 AsResult types for seamless integration.
125

126
```scala { .api }
127
trait AsResultProp {
128
  implicit def asResultToProp[R : AsResult](r: R): Prop
129
  implicit def propAsResult(implicit p: Parameters, pfq: FreqMap[Set[Any]] => Pretty): AsResult[Prop]
130
  implicit def propertiesAsResult(implicit p: Parameters, pfq: FreqMap[Set[Any]] => Pretty): AsResult[Properties]
131
}
132
```
133

134
[Result Conversion](./result-conversion.md)
135

136
### DSL Integration
137

138
Integration with specs2's specification DSL for displaying Properties as examples and converting Prop objects.
139

140
```scala { .api }
141
trait ScalaCheckPropertyDsl {
142
  implicit def propToScalaCheckProperty(prop: Prop)(implicit 
143
    parameters: Parameters, 
144
    prettyFreqMap: FreqMap[Set[Any]] => Pretty
145
  ): ScalaCheckProp
146
  
147
  def properties(ps: Properties): Fragments
148
}
149
```
150

151
[DSL Integration](./dsl-integration.md)
152

153
### Utilities
154

155
Utility traits and objects for expectation control, pretty printing enhancements, and Scalaz integration.
156

157
```scala { .api }
158
trait OneExpectationPerProp extends AsResultProp
159
object PrettyProduct
160
object PrettyDetails  
161
trait GenInstances
162
```
163

164
[Utilities](./utilities.md)
165

166

167
## Types
168

169
```scala { .api }
170
// Main entry point trait combining all functionality
171
trait ScalaCheck extends 
172
  ScalaCheckPropertyCreation with
173
  ScalaCheckPropertyCheck with
174
  ScalaCheckParameters with
175
  AsResultProp with
176
  ScalaCheckPropertyDsl with
177
  GenInstances
178

179
// Base property trait
180
trait ScalaCheckProperty {
181
  type SelfType <: ScalaCheckProperty
182
  def prop: Prop
183
  def parameters: Parameters
184
  def prettyFreqMap: FreqMap[Set[Any]] => Pretty
185
  def setParameters(ps: Parameters): SelfType
186
  def setVerbosity(v: Int): SelfType
187
  def verbose: SelfType
188
}
189

190
// Property with context support
191
trait ScalaCheckFunction extends ScalaCheckProperty {
192
  def noShrink: SelfType
193
  def context: Option[Context]
194
  def setContext(context: Context): SelfType
195
  def before(action: =>Any): SelfType
196
  def after(action: =>Any): SelfType
197
  def around(action: Result => Result): SelfType
198
}
199

200
// Simple property wrapper
201
case class ScalaCheckProp(
202
  prop: Prop, 
203
  parameters: Parameters, 
204
  prettyFreqMap: FreqMap[Set[Any]] => Pretty
205
) extends ScalaCheckProperty
206

207
// Parameter bundle for typeclass instances
208
case class ScalaCheckArgInstances[T](
209
  arbitrary: Arbitrary[T], 
210
  shrink: Option[Shrink[T]], 
211
  collectors: List[T => Any], 
212
  pretty: T => Pretty
213
)
214

215
// Utility trait for controlling expectation counts in specs2
216
trait OneExpectationPerProp extends AsResultProp {
217
  implicit override def propAsResult(implicit p: Parameters, pfq: FreqMap[Set[Any]] => Pretty): AsResult[Prop]
218
  implicit override def propertiesAsResult(implicit p: Parameters, pfq: FreqMap[Set[Any]] => Pretty): AsResult[Properties]
219
}
220

221
// Utility object for creating Pretty instances for case classes
222
object PrettyProduct {
223
  def toString[P <: Product](p: P): String
224
  def apply[P <: Product]: P => Pretty
225
}
226

227
// Utility object for handling failure details in frequency maps
228
object PrettyDetails {
229
  def collectDetails[T](fq: FreqMap[Set[T]]): execute.Details
230
  def removeDetails(fq: FreqMap[Set[Any]]): FreqMap[Set[Any]]
231
}
232

233
// Utility trait for controlling expectation counts in specs2
234
trait OneExpectationPerProp extends AsResultProp {
235
  implicit override def propAsResult(implicit p: Parameters, pfq: FreqMap[Set[Any]] => Pretty): AsResult[Prop]
236
  implicit override def propertiesAsResult(implicit p: Parameters, pfq: FreqMap[Set[Any]] => Pretty): AsResult[Properties]
237
}
238

239
// Scalaz typeclass instances for ScalaCheck Gen
240
trait GenInstances {
241
  implicit def genMonad: Monad[Gen]
242
}
243
```