0
# Property Configuration
1

2
Comprehensive parameter configuration system for controlling ScalaCheck test execution, including test counts, sizing, parallelism, and output formatting. The configuration system supports both programmatic setup and command-line overrides.
3

4
## Capabilities
5

6
### Parameters Configuration
7

8
The `Parameters` case class encapsulates all ScalaCheck test parameters along with specs2-specific settings for pretty printing and verbosity.
9

10
```scala { .api }
11
/**
12
 * ScalaCheck parameters with specs2 integration
13
 * @param minTestsOk - Minimum successful tests required (default: ScalaCheck default)
14
 * @param minSize - Minimum size for generators (default: ScalaCheck default)  
15
 * @param maxDiscardRatio - Maximum ratio of discarded to successful tests (default: ScalaCheck default)
16
 * @param maxSize - Maximum size for generators (default: ScalaCheck default)
17
 * @param workers - Number of worker threads (default: ScalaCheck default)
18
 * @param testCallback - Callback for test events (default: ScalaCheck default)
19
 * @param loader - Custom class loader (default: None)
20
 * @param prettyParams - Pretty printing parameters (default: Pretty.defaultParams)
21
 */
22
case class Parameters(
23
  minTestsOk: Int = Test.Parameters.default.minSuccessfulTests,
24
  minSize: Int = Test.Parameters.default.minSize,
25
  maxDiscardRatio: Float = Test.Parameters.default.maxDiscardRatio,
26
  maxSize: Int = Test.Parameters.default.maxSize,
27
  workers: Int = Test.Parameters.default.workers,
28
  testCallback: Test.TestCallback = Test.Parameters.default.testCallback,
29
  loader: Option[ClassLoader] = Test.Parameters.default.customClassLoader,
30
  prettyParams: Pretty.Params = Pretty.defaultParams
31
) {
32
  
33
  /** Enable verbose output (verbosity = 1) */
34
  def verbose: Parameters
35
  
36
  /** Set specific verbosity level */
37
  def setVerbosity(v: Int): Parameters
38
  
39
  /** Convert to native ScalaCheck parameters */
40
  def testParameters: Test.Parameters
41
  
42
  /** Override parameters with command line arguments */
43
  def overrideWith(commandLine: CommandLine): Parameters
44
}
45
```
46

47
**Usage Examples:**
48

49
```scala
50
import org.specs2.scalacheck.Parameters
51

52
// Basic parameter configuration
53
implicit val params = Parameters().verbose
54

55
// Custom parameter settings
56
implicit val customParams = Parameters(
57
  minTestsOk = 200,
58
  maxSize = 100,
59
  workers = 2
60
).setVerbosity(2)
61

62
// Using parameters in properties
63
def myProperty = {
64
  implicit val p = Parameters(minTestsOk = 500)
65
  prop { (x: Int) => x + 0 == x }
66
}
67
```
68

69
### Default Parameters Provider
70

71
The `ScalaCheckParameters` trait provides default parameter instances and helper methods for parameter creation.
72

73
```scala { .api }
74
trait ScalaCheckParameters {
75
  /** Default parameters instance with standard ScalaCheck values */
76
  implicit def defaultParameters: Parameters
77
  
78
  /** Default frequency map pretty printer that removes failure details */
79
  implicit def defaultFreqMapPretty: FreqMap[Set[Any]] => Pretty
80
  
81
  /** 
82
   * Create parameters with verbose = false
83
   * @param minTestsOk - Minimum successful tests (default: 100)
84
   * @param minSize - Minimum generator size (default: 0)
85
   * @param maxDiscardRatio - Maximum discard ratio (default: 5.0)
86
   * @param maxSize - Maximum generator size (default: 100)
87
   * @param workers - Number of workers (default: 1)
88
   * @param callback - Test callback (default: no-op)
89
   * @param loader - Custom class loader (default: None)
90
   */
91
  def set(
92
    minTestsOk: Int = defaultParameters.minTestsOk,
93
    minSize: Int = defaultParameters.minSize,
94
    maxDiscardRatio: Float = defaultParameters.maxDiscardRatio,
95
    maxSize: Int = defaultParameters.maxSize,
96
    workers: Int = defaultParameters.workers,
97
    callback: Test.TestCallback = defaultParameters.testCallback,
98
    loader: Option[ClassLoader] = defaultParameters.loader
99
  ): Parameters
100
  
101
  /** 
102
   * Create parameters with verbose = true
103
   * Same parameters as set() but with verbose output enabled
104
   */
105
  def display(
106
    minTestsOk: Int = defaultParameters.minTestsOk,
107
    minSize: Int = defaultParameters.minSize,
108
    maxDiscardRatio: Float = defaultParameters.maxDiscardRatio,
109
    maxSize: Int = defaultParameters.maxSize,
110
    workers: Int = defaultParameters.workers,
111
    callback: Test.TestCallback = defaultParameters.testCallback,
112
    loader: Option[ClassLoader] = defaultParameters.loader
113
  ): Parameters
114
}
115
```
116

117
**Usage Examples:**
118

119
```scala
120
import org.specs2.ScalaCheck
121

122
class MySpec extends Specification with ScalaCheck { def is = s2"""
123
  Properties with different parameter settings
124
    quick test $quickTest
125
    thorough test $thoroughTest  
126
    parallel test $parallelTest
127
"""
128

129
  // Using default parameters
130
  def quickTest = prop { (x: Int) => x == x }
131
  
132
  // Using custom parameters with set()
133
  def thoroughTest = {
134
    implicit val params = set(minTestsOk = 1000, maxSize = 200)
135
    prop { (x: String) => x.reverse.reverse == x }
136
  }
137
  
138
  // Using verbose parameters with display()
139
  def parallelTest = {
140
    implicit val params = display(workers = 4, minTestsOk = 500)
141
    prop { (x: List[Int]) => x.sorted.length == x.length }
142
  }
143
}
144
```
145

146
### Property Parameter Configuration
147

148
Properties created with `prop` methods support fluent parameter configuration through method chaining.
149

150
```scala { .api }
151
trait ScalaCheckProperty {
152
  /** Set new parameters for this property */
153
  def setParameters(ps: Parameters): SelfType
154
  
155
  /** Set verbosity level (0 = quiet, 1+ = verbose) */
156
  def setVerbosity(v: Int): SelfType
157
  
158
  /** Enable verbose output (verbosity = 1) */
159
  def verbose: SelfType
160
  
161
  /** 
162
   * Configure test parameters fluently
163
   * @param minTestsOk - Minimum successful tests
164
   * @param minSize - Minimum generator size
165
   * @param maxDiscardRatio - Maximum discard ratio  
166
   * @param maxSize - Maximum generator size
167
   * @param workers - Number of worker threads
168
   * @param callback - Test callback
169
   * @param loader - Custom class loader
170
   */
171
  def set(
172
    minTestsOk: Int = parameters.minTestsOk,
173
    minSize: Int = parameters.minSize,
174
    maxDiscardRatio: Float = parameters.maxDiscardRatio,
175
    maxSize: Int = parameters.maxSize,
176
    workers: Int = parameters.workers,
177
    callback: Test.TestCallback = parameters.testCallback,
178
    loader: Option[ClassLoader] = parameters.loader
179
  ): SelfType
180
  
181
  /** 
182
   * Configure test parameters with verbose output enabled
183
   * Same parameters as set() but automatically enables verbose mode
184
   */
185
  def display(
186
    minTestsOk: Int = parameters.minTestsOk,
187
    minSize: Int = parameters.minSize,
188
    maxDiscardRatio: Float = parameters.maxDiscardRatio,
189
    maxSize: Int = parameters.maxSize,
190
    workers: Int = parameters.workers,
191
    callback: Test.TestCallback = parameters.testCallback,
192
    loader: Option[ClassLoader] = parameters.loader
193
  ): SelfType
194
}
195
```
196

197
**Usage Examples:**
198

199
```scala
200
// Fluent parameter configuration
201
def configurableProperty = {
202
  prop { (x: Int, y: Int) =>
203
    x + y == y + x
204
  }.set(minTestsOk = 300, maxSize = 150)
205
   .verbose
206
}
207

208
// Display mode with custom settings
209
def debugProperty = {
210
  prop { (s: String) =>
211
    s.toLowerCase.toUpperCase == s.toUpperCase
212
  }.display(minTestsOk = 50, workers = 1)
213
}
214

215
// Chaining multiple configurations
216
def complexProperty = {
217
  prop { (list: List[Int]) =>
218
    list.reverse.reverse == list
219
  }.set(minTestsOk = 200)
220
   .setVerbosity(2)
221
   .display(maxSize = 50)
222
}
223
```
224

225
### Command Line Override Support
226

227
Parameters support runtime override from command line arguments, enabling configuration without recompilation.
228

229
```scala { .api }
230
/**
231
 * Override parameters with command line arguments
232
 * Supported command line options:
233
 * - scalacheck.mintestsok=N
234
 * - scalacheck.minsize=N  
235
 * - scalacheck.maxdiscardratio=F
236
 * - scalacheck.maxsize=N
237
 * - scalacheck.workers=N
238
 * - scalacheck.verbosity=N
239
 * - scalacheck.verbose=true/false
240
 */
241
def overrideWith(commandLine: CommandLine): Parameters
242
```
243

244
**Command Line Usage:**
245

246
```bash
247
# Run with custom test count
248
sbt "testOnly MySpec -- scalacheck.mintestsok=500"
249

250
# Run with verbose output and parallel workers
251
sbt "testOnly MySpec -- scalacheck.verbose=true scalacheck.workers=4"
252

253
# Run with custom size and discard ratio
254
sbt "testOnly MySpec -- scalacheck.maxsize=200 scalacheck.maxdiscardratio=10.0"
255

256
# Run with all available command line options
257
sbt "testOnly MySpec -- scalacheck.mintestsok=1000 scalacheck.minsize=5 scalacheck.maxsize=150 scalacheck.maxdiscardratio=8.0 scalacheck.workers=2 scalacheck.verbosity=2"
258
```
259

260
### Parameter Validation and Defaults
261

262
The parameter system provides sensible defaults and validation for ScalaCheck integration:
263

264
```scala { .api }
265
// Default parameter values from ScalaCheck
266
val defaultMinTestsOk: Int = Test.Parameters.default.minSuccessfulTests      // Usually 100
267
val defaultMinSize: Int = Test.Parameters.default.minSize                    // Usually 0  
268
val defaultMaxDiscardRatio: Float = Test.Parameters.default.maxDiscardRatio  // Usually 5.0
269
val defaultMaxSize: Int = Test.Parameters.default.maxSize                    // Usually 100
270
val defaultWorkers: Int = Test.Parameters.default.workers                    // Usually 1
271

272
// Pretty printing defaults
273
val defaultVerbosity: Int = Pretty.defaultParams.verbosity                   // Usually 0 (quiet)
274
```
275

276
**Parameter Guidelines:**
277

278
- **minTestsOk**: Higher values increase confidence but slow down tests (typical: 100-1000)
279
- **minSize/maxSize**: Control generator complexity (typical: 0-100, can go higher for stress testing)
280
- **maxDiscardRatio**: Higher values allow more filtering but may slow tests (typical: 5.0-20.0)
281
- **workers**: Parallel execution (typical: 1-4, based on CPU cores)
282
- **verbosity**: 0 = quiet, 1 = basic output, 2+ = detailed output