Spock Framework

https://github.com/spockframework/spock
Admin
Spock is a BDD-style developer testing and specification framework for Java and Groovy applications.
Tokens:157,444
Snippets:1,195
Trust Score:8.5
License:Apache-2.0
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### Detached Mock Factory for Classes

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/all_in_one.md

Application classes used in the example: Engine and Car, where Car has an Engine. Each car's drive method starts the engine and park stops it.

```groovy
class Engine {
  private boolean started

  boolean isStarted() { return started }

  void start() { started = true }

  void stop() { started = false }
}

class Car {
  private Engine engine

  void drive() { engine.start() }

  void park() { engine.stop() }
}

```

--------------------------------

### Inject mock subscribers into publisher in setup()

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/interaction_based_testing.md

Sets up a Publisher and two mock Subscribers, then registers the subscribers with the publisher in the setup() method. The << operator is Groovy shorthand for List.add().

```groovy
class PublisherSpec extends Specification {
  Publisher publisher = new Publisher()
  Subscriber subscriber = Mock()
  Subscriber subscriber2 = Mock()

  def setup() {
    publisher.subscribers << subscriber // << is a Groovy shorthand for List.add()
    publisher.subscribers << subscriber2
  }

```

--------------------------------

### Example snapshot config

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/extensions.md

Example Spock configuration file snippet for snapshot testing. Sets the rootPath directory, updateSnapshots flag, writeActualSnapshotOnMismatch flag, and defaultExtension.

```groovy
snapshots {
  rootPath = Paths.get("src/test/resources")
  updateSnapshots = System.getenv("UPDATE_SNAPSHOTS") == "true"
  writeActualSnapshotOnMismatch = !System.getenv("CI")
  defaultExtension = 'snap.groovy'
}
```

--------------------------------

### Publisher and Subscriber example with Spock specification

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/interaction_based_testing.md

Defines a Publisher class, Subscriber interface, and a Spock specification with a Publisher instance. This is the base example for demonstrating interaction-based testing with mocks.

```groovy
class Publisher {
  List<Subscriber> subscribers = []
  int messageCount = 0
  void send(String message){
    subscribers*.receive(message)
    messageCount++
  }
}

interface Subscriber {
  void receive(String message)
}

class PublisherSpec extends Specification {
  Publisher publisher = new Publisher()
}
```

--------------------------------

### Method constraint examples

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/interaction_based_testing.md

Method constraint examples: exact method name or a regular expression pattern. The regex /r.*e/ matches method names starting with 'r' and ending in 'e'.

```groovy
1 * subscriber.receive("hello") // a method named 'receive'
1 * subscriber./r.*e/("hello")  // a method whose name matches the given regular expression
                                // (here: method name starts with 'r' and ends in 'e')

```

--------------------------------

### Define Engine and Car classes for detached mocks

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/interaction_based_testing.md

Defines the application classes Engine and Car used in the detached mock example. Car depends on Engine and delegates drive and park to engine start and stop.

```groovy
class Engine {
  private boolean started

  boolean isStarted() { return started }

  void start() { started = true }

  void stop() { started = false }
}

class Car {
  private Engine engine

  void drive() { engine.start() }

  void park() { engine.stop() }
}
```

--------------------------------

### Example Gradle config for snapshot testing

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/extensions.md

Example Gradle configuration for snapshot testing. Sets the snapshot rootPath system property and conditionally enables snapshot updates and tag filtering when the updateSnapshots project property is present.

```groovy
tasks.named("test", Test) {
  useJUnitPlatform()
  // set the snapshot directory, as resources are already an input we don't need to track them separately
  systemProperty("spock.snapshots.rootPath", "src/test/resources")
  // allow updating the snapshots with running `gradlew test -PupdateSnapshots`
  if (project.hasProperty("updateSnapshots")) {
    systemProperty("spock.snapshots.updateSnapshots", "true")
    // not strictly necessary but speeds up the process by only executing snapshot tests
    useJUnitPlatform {
      includeTags("snapshot")
    }
  }
}
```

--------------------------------

### Custom Mock Maker with FancyMockMaker and Usage Example

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/extensions.md

Complete custom mock maker example: the Java implementation defines FancyMockMaker, FancyMockMakerSettings, and the FancyMockMakers entry point; the Groovy usage shows how to select it via the mockMaker argument and the resulting failure message.

```java
public final class FancyMockMaker implements IMockMaker {
  static final MockMakerId ID = new MockMakerId("fancy");

  private static final Set<MockMakerCapability> CAPABILITIES = EnumSet.of(
    MockMakerCapability.CLASS,
    MockMakerCapability.EXPLICIT_CONSTRUCTOR_ARGUMENTS);

  public FancyMockMaker() {
  }

  @Override
  public MockMakerId getId() {
    return ID;
  }

  @Override
  public Set<MockMakerCapability> getCapabilities() {
    return CAPABILITIES;
  }

  @Override
  public int getPriority() {
    return 5000;
  }

  @Override
  public Object makeMock(IMockCreationSettings settings) {
    FancyMockMakerSettings fancySettings = settings.getMockMakerSettings();
    return makeMockInternal(fancySettings);
  }

  @Override
  public IMockabilityResult getMockability(IMockCreationSettings settings) {
    FancyMockMakerSettings fancySettings = settings.getMockMakerSettings();
    if (fancySettings != null &&
      fancySettings.isSerialization() &&
      !fancySettings.getFancyTypes().isEmpty()) {
      return () -> "Mock with serialization and fancy types is not supported.";
    }
    return IMockabilityResult.MOCKABLE;
  }

  Object makeMockInternal(FancyMockMakerSettings settings) {
    //Implementation omitted ...
    return null;
  }
}

final class FancyMockMakerSettings implements IMockMakerSettings {
  private boolean serialization;
  private final List<Type> specialTypes = new ArrayList<>();

  FancyMockMakerSettings() {
  }

  boolean isSerialization() {
    return serialization;
  }

  List<Type> getFancyTypes() {
    return specialTypes;
  }

  @Override
  public MockMakerId getMockMakerId() {
    return FancyMockMaker.ID;
  }

  public void withSerialization() {
    serialization = true;
  }

  public void fancyTypes(Type... types) {
    this.specialTypes.addAll(Arrays.asList(types));
  }
}

final class FancyMockMakers {
  /**
   * Public static entry point for the User.
   */
  public static IMockMakerSettings fancyMock(
    @DelegatesTo(FancyMockMakerSettings.class)
    Closure<?> code) {
    FancyMockMakerSettings settings = new FancyMockMakerSettings();
    code.setDelegate(settings);
    code.call();
    return settings;
  }
}
```

```groovy
when:
Mock(ArrayList, mockMaker: FancyMockMakers.fancyMock {
  fancyTypes(List.class, String.class)
  withSerialization()
})
then:
CannotCreateMockException ex = thrown()
ex.message == "Cannot create mock for class java.util.ArrayList. fancy: Mock with serialization and fancy types is not supported."
```

--------------------------------

### Define Spock fixture methods: setupSpec, setup, cleanup, cleanupSpec

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/spock_primer.md

Declares the four optional fixture methods in a Spock specification. Use setup() and cleanup() for a fresh fixture per feature method; use setupSpec() and cleanupSpec() with @Shared fields for shared fixtures. Only one method of each type is allowed per specification class.

```groovy
def setupSpec() {}    // runs once -  before the first feature method
def setup() {}        // runs before every feature method
def cleanup() {}      // runs after every feature method
def cleanupSpec() {}  // runs once -  after the last feature method
```

--------------------------------

### @IgnoreIf with os.windows property

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/extensions.md

Rewrites the previous example using the os property from the precondition context, which is more readable. Skips the feature on Windows.

```groovy
@IgnoreIf({ os.windows })
def "I will run everywhere but on Windows"() {
```

--------------------------------

### Specification Class Inheritance Example

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/migration_guide.md

Demonstrates the class initialization order change between Spock 0.5 and 0.6 using Base and Derived classes.

```groovy
class Base extends Specification {
    def base1 = "base1"
    def base2

    def setup() { base2 = "base2" }
}

class Derived extends Base {
    def derived1 = "derived1"
    def derived2

    def setup() { derived2 = "derived2" }
}
```

--------------------------------

### Example specs for ExceptionCounterGlobalExtension

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/extensions.md

Example specifications used to demonstrate the ExceptionCounterGlobalExtension. They contain failing tests that throw IllegalStateException and IllegalArgumentException, producing the statistics output shown in the following example.

```groovy
class ASpec extends Specification {
  def "a failing test"() {
    expect: false
  }

  def "a test failing with an exception"() {
    given:
    if(1==1) throw new IllegalStateException()

    expect: true
  }
}

class BSpec extends Specification {

  def "illegal parameter for List"() {
    given:
    def value = new ArrayList<>(-1)

    expect:
    value.empty
  }

  def "illegal parameter for Map"() {
    given:
    def value = new HashMap(-1)

    expect:
    value.empty
  }
}
```

--------------------------------

### Report output with #iterationIndex

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/data_driven_testing.md

Example report output showing the iteration index.

```text
╷
└─ Spock ✔
   └─ PersonSpec ✔
      └─ #person.name is #person.age years old [#iterationIndex] ✔
         ├─ Fred is 38 years old [0] ✔
         ├─ Wilma is 36 years old [1] ✔
         └─ Pebbles is 5 years old [2] ✔
```

--------------------------------

### Example output of unrolled iteration

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/data_driven_testing.md

The output shows how placeholders are replaced with concrete values during test execution.

```text
maximum of 1 and 3 is 3   PASSED
maximum of 7 and 4 is 7   FAILED

Math.max(a, b) == c
|    |   |  |  |  |
|    |   7  4  |  7
|    42        false
class java.lang.Math

maximum of 0 and 0 is 0   PASSED
```

--------------------------------

### Target constraint examples

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/interaction_based_testing.md

Target constraint examples: a specific mock object or any mock object using the underscore wildcard.

```groovy
1 * subscriber.receive("hello") // a call to 'subscriber'
1 * _.receive("hello")          // a call to any mock object

```

--------------------------------

### ExceptionCounterGlobalExtension with example specs and output

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/all_in_one.md

A global extension that counts exceptions thrown during feature methods and prints a report at the end. The example specs trigger the exceptions, and the output shows the collected statistics.

```groovy
class ExceptionCounterGlobalExtension implements IGlobalExtension {
  private static final Namespace EXAMPLE_NS =                             // <1>
    Namespace.create(ExceptionCounterGlobalExtension)
  private static final String ACCUMULATOR = "accumulator"
  private static final IMethodInterceptor INTERCEPTOR =  {
    try {
      it.proceed()
    } catch (Exception e) {
      it.getStore(EXAMPLE_NS)                                             // <6>
        .get(ACCUMULATOR, ConcurrentHashMap)                              // <7>
        .computeIfAbsent(e.class.name, { __ -> new AtomicInteger() })     // <8>
        .incrementAndGet()
      throw e
    }
  }

  @Override
  void visitSpec(SpecInfo spec) {
    spec.allFeatures.featureMethod*.addInterceptor(INTERCEPTOR)           // <2>
  }

  @Override
  void executionStart(ISpockExecution spockExecution) {                   // <3>
    spockExecution.getStore(EXAMPLE_NS)                                   // <4>
      .put(ACCUMULATOR, new ConcurrentHashMap())                          // <5>
  }

  @Override
  void executionStop(ISpockExecution spockExecution) {                    // <9>
    def results = spockExecution.getStore(EXAMPLE_NS)
      .get(ACCUMULATOR, ConcurrentHashMap)

    if (!results.isEmpty()) {
      println "========================"
      println "==Exception statistics=="
      println "========================"
      results.toSorted().each { exceptionName, counter ->
        println "${counter}x $exceptionName"
      }
      println "========================"
    }
  }
}
```

```groovy
class ASpec extends Specification {
  def "a failing test"() {
    expect: false
  }

  def "a test failing with an exception"() {
    given:
    if(1==1) throw new IllegalStateException()

    expect: true
  }
}

class BSpec extends Specification {

  def "illegal parameter for List"() {
    given:
    def value = new ArrayList<>(-1)

    expect:
    value.empty
  }

  def "illegal parameter for Map"() {
    given:
    def value = new HashMap(-1)

    expect:
    value.empty
  }
}
```

```text
========================
==Exception statistics==
========================
1x java.lang.IllegalStateException
2x java.lang.IllegalArgumentException
========================
```

--------------------------------

### StaticClass Example

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/interaction_based_testing.md

Example static class used in the static mock examples. Provides two static methods that return fixed values.

```groovy
private static class StaticClass {
  static String staticMethod() {
    return "RealValue"
  }

  static String otherStaticMethod() {
    return "OtherValue"
  }
}
```

--------------------------------

### Stepwise on data-driven feature method example

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/extensions.md

Apply @Stepwise to a data-driven feature method to execute iterations sequentially and skip subsequent iterations if one fails. This example passes for the first two iterations, fails on the third, and skips the remaining two.

```groovy
class SkipAfterFailingIterationSpec extends Specification {
  @Stepwise
  def "iteration #count"()  {
    expect:
    count != 3

    where:
    count << (1..5)
  }
}
```

--------------------------------

### Output with #iterationIndex

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/all_in_one.md

Example output of an unrolled feature method with #iterationIndex, showing the reported iteration names with indices.

```text
╷
└─ Spock ✔
   └─ PersonSpec ✔
      └─ #person.name is #person.age years old [#iterationIndex] ✔
         ├─ Fred is 38 years old [0] ✔
         ├─ Wilma is 36 years old [1] ✔
         └─ Pebbles is 5 years old [2] ✔

```

--------------------------------

### Given block for setup

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/spock_primer.md

Sets up the fixture for a feature method. The given block is optional and can be omitted, resulting in an implicit given block. It may not be preceded by other blocks and may not be repeated.

```groovy
given:
def stack = new Stack()
def elem = "push me"
```

--------------------------------

### Lenient Match Example with Failure Output

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/utilities.md

Shows a lenient match using `=~` that checks the list contains at least one instance of each item. The example fails because `4` is missing and `3` is extra, producing the displayed failure output.

```groovy
def x = [2, 2, 1, 3, 3]
assert x =~ [4, 1, 2]
```

```text
x =~ [4, 1, 2]
| |
| false
| 2 differences (66% similarity, 1 missing, 1 extra)
| missing: [4]
| extra: [3]
[2, 1, 3]
```

--------------------------------

### Strict Match Example with Failure Output

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/utilities.md

Shows a strict match using `==~` that requires the collection to contain exactly the specified items in any order. The example fails because the actual list has extra elements, and the failure output is shown.

```groovy
def x = [2, 2, 1, 3, 3]
assert x ==~ [4, 1, 2]
```

```text
x ==~ [4, 1, 2]
| |
| false
[2, 2, 1, 3, 3]

Expected: iterable with items [<4>, <1>, <2>] in any order
     but: not matched: <2>
```

--------------------------------

### Cardinality examples for interactions

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/interaction_based_testing.md

Shows cardinality options for interactions: fixed numbers, ranges, and wildcards. The underscore (_) matches any number of calls including zero.

```groovy
1 * subscriber.receive("hello")      // exactly one call
0 * subscriber.receive("hello")      // zero calls
(1..3) * subscriber.receive("hello") // between one and three calls (inclusive)
(1.._) * subscriber.receive("hello") // at least one call
(_..3) * subscriber.receive("hello") // at most three calls
_ * subscriber.receive("hello")      // any number of calls, including zero
                                     // (rarely needed; see 'Strict Mocking')

```

--------------------------------

### Argument constraint examples in Groovy

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/interaction_based_testing.md

Shows the various argument constraint syntaxes for a single-argument method, including equality, negation, wildcard, spread wildcard, type, Hamcrest, and code constraints. The comment lines explain each constraint's matching behavior.

```groovy
1 * subscriber.receive("hello")        // an argument that is equal to the String "hello"
1 * subscriber.receive(!"hello")       // an argument that is unequal to the String "hello"
1 * subscriber.receive()               // the empty argument list (would never match in our example)
1 * subscriber.receive(_)              // any single argument (including null)
1 * subscriber.receive(*_)             // any argument list (including the empty argument list)
1 * subscriber.receive(!null)          // any non-null argument
1 * subscriber.receive(_ as String)    // any non-null argument that is-a String
1 * subscriber.receive(endsWith("lo")) // an argument matching the given Hamcrest matcher
                                       // a String argument ending with "lo" in this case
1 * subscriber.receive({ it.size() > 3 && it.contains('a') })
// an argument that satisfies the given predicate, meaning that
// code argument constraints need to return true of false
// depending on whether they match or not
// (here: message length is greater than 3 and contains the character a)
```

--------------------------------

### Feature method with inline conditions

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/spock_primer.md

A feature method with inline conditions that verify a purchased PC matches a preferred configuration. This is the starting point before factoring out the conditions into a helper method.

```groovy
def "offered PC matches preferred configuration"() {
  when:
  def pc = shop.buyPc()

  then:
  pc.vendor == "Sunny"
  pc.clockRate >= 2333
  pc.ram >= 4096
  pc.os == "Linux"
}
```

--------------------------------

### @SpringSpy spy an existing bean example

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/module_spring.md

Shows how to use @SpringSpy to spy on an existing bean in the ApplicationContext. The field must be of the type to spy on and cannot have an initializer. The example includes an autowired dependency and verifies both default implementation and stubbed behavior.

```groovy
@SpringSpy
Service2 service2

@Autowired
Service1 service1

def "default implementation is used"() {
  expect:
  service1.generateString() == "The quick brown fox jumps over the lazy dog."
}

def "mocking works was well"() {
  when:
  def result = service1.generateString()

  then:
  result == "Foo"
  1 * service2.generateQuickBrownFox() >> "Foo"
}
```

--------------------------------

### Create Custom Mock Configuration with Named Arguments

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/all_in_one.md

The Mock() factory method accepts named arguments matching properties of IMMockConfiguration. This example creates a mock with default response ZeroOrNullResponse.INSTANCE and verified: false. All properties are immutable, containing only getters.

```groovy
def person = Mock(name: "Fred", type: Person, defaultResponse: ZeroOrNullResponse.INSTANCE, verified: false)

```

--------------------------------

### Example output for a rolled-up feature failure

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/all_in_one.md

Example output when a rolled-up feature fails. The report shows the feature name with FAILED and the condition-not-satisfied details, including the actual values of the variables. This output is illustrative and depends on the execution environment.

```text
maximum of two numbers   FAILED

Condition not satisfied:

Math.max(a, b) == c
|    |   |  |  |  |
|    |   7  4  |  7
|    42        false
class java.lang.Math

```

--------------------------------

### Get mock object details with MockUtil.asMock

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/interaction_based_testing.md

Uses MockUtil.asMock to obtain an IMockObject and verifies its name, type, and nature. This provides more information about a mock object.

```groovy
IMockObject mock = mockUtil.asMock(list2)

expect:
mock.name == "list2"
mock.type == List
mock.nature == MockNature.MOCK
```

--------------------------------

### Report output with @Unroll annotation

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/data_driven_testing.md

Example report output using the @Unroll annotation pattern.

```text
╷
└─ Spock ✔
   └─ PersonSpec ✔
      └─ person age should be calculated properly ✔
         ├─ person age should be calculated properly[0] (Fred is 38 years old) ✔
         ├─ person age should be calculated properly[1] (Wilma is 36 years old) ✔
         └─ person age should be calculated properly[2] (Pebbles is 5 years old) ✔
```

--------------------------------

### Output of @Unroll annotation pattern

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/all_in_one.md

Example output of the @Unroll annotation pattern, showing the reported iteration names with the feature name and index.

```text
╷
└─ Spock ✔
   └─ PersonSpec ✔
      └─ person age should be calculated properly ✔
         ├─ person age should be calculated properly[0] (Fred is 38 years old) ✔
         ├─ person age should be calculated properly[1] (Wilma is 36 years old) ✔
         └─ person age should be calculated properly[2] (Pebbles is 5 years old) ✔

```

--------------------------------

### Unmatched invocations output for TooFewInvocationsError

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/interaction_based_testing.md

Example output showing invocations that did not match any interaction, ordered by similarity. Invocations that match everything but the interaction's arguments are shown first.

```groovy
Unmatched invocations (ordered by similarity):

1 * subscriber.receive("goodbye")
1 * subscriber2.receive("hello")

```

--------------------------------

### Use `HamcrestSupport.expect` for Hamcrest assertions

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/release_notes.md

Uses the new `expect` method from `spock.util.matcher.HamcrestSupport` to write Hamcrest assertions in then-blocks. The example checks that `x` is close to 42 within 0.01.

```groovy
when:
def x = computeValue()

then:
expect x, closeTo(42, 0.01)
```

--------------------------------

### Use @ParameterIndex in fixture and feature methods

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/extensions.md

Shows how to use the @ParameterIndex extension in fixture and feature methods. The extension injects the parameter's index value, so the first parameter gets 0, the second 1, and so on.

```groovy
  def setup(@ParameterIndex int param1) {
    assert param1 == 0
  }

  def "test"(@ParameterIndex int param1, @ParameterIndex Integer param2, @ParameterIndex int param3) {
    expect:
    param1 == 0
    param2 == 1
    param3 == 2
  }
```

--------------------------------

### Multi-Variable Assignment with Data Pipe

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/data_driven_testing.md

Demonstrates multi-variable assignment using standard Groovy multi-assignment syntax. Requires an object Groovy can iterate over, such as a row from a SQL query. The example shows a complete feature method with a @Shared Sql instance.

```groovy
@Shared sql = Sql.newInstance("jdbc:h2:mem:", "org.h2.Driver")

def "maximum of two numbers multi-assignment"() {
  expect:
  Math.max(a, b) == c

  where:
  row << sql.rows("select a, b, c from maxdata")
  (a, b, c) = row
}

```

--------------------------------

### verifyAll method usage in Spock

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/release_notes.md

Use verifyAll to assert multiple boolean expressions without short-circuiting after a failure. This example shows a then block with multiple equality assertions.

```groovy
then:
verifyAll {
  a == b
  b == c
}
```

--------------------------------

### Incompatible Field Initialization in Derived Class

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/migration_guide.md

An example of code that fails in Spock 0.6 due to the change in field initialization order where the base field is not yet set.

```groovy
class Base extends Specification {
    def base

    def setup() { base = "base" }
}

class Derived extends Base {
    def derived = base + "derived" // base is not yet set
}
```

--------------------------------

### Manually attach and detach a mock with mockUtil.attachMock

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/interaction_based_testing.md

Creates a detached Engine mock, attaches it manually with mockUtil.attachMock, stubs isStarted() to return true, injects it into a Car, and detaches it in the cleanup block after verifying start() and stop() interactions.

```groovy
def "Manually attach detached mock"() {
  given:
  def manuallyAttachedEngine = mockFactory.Mock(Engine)
  mockUtil.attachMock(manuallyAttachedEngine, this)
  manuallyAttachedEngine.isStarted() >> true
  def car = new Car(engine: manuallyAttachedEngine)

  when:
  car.drive()

  then:
  1 * manuallyAttachedEngine.start()
  manuallyAttachedEngine.isStarted()

  when:
  car.park()

  then:
  1 * manuallyAttachedEngine.stop()
  manuallyAttachedEngine.isStarted()

  cleanup:
  mockUtil.detachMock(manuallyAttachedEngine)
}
```

--------------------------------

### Matching invocations output for TooManyInvocationsError

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/interaction_based_testing.md

Example output showing all invocations that matched an interaction when a TooManyInvocationsError occurs. Indistinguishable calls are aggregated into a single line, so the first receive("hello") may have occurred before receive("goodbye").

```text
Matching invocations (ordered by last occurrence):

2 * subscriber.receive("hello")   <-- this triggered the error
1 * subscriber.receive("goodbye")

```

--------------------------------

### Output of unrolled feature method

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/all_in_one.md

Example output of an unrolled feature method showing the replaced placeholders and the failure report for the second iteration. The output includes the failing assertion with values and the class name.

```text
maximum of 1 and 3 is 3   PASSED
maximum of 7 and 4 is 7   FAILED

Math.max(a, b) == c
|    |   |  |  |  |
|    |   7  4  |  7
|    42        false
class java.lang.Math

maximum of 0 and 0 is 0   PASSED

```

--------------------------------

### TooFewInvocationsError diagnostic message

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/all_in_one.md

Example diagnostic message for TooFewInvocationsError, showing the expected invocation count, actual invocations, and unmatched invocations ordered by similarity.

```text
Too few invocations for:

1 * person.sing("fa")   (0 invocations)

Unmatched invocations (ordered by similarity):

1 * person.sing("re")
1 * person.say("fa")
1 * person2.shout("mi")
```

--------------------------------

### MathSpec: maximum of two numbers with hard-coded inputs

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/data_driven_testing.md

Initial example showing a feature method that exercises Math.max with a few hard-coded inputs. This approach mixes code and data, making it hard to change independently and to identify which inputs caused a failure.

```groovy
class MathSpec extends Specification {
  def "maximum of two numbers"() {
    expect:
    // exercise math method for a few different inputs
    Math.max(1, 3) == 3
    Math.max(7, 4) == 7
    Math.max(0, 0) == 0
  }
}
```

--------------------------------

### Allow any invocation order with multiple interactions in a single then: block

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/interaction_based_testing.md

Shows the default behavior where Spock allows any invocation order as long as the specified interactions are eventually satisfied. The example specifies two 'hello' calls and one 'goodbye' call, and any sequence of these calls will satisfy the interactions.

```groovy
then:
2 * subscriber.receive("hello")
1 * subscriber.receive("goodbye")
```

--------------------------------

### Create an a la carte mock with custom configuration

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/interaction_based_testing.md

Creates a mock with fine-grained configuration using named arguments that correspond to properties of the org.spockframework.mock.IMockConfiguration interface. The mock uses default return values like a Mock() but does not verify invocations, like a Stub().

```groovy
def person = Mock(name: "Fred", type: Person, defaultResponse: ZeroOrNullResponse.INSTANCE, verified: false)
```

--------------------------------

### Inject temporary directories with @TempDir

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/extensions.md

Shows field and parameter injection of @TempDir in a Spock spec. Field types can be File, Path, def (injects Path), or a custom class with a constructor accepting File or Path. Parameter injection works in setup(), setupSpec(), and feature methods. @Shared fields share the directory across the spec; otherwise each feature and iteration gets its own.

```groovy
// all features will share the same temp directory path1
@TempDir
@Shared
Path path1

// all features and iterations will have their own path2
@TempDir
File path2

// will be injected using java.nio.file.Path
@TempDir
def path3

// use a custom class that accepts java.nio.file.Path as sole constructor parameter
@TempDir
FileSystemFixture path4

// Use for parameter injection of a setupSpec method
def setupSpec(@TempDir Path sharedPath) {
  assert sharedPath instanceof Path
}

// Use for parameter injection of a setup method
def setup(@TempDir Path setupPath) {
  assert setupPath instanceof Path
}

// Use for parameter injection of a feature
def demo(@TempDir Path path5) {
  expect:
  path1 instanceof Path
  path2 instanceof File
  path3 instanceof Path
  path4 instanceof FileSystemFixture
  path5 instanceof Path
}
```

--------------------------------

### Usage: Inject and configure mocks in a specification

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/module_spring.md

Shows how to inject the mocks created in Java or XML config into a Spock specification and configure them with interactions. The example includes tests for mock, stub, spy, and alternative mock beans.

```groovy
@Autowired @Named('serviceMock')
GreeterService serviceMock

@Autowired @Named('serviceStub')
GreeterService serviceStub

@Autowired @Named('serviceSpy')
GreeterService serviceSpy

@Autowired @Named('alternativeMock')
GreeterService alternativeMock

def "mock service"() {
  when:
  def result = serviceMock.greeting

  then:
  result == 'mock me'
  1 * serviceMock.getGreeting() >> 'mock me'
}

def "sub service"() {
  given:
  serviceStub.getGreeting() >> 'stub me'

  expect:
  serviceStub.greeting == 'stub me'
}

def "spy service"() {
  when:
  def result = serviceSpy.greeting

  then:
  result == 'Hello World'
  1 * serviceSpy.getGreeting()
}

def "alternative mock service"() {
  when:
  def result = alternativeMock.greeting

  then:
  result == 'mock me'
  1 * alternativeMock.getGreeting() >> 'mock me'
}
```

--------------------------------

### Tree output without feature name repetition

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/all_in_one.md

Example tree output when 'includeFeatureNameForIterations' is false. Iterations are shown only with data variables and iteration index, omitting the feature name.

```text
╷
└─ Spock ✔
   └─ ASpec ✔
      └─ really long and informative test name that doesn't have to be repeated ✔
         ├─ x: 1, y: a, #0 ✔
         ├─ x: 2, y: b, #1 ✔
         └─ x: 3, y: c, #2 ✔
```

--------------------------------

### Tree output with feature name repetition

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/all_in_one.md

Example tree output when 'includeFeatureNameForIterations' is true (default). Each iteration repeats the full feature name followed by the data variables and iteration index.

```text
╷
└─ Spock ✔
   └─ ASpec ✔
      └─ really long and informative test name that doesn't have to be repeated ✔
         ├─ really long and informative test name that doesn't have to be repeated [x: 1, y: a, #0] ✔
         ├─ really long and informative test name that doesn't have to be repeated [x: 2, y: b, #1] ✔
         └─ really long and informative test name that doesn't have to be repeated [x: 3, y: c, #2] ✔
```

--------------------------------

### Compile error for final variable in cleanup

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/all_in_one.md

Example compiler output when compiling the Broken specification. The error points to the cleanup line and indicates the final variable may be uninitialized.

```text
> Task :compileTestGroovy FAILED
startup failed:
/Users/acme/projects/spock-tests/src/test/groovy/Broken.groovy: 11: The variable [value] may be uninitialized
. At [11:15]  @ line 11, column 15.
           clean value
```

--------------------------------

### Configure @Retry on feature methods

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/extensions.md

Shows various configurations of the @Retry annotation on feature methods: default retry count, custom count, exception filtering, condition closures, mode for setup/cleanup, and delay. The condition closure can inspect the failure message or the instance state. The mode SETUP_FEATURE_CLEANUP also runs setup and cleanup on retries, but only if the feature method fails in the expected way.

```groovy
class FlakyIntegrationSpec extends Specification {
  @Retry
  def "retry 3 times"() {
    expect: true
  }

  @Retry(count = 5)
  def "retry 5 times"() {
    expect: true
  }

  @Retry(exceptions = [IOException])
  def "only retry on IOException"() {
    expect: true
  }

  @Retry(condition = { failure.message.contains('foo') })
  def "only retry if condition on failure holds"() {
    expect: true
  }

  @Retry(condition = { instance.field != null })
  def "only retry if condition on instance holds"() {
    expect: true
  }

  @Retry
  def "retry failing feature methods"() {
    expect: true

    where:
    data << sql.execute('')
  }

  @Retry(mode = Retry.Mode.SETUP_FEATURE_CLEANUP)
  def "retry with setup and cleanup"() {
    expect: true

    where:
    data << sql.execute('')
  }

  @Retry(delay = 1000)
  def "retry after 1000 ms delay"() {
    expect: true
  }
}
```

--------------------------------

### SpockConfig.groovy with fixed(4) parallel setting

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/parallel_execution.md

Example configuration for Spock's parallel execution using the fixed(4) setting, which uses exactly 4 threads. Place this in SpockConfig.groovy to enable parallel execution with a fixed thread pool size.

```groovy
runner {
  parallel {
    enabled true
    fixed(4)
  }
}
```

--------------------------------

### SAME_THREAD specifications with CONCURRENT features Gantt diagram

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/all_in_one.md

Gantt diagram showing `SAME_THREAD` specifications with `CONCURRENT` features. Features within each specification run in parallel, but specifications are serialized; B's tasks start after A's last task ends.

```plantuml
@startgantt
scale 2
[A.test1()] lasts 4 days
[A.test2()] lasts 8 days
[B.test1()] lasts 6 days and starts at [A.test2()]'s end
[B.test2()] lasts 4 days and starts at [A.test2()]'s end
@endgantt
```

--------------------------------

### `verifyEach` with custom namer and its output

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/spock_primer.md

Shows how to provide a custom 'namer' method to `verifyEach` to control how each item is rendered in failure messages. This is useful when the item has no useful `toString()` or when the default rendering is too verbose.

```groovy
def list = [1, 2, 3]
verifyEach(list, { "int($it)" }) { it == 2 }

```

```text
Multiple Failures (2 failures)
	org.spockframework.runtime.SpockAssertionError: Assertions failed for item[0] int(1):
Condition not satisfied:

it == 2
|  |
1  false

	org.spockframework.runtime.SpockAssertionError: Assertions failed for item[2] int(3):
Condition not satisfied:

it == 2
|  |
3  false

```

--------------------------------

### Global Groovy Spy for Static Methods

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/all_in_one.md

Global mocks support mocking and stubbing of static methods in Groovy code. For Java code, use Static Mocks instead. The example stubs a static method to return 42.

```groovy
RealSubscriber anySubscriber = GroovySpy(global: true)

1 * RealSubscriber.someStaticMethod("hello") >> 42

```

--------------------------------

### Write a given-when-then specification

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/spock_primer.md

Write a specification in given-when-then format, as used in Behavior Driven Development. The given: label sets up the initial state, when: performs an action, and then: verifies the outcome. Block descriptions are available to the Spock runtime for enhanced diagnostics and textual reports.

```groovy
given: "an empty bank account"
// ...

when: "the account is credited \$10"
// ...

then: "the account's balance is \$10"
// ...
```

--------------------------------

### Method constraint: exact name and regular expression

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/all_in_one.md

Defines an interaction expecting a call to a method named 'receive' with the argument "hello", and another expecting a call to any method whose name matches the regular expression /r.*e/ (starts with 'r' and ends with 'e').

```groovy
1 * subscriber.receive("hello") // a method named 'receive'
1 * subscriber./r.*e/("hello")  // a method whose name matches the given regular expression
                                // (here: method name starts with 'r' and ends in 'e')
```

--------------------------------

### `verifyEach` with index parameter and its output

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/spock_primer.md

Shows how to use the optional index parameter in the `verifyEach` closure to access the current item's index, useful for comparing against a list of expected values. The output shows the index and the expected value used in the comparison.

```groovy
def list = [1, 2, 3]
def expected = [1, 3, 4]
verifyEach(list) { it, i -> it == expected[i] }

```

```text
Multiple Failures (2 failures)
	org.spockframework.runtime.SpockAssertionError: Assertions failed for item[1] 2:
Condition not satisfied:

it == expected[i]
|  |  |       ||
2  |  |       |1
   |  |       3
   |  [1, 3, 4]
   false

	org.spockframework.runtime.SpockAssertionError: Assertions failed for item[2] 3:
Condition not satisfied:

it == expected[i]
|  |  |       ||
3  |  |       |2
   |  |       4
   |  [1, 3, 4]
   false

```

--------------------------------

### Enable IntelliJ IDEA DSL auto-completion with `with`

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/release_notes.md

Shows how the DSL descriptor enables IntelliJ IDEA to understand `with` blocks and provide auto-completion for properties. Requires IntelliJ IDEA 11.1 or higher.

```groovy
def person = new Person(name: "Fred", age: 42)

expect:
with(person) {
    name == "Fred" // editor understands and auto-completes 'name'
    age == 42      // editor understands and auto-completes 'age'
}
```

--------------------------------

### Create a directory tree with FileSystemFixture

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/utilities.md

Use @TempDir with FileSystemFixture to create a directory structure in an integration test. The create block supports dir, file, and copyFromClasspath methods. Requires the groovy-nio dependency for Groovy Path methods.

```groovy
@TempDir
FileSystemFixture fsFixture

def "FileSystemFixture can create a directory structure"() {
  when:
  fsFixture.create {
    dir('src') {
      dir('main') {
        dir('groovy') {
          file('HelloWorld.java') << 'println "Hello World"'
        }
      }
      dir('test/resources') {
        file('META-INF/MANIFEST.MF') << 'bogus entry'
        copyFromClasspath('/org/spockframework/smoke/extension/SampleFile.txt')
      }
    }
  }

  then:
  Files.isDirectory(fsFixture.resolve('src/main/groovy'))
  Files.isDirectory(fsFixture.resolve('src/test/resources/META-INF'))
  fsFixture.resolve('src/main/groovy/HelloWorld.java').text == 'println "Hello World"'
  fsFixture.resolve('src/test/resources/META-INF/MANIFEST.MF').text == 'bogus entry'
  fsFixture.resolve('src/test/resources/SampleFile.txt').text == 'HelloWorld\n'
}
```

--------------------------------

### Incompatible Hamcrest Method Call

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/migration_guide.md

An example of Hamcrest syntax that no longer works in newer Groovy versions.

```groovy
expect:
object.getAnswer() closeTo(42, 0.001)
```

--------------------------------

### Select byte-buddy mock maker with MockMakers.byteBuddy

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/interaction_based_testing.md

Selects the byte-buddy mock maker for a mocked object by specifying an IMockMakerSettings instance as the mockMaker mock option. The class spock.mock.MockMakers provides constants and methods for the built-in mock makers.

```groovy
def subscriber = Mock(mockMaker: MockMakers.byteBuddy, Subscriber)
```

--------------------------------

### Example of aggregated failure report with @Rollup

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/data_driven_testing.md

When @Rollup is used, the test failure is reported as a single aggregated result rather than per-iteration.

```text
maximum of two numbers   FAILED

Condition not satisfied:

Math.max(a, b) == c
|    |   |  |  |  |
|    |   7  4  |  7
|    42        false
class java.lang.Math
```

--------------------------------

### Exception statistics output

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/extensions.md

Output produced by the ExceptionCounterGlobalExtension when running the example specs. It shows the count of each exception type collected during the test execution.

```text
========================
==Exception statistics==
========================
1x java.lang.IllegalStateException
2x java.lang.IllegalArgumentException
========================
```

--------------------------------

### Example of a failed data-driven test iteration report

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/data_driven_testing.md

This output shows how Spock identifies the specific iteration that failed during a data-driven test execution.

```text
maximum of two numbers [a: 1, b: 3, c: 3, #0]   PASSED
maximum of two numbers [a: 7, b: 4, c: 7, #1]   FAILED

Condition not satisfied:

Math.max(a, b) == c
|    |   |  |  |  |
|    |   7  4  |  7
|    42        false
class java.lang.Math

maximum of two numbers [a: 0, b: 0, c: 0, #2]   PASSED
```

--------------------------------

### Configure tempdir baseDir, keep, and cleanup

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/extensions.md

Configures the Spock configuration file for temporary directories. baseDir sets the parent directory (defaults to system property java.io.tmpdir), keep sets whether to keep directories (defaults to spock.tempDir.keep), and cleanup sets the default cleanup mode (defaults to ALWAYS).

```groovy
tempdir {
  // java.nio.Path object, default null,
  // which means system property "java.io.tmpdir"
  baseDir Paths.get("/tmp")
  // boolean, default is system property "spock.tempDir.keep"
  keep true
  // spock.lang.TempDir.CleanupMode, default ALWAYS
  // allows to set the default cleanup mode to use
  cleanup spock.lang.TempDir.CleanupMode.ON_SUCCESS
}
```

--------------------------------

### Create GroovyMock, GroovyStub, and GroovySpy

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/release_notes.md

Creates Groovy-specific mocks: GroovyMock(Person), GroovyStub(Person), and GroovySpy(Person). These automatically implement GroovyObject and support dynamic methods; when called from Java they behave like regular mocks.

```groovy
def mock = GroovyMock(Person)
def stub = GroovyStub(Person)
def spy = GroovySpy(Person)

```

--------------------------------

### Subscriber interface with receive method

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/interaction_based_testing.md

Defines the Subscriber interface used in the stubbing examples. The receive method returns a String status code.

```groovy
interface Subscriber {
    String receive(String message)
}
```

--------------------------------

### TooManyInvocationsError output

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/interaction_based_testing.md

Example output of a TooManyInvocationsError. This error is detected when an invocation matches more times than allowed. The output shows the interaction and the number of invocations.

```text
Too many invocations for:

2 * subscriber.receive(_) (3 invocations)

```

--------------------------------

### Opt out of condition handling with !!

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/spock_primer.md

Use the !! operator to opt out of condition handling for a top-level expression. This prevents the empty-list falsy failure from the previous example.

```groovy
expect:
!!aList.each { assert it > 0 }
```

--------------------------------

### Create two mock subscribers with Groovy syntax and Mock(Subscriber)

Source: https://github.com/spockframework/spock/blob/gh-pages/docs/2.4/interaction_based_testing.md

Creates two mock instances of the Subscriber type using Spock's Mock() method with an explicit type argument. Mocks have no behavior initially and unexpected method calls are allowed and answered with default values (false, 0, or null).

```groovy
def subscriber = Mock(Subscriber)
def subscriber2 = Mock(Subscriber)
```
Tokens:
Raw