0
# Execution
1

2
Execute property-based tests with comprehensive result reporting, failure analysis, seed capture for reproducibility, and statistical data collection. The execution system handles property evaluation, result interpretation, and detailed error reporting with shrinking of counterexamples.
3

4
## Capabilities
5

6
### Property Execution
7

8
Execute individual properties and property collections with configurable parameters and comprehensive result reporting.
9

10
```scala { .api }
11
trait ScalaCheckPropertyCheck extends ExpectationsCreation {
12
  def check(
13
    prop: Prop, 
14
    parameters: Parameters, 
15
    prettyFreqMap: FreqMap[Set[Any]] => Pretty
16
  ): Result
17
  
18
  def checkProperties(
19
    properties: Properties, 
20
    parameters: Parameters, 
21
    prettyFreqMap: FreqMap[Set[Any]] => Pretty
22
  ): Result
23
}
24
```
25

26
**Usage:**
27
```scala
28
import org.specs2._
29
import org.specs2.scalacheck._
30
import org.scalacheck._
31

32
class ExecutionSpec extends Specification with ScalaCheckPropertyCheck { def is = s2"""
33
  Manual property execution ${
34
    val prop = Prop.forAll((n: Int) => n + 0 == n)
35
    check(prop, Parameters().verbose, defaultFreqMapPretty) must beASuccess
36
  }
37
  
38
  Properties collection ${
39
    val props = new Properties("arithmetic") {
40
      property("addition") = Prop.forAll((a: Int, b: Int) => a + b == b + a)
41
      property("multiplication") = Prop.forAll((x: Int) => x * 1 == x)
42
    }
43
    checkProperties(props, Parameters(), defaultFreqMapPretty) must beASuccess
44
  }
45
"""
46
}
47
```
48

49
### Result Interpretation
50

51
Process property execution results with detailed failure analysis, exception handling, and statistical reporting.
52

53
```scala { .api }
54
trait ScalaCheckPropertyCheck {
55
  def checkResultFailure(checkResult: Result): Result
56
  def showCause(t: Throwable): String
57
  def frequencies(fq: FreqMap[Set[Any]], parameters: Parameters, prettyFreqMap: FreqMap[Set[Any]] => Pretty): String
58
  def prettyResult(
59
    res: Test.Result, 
60
    parameters: Parameters, 
61
    initialSeed: =>Seed,
62
    freqMapPretty: FreqMap[Set[Any]] => Pretty
63
  ): Pretty
64
}
65
```
66

67
Result types include:
68
- **Success**: Property passed all tests
69
- **Failure**: Property failed with counterexample and shrinking
70
- **Error**: Exception occurred during property evaluation
71
- **Exhausted**: Too many discarded tests
72

73
### Seed Capture and Reproducibility
74

75
Automatically capture random seeds used during property execution for reproducible test runs and debugging.
76

77
```scala { .api }
78
// Seed is automatically captured during property execution
79
// and included in failure reports for reproducibility
80
```
81

82
**Usage:**
83
```scala
84
class ReproducibilitySpec extends Specification with ScalaCheck { def is = s2"""
85
  Failing property debugging ${ 
86
    // When a property fails, the seed will be reported:
87
    // "The seed is AbCdEf1234567890"
88
    // Use this seed to reproduce the exact failure:
89
    prop((data: ComplexType) => processData(data).isValid)
90
      .setSeed("AbCdEf1234567890")  // Reproduce exact failure
91
  }
92
"""
93
}
94
```
95

96
### Statistical Data Collection
97

98
Collect and display statistical information about generated test data using frequency maps and custom collectors.
99

100
```scala { .api }
101
// Frequency map handling for statistical reporting
102
def frequencies(fq: FreqMap[Set[Any]], parameters: Parameters, prettyFreqMap: FreqMap[Set[Any]] => Pretty): String
103

104
// Pretty printing of frequency maps
105
implicit def defaultFreqMapPretty: FreqMap[Set[Any]] => Pretty
106
```
107

108
**Usage:**
109
```scala
110
class StatisticsSpec extends Specification with ScalaCheck { def is = s2"""
111
  Data distribution analysis ${
112
    prop((x: Int) => x * x >= 0)
113
      .collectArg(x => if (x >= 0) "positive" else "negative")
114
      .display()  // Shows frequency distribution
115
  }
116
  
117
  Complex data collection ${
118
    prop((data: List[String]) => data.length >= 0)
119
      .collectArg(_.length)
120
      .collectArg(data => s"size-bucket-${data.length / 10}")
121
      .verbose
122
  }
123
"""
124
}
125
```
126

127
### Exception Handling
128

129
Handle various types of exceptions that can occur during property evaluation with appropriate error categorization.
130

131
```scala { .api }
132
// Exception types handled:
133
// - FailureException: Converted to normal failures
134
// - DecoratedResultException: Enhanced failure reporting  
135
// - AssertionError: Test assertion failures
136
// - SkipException: Skipped tests
137
// - PendingException: Pending tests
138
// - NonFatal exceptions: Converted to errors
139
```
140

141
**Usage:**
142
```scala
143
class ExceptionHandlingSpec extends Specification with ScalaCheck { def is = s2"""
144
  Exception in property ${
145
    prop((n: Int) => {
146
      if (n == 42) throw new IllegalArgumentException("Special case")
147
      n >= 0 || n < 0  // Always true except for exception case
148
    }).set(minTestsOk = 1000)  // Increase chances of hitting exception
149
  }
150
  
151
  Assertion failure ${
152
    prop((s: String) => {
153
      assert(s.length >= 0, "String length must be non-negative")
154
      true
155
    })
156
  }
157
"""
158
}
159
```
160

161
### Pretty Printing and Reporting
162

163
Format test results with detailed information including test statistics, failure details, and execution time.
164

165
```scala { .api }
166
def prettyResult(
167
  res: Test.Result, 
168
  parameters: Parameters, 
169
  initialSeed: =>Seed,
170
  freqMapPretty: FreqMap[Set[Any]] => Pretty
171
): Pretty
172
```
173

174
Output includes:
175
- **Passed tests**: "OK, passed N tests"
176
- **Failed tests**: "Falsified after N passed tests" with counterexample
177
- **Proved properties**: "OK, proved property" with arguments
178
- **Exhausted tests**: "Gave up after only N passed tests"
179
- **Seed information**: Random seed for reproducibility
180
- **Execution time**: Performance metrics
181
- **Frequency maps**: Statistical data collection
182

183
## Types
184

185
```scala { .api }
186
// Property checking trait
187
trait ScalaCheckPropertyCheck extends ExpectationsCreation {
188
  def check(prop: Prop, parameters: Parameters, prettyFreqMap: FreqMap[Set[Any]] => Pretty): Result
189
  def checkProperties(properties: Properties, parameters: Parameters, prettyFreqMap: FreqMap[Set[Any]] => Pretty): Result
190
  def checkResultFailure(checkResult: Result): Result
191
  def showCause(t: Throwable): String
192
  def frequencies(fq: FreqMap[Set[Any]], parameters: Parameters, prettyFreqMap: FreqMap[Set[Any]] => Pretty): String
193
  def prettyResult(res: Test.Result, parameters: Parameters, initialSeed: =>Seed, freqMapPretty: FreqMap[Set[Any]] => Pretty): Pretty
194
}
195

196
// Result types (from specs2)
197
sealed trait Result
198
case class Success(message: String, expected: String, successCount: Int) extends Result
199
case class Failure(message: String, expected: String = "", details: Details = NoDetails, trace: List[StackTraceElement] = Nil) extends Result
200
case class Error(message: String, exception: Throwable) extends Result
201
```