Spock Framework Reference Documentation

If fixture methods are overridden in a specification subclass then setup() of the superclass will run before setup() of the subclass. cleanup() works in reverse order, that is cleanup() of the subclass will execute before cleanup() of the superclass. setupSpec() and cleanupSpec() behave in the same way. There is no need to explicitly call super.setup() or super.cleanup() as Spock will automatically find and execute fixture methods at all levels in an inheritance hierarchy.

Spock has built-in support for implementing each of the conceptual phases of a feature method. To this end, feature methods are structured into so-called blocks. Blocks start with a label, and extend to the beginning of the next block, or the end of the method. There are six kinds of blocks: given, when, then, expect, cleanup, and where blocks. Any statements between the beginning of the method and the first explicit block belong to an implicit given block.

A feature method must have at least one explicit (i.e. labelled) block - in fact, the presence of an explicit block is what makes a method a feature method. Blocks divide a method into distinct sections, and cannot be nested.

This is the complete list of special tokens:

If none of the three described ways is used to set a custom unroll-pattern, by default the feature name is used, suffixed with all data variable names and their values and finally the iteration index, so the result will be for example my feature [x: 1, y: 2, z: 3, #0].

If there is an error in an unroll expression, for example typo in variable name, exception during evaluation of a property or method in the expression and so on, the test will fail. This is not true for the automatic fall back rendering of the data variables if there is no unroll-pattern set in any way, this will never fail the test, no matter what happens.

The failing of test with errors in the unroll expression can be disabled by setting the configuration file setting validateExpressions in the unroll section to false. If this is done and an error happens, the erroneous expression #foo.bar will be substituted by #Error:foo.bar.

Some reporting frameworks, or IDEs support proper tree based reporting. For these cases it might be desirable to omit the feature name from the iteration reporting.

With includeFeatureNameForIterations true

Let’s take a closer look at the then: block. It contains two interactions, each of which has four distinct parts: a cardinality, a target constraint, a method constraint, and an argument constraint:

The cardinality of an interaction describes how often a method call is expected. It can either be a fixed number or a range:

The target constraint of an interaction describes which mock object is expected to receive the method call:

The method constraint of an interaction describes which method is expected to be called:

When expecting a call to a getter method, Groovy property syntax can be used instead of method syntax:

When expecting a call to a setter method, only method syntax can be used:

The argument constraints of an interaction describe which method arguments are expected:

Argument constraints work as expected for methods with multiple arguments:

When dealing with vararg methods, vararg syntax can also be used in the corresponding interactions:

Sometimes it can be useful to match "anything", in some sense of the word:

Now, when would matching any method call be useful? A good example is strict mocking, a style of mocking where no interactions other than those explicitly declared are allowed:

0 * only makes sense as the last interaction of a then: block or method. Note the use of _ * (any number of calls), which allows any interaction with the auditing component.

So far, we declared all our interactions in a then: block. This often results in a spec that reads naturally. However, it is also permissible to put interactions anywhere before the when: block that is supposed to satisfy them. In particular, this means that interactions can be declared in a setup method. Interactions can also be declared in any "helper" instance method of the same specification class.

When an invocation on a mock object occurs, it is matched against interactions in the interactions' declared order. If an invocation matches multiple interactions, the earliest declared interaction that hasn’t reached its upper invocation limit will win. There is one exception to this rule: Interactions declared in a then: block are matched against before any other interactions. This allows to override interactions declared in, say, a setup method with interactions declared in a then: block.

If a mock has a set of "base" interactions that don’t vary, they can be declared right at mock creation time:

This feature is particularly attractive for Stubbing and with dedicated Stubs. Note that the interactions don’t (and cannot ^[4]) have a target constraint; it’s clear from the context which mock object they belong to.

Interactions can also be declared when initializing an instance field with a mock:

Interactions sharing the same target can be grouped in a Specification.with block. Similar to Declaring Interactions at Mock Creation Time, this makes it unnecessary to repeat the target constraint:

A with block can also be used for grouping conditions with the same target.

A then: block may contain both interactions and conditions. Although not strictly required, it is customary to declare interactions before conditions:

Read out aloud: "When the publisher sends a 'hello' message, then the subscriber should receive the message exactly once, and the publisher’s message count should be one."

Internally, Spock must have full information about expected interactions before they take place. So how is it possible for interactions to be declared in a then: block? The answer is that under the hood, Spock moves interactions declared in a then: block to immediately before the preceding when: block. In most cases this works out just fine, but sometimes it can lead to problems:

Here we have introduced a variable for the expected argument. (Likewise, we could have introduced a variable for the cardinality.) However, Spock isn’t smart enough (huh?) to tell that the interaction is intrinsically linked to the variable declaration. Hence it will just move the interaction, which will cause a MissingPropertyException at runtime.

One way to solve this problem is to move (at least) the variable declaration to before the when: block. (Fans of Data Driven Testing might move the variable into a where: block.) In our example, this would have the added benefit that we could use the same variable for sending the message.

Another solution is to be explicit about the fact that variable declaration and interaction belong together:

Since an MockingApi.interaction block is always moved in its entirety, the code now works as intended.

Interactions declared in a then: block are scoped to the preceding when: block:

This makes sure that subscriber receives "message1" during execution of the first when: block, and "message2" during execution of the second when: block.

Interactions declared outside a then: block are active from their declaration until the end of the containing feature method.

Interactions are always scoped to a particular feature method. Hence they cannot be declared in a static method, setupSpec method, or cleanupSpec method. Likewise, mock objects should not be stored in static or @Shared fields.

There are two main ways in which a mock-based test can fail: An interaction can match more invocations than allowed, or it can match fewer invocations than required. The former case is detected right when the invocation happens, and causes a TooManyInvocationsError:

To make it easier to diagnose why too many invocations matched, Spock will show all invocations matching the interaction in question:

According to this output, one of the receive("hello") calls triggered the TooManyInvocationsError. Note that because indistinguishable calls like the two invocations of subscriber.receive("hello") are aggregated into a single line of output, the first receive("hello") may well have occurred before the receive("goodbye").

The second case (fewer invocations than required) can only be detected once execution of the when block has completed. (Until then, further invocations may still occur.) It causes a TooFewInvocationsError:

Note that it doesn’t matter whether the method was not called at all, the same method was called with different arguments, the same method was called on a different mock object, or a different method was called "instead" of this one; in either case, a TooFewInvocationsError error will occur.

To make it easier to diagnose what happened "instead" of a missing invocation, Spock will show all invocations that didn’t match any interaction, ordered by their similarity with the interaction in question. In particular, invocations that match everything but the interaction’s arguments will be shown first:

Often, the exact method invocation order isn’t relevant and may change over time. To avoid over-specification, Spock defaults to allowing any invocation order, provided that the specified interactions are eventually satisfied:

Here, any of the invocation sequences "hello" "hello" "goodbye", "hello" "goodbye" "hello", and "goodbye" "hello" "hello" will satisfy the specified interactions.

In those cases where invocation order matters, you can impose an order by splitting up interactions into multiple then: blocks:

Now Spock will verify that both "hello"'s are received before the "goodbye". In other words, invocation order is enforced between but not within then: blocks.

Besides interfaces, Spock also supports mocking of classes. Mocking classes works just like mocking interfaces; the only additional requirement is to put byte-buddy 1.9+ or cglib-nodep 3.2.0+ on the class path.

When using for example

it is also necessary to put objenesis 3.0+ on the class path, except for classes with accessible no-arg constructor or configured constructorArgs unless the constructor call should not be done, for example to avoid unwanted side effects.

If either of these libraries is missing from the class path, Spock will gently let you know.

We have already seen the use of the right-shift (>>) operator to return a fixed value:

To return different values for different invocations, use multiple interactions:

This will return "ok" whenever "message1" is received, and "fail" whenever "message2" is received. There is no limit as to which values can be returned, provided they are compatible with the method’s declared return type.

To return different values on successive invocations, use the triple-right-shift (>>>) operator:

This will return "ok" for the first invocation, "error" for the second and third invocation, and "ok" for all remaining invocations. The right-hand side must be a value that Groovy knows how to iterate over; in this example, we’ve used a plain list.

To compute a return value based on the method’s argument, use the the right-shift (>>) operator together with a closure. If the closure declares a single untyped parameter, it gets passed the method’s argument list:

Here "ok" gets returned if the message is more than three characters long, and "fail" otherwise.

In most cases it would be more convenient to have direct access to the method’s arguments. If the closure declares more than one parameter or a single typed parameter, method arguments will be mapped one-by-one to closure parameters:^[5]

This response generator behaves the same as the previous one, but is arguably more readable.

If you find yourself in need of more information about a method invocation than its arguments, have a look at org.spockframework.mock.IMockInvocation. All methods declared in this interface are available inside the closure, without a need to prefix them. (In Groovy terminology, the closure delegates to an instance of IMockInvocation.)

Sometimes you may want to do more than just computing a return value. A typical example is throwing an exception. Again, closures come to the rescue:

Of course, the closure can contain more code, for example a println statement. It will get executed every time an incoming invocation matches the interaction.

Method responses can be chained:

This will return "ok", "fail", "ok" for the first three invocations, throw InternalError for the fourth invocations, and return ok for any further invocation.

If you don’t really care what you return, but you must return a non-null value, you can use _. This will use the same logic to compute a response as Stub (see Stubs), so it is only really useful for Mock and Spy instances.

You can of course use this with chaining as well. Here it might be useful for Stub instances as well.

A stub is created with the MockingApi.Stub factory method:

Whereas a mock can be used both for stubbing and mocking, a stub can only be used for stubbing. Limiting a collaborator to a stub communicates its role to the readers of the specification.

Like a mock, a stub allows unexpected invocations. However, the values returned by a stub in such cases are more ambitious:

A stub often has a fixed set of interactions, which makes declaring interactions at mock creation time particularly attractive:

(Think twice before using this feature. It might be better to change the design of the code under specification.)

A spy is created with the MockingApi.Spy factory method:

A spy is always based on a real object. Hence you must provide a class type rather than an interface type, along with any constructor arguments for the type. If no constructor arguments are provided, the type’s no-arg constructor will be used.

If the given constructor arguments lead to an ambiguity, you can cast the constructor arguments as usual using as or Java-style cast. If the testee for example has one constructor with a String parameter and one with a Pattern parameter and you want null as constructorArg:

You may also create a spy from an instantiated object. This may be useful in cases where you do not have full control over the instantiation of types you are interested in spying. (For example when testing within a Dependency Injection framework such as Spring or Guice.)

Method calls on a spy are automatically delegated to the real object. Likewise, values returned from the real object’s methods are passed back to the caller via the spy.

After creating a spy, you can listen in on the conversation between the caller and the real object underlying the spy:

Apart from making sure that receive gets called exactly once, the conversation between the publisher and the SubscriberImpl instance underlying the spy remains unaltered.

When stubbing a method on a spy, the real method no longer gets called:

Instead of calling SubscriberImpl.receive, the receive method will now simply return "ok".

Sometimes, it is desirable to both execute some code and delegate to the real method:

Here we use callRealMethod() to delegate the method invocation to the real object. Note that we don’t have to pass the message argument along; this is taken care of automatically. callRealMethod() returns the real invocation’s result, but in this example we opted to return our own result instead. If we had wanted to pass a different message to the real method, we could have used callRealMethodWithArgs("changed message").

Please note that while semantically both callRealMethod() and callRealMethodWithArgs(…​) only make sense with spies, technically you can also call these methods on mock or stub objects, kind of turning them into (pseudo) spy objects "through the backdoor". The only precondition is that the mocked/stubbed object actually has a real method implementation, i.e. for interface mocks there must be a default method, for class mocks there must be a (non-abstract) original method.

(Think twice before using this feature. It might be better to change the design of the code under specification.)

Spies can also be used as partial mocks:

All Groovy mocks implement the GroovyObject interface. They support the mocking and stubbing of dynamic methods as if they were physically declared methods:

(Think twice before using this feature. It might be better to change the design of the code under specification.)

Usually, Groovy mocks need to be injected into the code under specification just like regular mocks. However, when a Groovy mock is created as global, it automagically replaces all real instances of the mocked type for the duration of the feature method:^[6]

Here, we set up the publisher with two instances of a real subscriber implementation. Then we create a global mock of the same type. This reroutes all method calls on the real subscribers to the mock object. The mock object’s instance isn’t ever passed to the publisher; it is only used to describe the interaction.

Since global mocks have a somewhat, well, global effect, it’s often convenient to use them together with GroovySpy. This leads to the real code getting executed unless an interaction matches, allowing you to selectively listen in on objects and change their behavior just where needed.

(Think twice before using this feature. It might be better to change the design of the code under specification.)

Global mocks support mocking of constructors:

Since we are using a spy, the object returned from the constructor call remains unchanged. To change which object gets constructed, we can stub the constructor:

Now, whenever some code tries to construct a subscriber named Fred, we’ll construct a subscriber named Barney instead.

(Think twice before using this feature. It might be better to change the design of the code under specification.)

Global mocks support mocking and stubbing of static methods:

The same works for dynamic static methods.

When a global mock is used solely for mocking constructors and static methods, the mock’s instance isn’t really needed. In such a case one can just write:

At the end of the day, the Mock(), Stub(), and Spy() factory methods are just canned ways to create mock objects with a certain configuration. If you want more fine-grained control over a mock’s configuration, have a look at the org.spockframework.mock.IMockConfiguration interface. All properties of this interface ^[7] can be passed as named arguments to the Mock() method. For example:

Here, we create a mock whose default return values match those of a Mock(), but whose invocations aren’t verified (as for a Stub()). Instead of passing ZeroOrNullResponse, we could have supplied our own custom org.spockframework.mock.IDefaultResponse for responding to unexpected method invocations.

To find out whether a particular object is a Spock mock object, use a org.spockframework.mock.MockUtil:

An util can also be used to get more information about a mock object:

You can configure Spock whether it should filter stack traces or not by using the configuration file. The default value is true.

See the Parallel Execution section for a detailed description.

To temporarily prevent a feature method from getting executed, annotate it with spock.lang.Ignore:

For documentation purposes, a reason can be provided:

To ignore a whole specification, annotate its class:

In most execution environments, ignored feature methods and specs will be reported as "skipped".

By default, @Ignore will only affect the annotated specification, by setting inherited to true you can configure it to apply to sub-specifications as well:

Care should be taken when ignoring feature methods in a spec class annotated with spock.lang.Stepwise since later feature methods may depend on earlier feature methods having executed.

To ignore all but a (typically) small subset of methods, annotate the latter with spock.lang.IgnoreRest:

@IgnoreRest is especially handy in execution environments that don’t provide an (easy) way to run a subset of methods.

Care should be taken when ignoring feature methods in a spec class annotated with spock.lang.Stepwise since later feature methods may depend on earlier feature methods having executed.

To ignore a feature method or specification under certain conditions, annotate it with spock.lang.IgnoreIf, followed by a predicate and an optional reason:

To execute a feature method under certain conditions, annotate it with spock.lang.Requires, followed by a predicate:

Requires works exactly like IgnoreIf, except that the predicate is inverted. In general, it is preferable to state the conditions under which a method gets executed, rather than the conditions under which it gets ignored.

If multiple @Requires annotations are present, they are effectively combined with a logical "and". The annotated element is skipped if any of the conditions evaluates to false:

To indicate that the feature is not fully implemented yet and should not be reported as error, annotate it with spock.lang.PendingFeature.

The use case is to annotate tests that can not yet run but should already be committed. The main difference to Ignore is that the test are executed, but test failures are ignored. If the test passes without an error, then it will be reported as failure since the PendingFeature annotation should be removed. This way the tests will become part of the normal tests instead of being ignored forever.

Groovy has the groovy.transform.NotYetImplemented annotation which is similar but behaves a differently.

PendingFeature:

To conditionally indicate that a feature is not fully implemented, and should not be reported as an error you can annotate it as spock.lang.PendingFeatureIf and include a precondition similar to IgnoreIf or Requires

If the conditional expression passes it behaves the same way as PendingFeature, otherwise it does nothing.

For instance, annotating a feature as @PendingFeatureIf({ false }) effectively does nothing, but annotating it as @PendingFeatureIf({ true }) behaves the same was as if it was marked as @PendingFeature

If applied to a data driven feature, the closure can also access the data variables. If the closure does not reference any actual data variables, the whole feature is deemed pending and only if all iterations become successful will be marked as failing. But if the closure actually does reference valid data variables, the individual iterations where the condition holds are deemed pending and each will individually fail as soon as it would be successful without this annotation.

It is also supported to have multiple @PendingFeatureIf annotations or a mixture of @PendingFeatureIf and @PendingFeature, for example to ignore certain exceptions only under certain conditions.

To execute features in the order that they are declared, annotate a spec class with spock.lang.Stepwise:

Stepwise only affects the class carrying the annotation; not sub or super classes. Features after the first failure are skipped.

Stepwise does not override the behaviour of annotations such as Ignore, IgnoreRest, and IgnoreIf, so care should be taken when ignoring feature methods in spec classes annotated with Stepwise.

To fail a feature method, fixture, or class that exceeds a given execution duration, use spock.lang.Timeout, followed by a duration, and optionally a time unit. The default time unit is seconds.

When applied to a feature method, the timeout is per execution of one iteration, excluding time spent in fixture methods:

Applying Timeout to a spec class has the same effect as applying it to each feature that is not already annotated with Timeout, excluding time spent in fixtures:

When applied to a fixture method, the timeout is per execution of the fixture method.

When a timeout is reported to the user, the stack trace shown reflects the execution stack of the test framework when the timeout was exceeded.

The @Retry extensions can be used for flaky integration tests, where remote systems can fail sometimes. By default it retries an iteration 3 times with 0 delay if either an Exception or AssertionError has been thrown, all this is configurable. In addition, an optional condition closure can be used to determine if a feature should be retried. It also provides special support for data driven features, offering to either retry all iterations or just the failing ones.

Retries can also be applied to spec classes which has the same effect as applying it to each feature method that isn’t already annotated with {@code Retry}.

A {@code @Retry} annotation that is declared on a spec class is applied to all features in all subclasses as well, unless a subclass declares its own annotation. If so, the retries defined in the subclass are applied to all feature methods declared in the subclass as well as inherited ones.

Given the following example, running FooIntegrationSpec will execute both inherited and foo with one retry. Running BarIntegrationSpec will execute inherited and bar with two retries.

Check RetryFeatureExtensionSpec for more examples.

To activate one or more Groovy categories within the scope of a feature method or spec, use spock.util.mop.Use:

This can be useful for stubbing of dynamic methods, which are usually provided by the runtime environment (e.g. Grails). It has no effect when applied to a helper method. However, when applied to a spec class, it will also affect its helper methods.

To use multiple categories, you can either give multiple categories to the value attribute of the annotation or you can apply the annotation multiple times to the same target.

To confine meta class changes to the scope of a feature method or spec class, use spock.util.mop.ConfineMetaClassChanges:

When applied to a spec class, the meta classes are restored to the state that they were in before setupSpec was executed, after cleanupSpec is executed.

When applied to a feature method, the meta classes are restored to as they were after setup was executed, before cleanup is executed.

To confine meta class changes for multiple classes, you can either give multiple classes to the value attribute of the annotation or you can apply the annotation multiple times to the same target.

Saves system properties before the annotated feature method (including any setup and cleanup methods) gets run, and restores them afterwards.

Applying this annotation to a spec class has the same effect as applying it to all its feature methods.

Automatically attaches a detached mock to the current Specification. Use this if there is no direct framework support available. Spring and Guice dependency injection is automatically handled by the Spring Module and Guice Module respectively.

Automatically clean up a field or property at the end of its lifetime by using spock.lang.AutoCleanup.

By default, an object is cleaned up by invoking its parameterless close() method. If some other method should be called instead, override the annotation’s value attribute:

If multiple fields or properties are annotated with AutoCleanup, their objects are cleaned up sequentially, in reverse field/property declaration order, starting from the most derived class class and walking up the inheritance chain.

If a cleanup operation fails with an exception, the exception is reported by default, and cleanup proceeds with the next annotated object. To prevent cleanup exceptions from being reported, override the annotation’s quiet attribute:

In order to generate a temporary directory for test and delete it after test, annotate a member field of type java.io.File, java.nio.file.Path or untyped using def in a spec class (def will inject a Path). If the annotated field is @Shared, the temporary directory will be shared in the corresponding specification, otherwise every feature method and every iteration per parametrized feature method will have their own temporary directories:

If you want to customize the parent directory for temporary directories, you can use the Spock Configuration File.

If keep is set to true, Spock will not delete temporary directories after tests. The default value is taken from system property spock.tempDir.keep or false, if undefined.

To attach a natural-language name to a spec, use spock.lang.Title:

Similarly, to attach a natural-language description to a spec, use spock.lang.Narrative:

To link to one or more references to external information related to a specification or feature, use spock.lang.See:

To indicate that a feature or spec relates to one or more issues in an external tracking system, use spock.lang.Issue:

If you have a common prefix URL for all issues in a project, you can use the Spock Configuration File to set it up for all at once. If it is set, it is prepended to the value of the @Issue annotation when building the URL.

If the issueNamePrefix is set, it is prepended to the value of the @Issue annotation when building the name for the issue.

To indicate one or more subjects of a spec, use spock.lang.Subject:

You can also use multiple @Subject annotations:

Additionally, Subject can be applied to fields and local variables:

Subject currently has only informational purposes.

Spock understands @org.junit.Rule annotations on non-@Shared instance fields when the JUnit 4 module is included. The according rules are run at the iteration interception point in the Spock lifecycle. This means that the rules before-actions are done before the execution of setup methods and the after-actions are done after the execution of cleanup methods.

Spock understands @org.junit.ClassRule annotations on @Shared fields when the JUnit 4 module is included. The according rules are run at the specification interception point in the Spock lifecycle. This means that the rules before-actions are done before the execution of setupSpec methods and the after-actions are done after the execution of cleanupSpec methods.

Spock is capable of including and excluding specifications according to their classes, super-classes and interfaces and according to annotations that are applied to the specification. Spock is also capable of including and excluding individual features according to annotations that are applied to the feature method. The configuration for what to include or exclude is done according to the Spock Configuration File section.

Spock can remember which features last failed and how often successively and also how long a feature needed to be tested. For successive runs Spock will then first run features that failed at last run and first features that failed more often successively. Within the previously failed or non-failed features Spock will run the fastest tests first. This behaviour can be enabled according to the Spock Configuration File section. The default value is false.

To create a global extension you need to create a class that implements the interface IGlobalExtension and put its fully-qualified class name in a file META-INF/services/org.spockframework.runtime.extension.IGlobalExtension in the class path. As soon as these two conditions are satisfied, the extension is automatically loaded and used when Spock is running.

IGlobalExtension has the following three methods:

To create an annotation driven local extension you need to create a class implementing the interface IAnnotationDrivenExtension. As type argument to the interface you need to supply an annotation class having @Retention set to RUNTIME, @Target set to one or more of FIELD, METHOD, and TYPE - depending on where you want your annotation to be applicable - and @ExtensionAnnotation applied, with the IAnnotationDrivenExtension class as argument. Of course the annotation class can have some attributes with which the user can further configure the behaviour of the extension for each annotation application.

Your annotation can be applied to a specification, a feature method, a fixture method or a field. On all other places like helper methods or other places if the @Target is set accordingly, the annotation will be ignored and has no effect other than being visible in the source code, except you check its existence in other places yourself.

Since Spock 2.0 your annotation can also be defined as @Repeatable and applied multiple times to the same target. IAnnotationDrivenExtension has visit…​Annotations methods that are called by Spock with all annotations of the extension applied to the same target. Their default implementations will then call the respective singular visit…​Annotation method once for each annotation. If you want a repeatable annotation that is compatible with Spock before 2.0 you need to make the container annotation an extension annotation itself and handle all cases accordingly, but you need to make sure to only handle the container annotation if Spock version is before 2.0, or your annotations might be handled twice. Be aware that the repeatable annotation can be attached to the target directly, inside the container annotation or even both if the user added the container annotation manually and also attached one annotation directly.

IAnnotationDrivenExtension has the following nine methods, where in each you can prepare a specification with your extension magic, like attaching interceptors to various interception points as described in the chapter Interceptors:

You can add own sections in the Spock Configuration File for your extension by creating POJOs or POGOs that are annotated with @ConfigurationObject and have a default constructor (either implicitly or explicitly). The argument to the annotation is the name of the top-level section that is added to the Spock configuration file syntax. The default values for the configuration options are defined in the class by initializing the fields at declaration time or in the constructor. In the Spock configuration file those values can then be edited by the user of your extension.

To use the values of the configuration object in your extension, you can either use constructor injection or field injection.

Spock will then automatically create exactly one instance of the configuration object per Spock run, apply the settings from the configuration file to it (before the start() methods of global extensions are called) and inject that instance into the extension class instances.

If a configuration object should be used exclusively in an annotation driven local extension you must register it in META-INF/services/spock.config.ConfigurationObject. This is similar to a global extension, put the fully-qualified class name of the annotated class on a new line in the file. This will cause the configuration object to properly get initialized and populated with the settings from the configuration file. However, if the configuration object is used in a global extension, you can also use it just fine in an annotation driven local extension. If the configuration object is only used in an annotation driven local extension, you will get an exception when then configuration object is to be injected into the extension, and you will also get an error when the configuration file is evaluated, and it contains the section, as the configuration object is not properly registered yet.

For applying the magic of your extension, there are various interception points, where you can attach interceptors from the extension methods described above to hook into the Spock lifecycle. For each interception point there can of course be multiple interceptors added by arbitrary Spock extensions (shipped or 3rd party). Their order currently depends on the order they are added, but there should not be made any order assumptions within one interception point.

An ellipsis in the figure means that the block before it can be repeated an arbitrary amount of times.

The …​ method interceptors are of course only run if there are actual methods of this type to be executed (the white boxes) and those can inject parameters to be given to the method that will be run.

The difference between shared initializer interceptor and shared initializer method interceptor and between initializer interceptor and initializer method interceptor - as there can be at most one of those methods each - is, that there are only the two methods if there are @Shared, respectively non-@Shared, fields that get values assigned at declaration time. The compiler will put those initializations in a generated method and call it at the proper place in the lifecycle. So if there are no such initializations, no method is generated and thus the method interceptor is never called. The non-method interceptors are always called at the proper place in the lifecycle to do work that has to be done at that time.

To create an interceptor to be attached to an interception point, you need to create a class that implements the interface IMethodInterceptor. This interface has the sole method intercept(IMethodInvocation invocation). The invocation parameter can be used to get and modify the current state of execution. Each interceptor must call the method invocation.proceed(), which will go on in the lifecycle, except you really want to prevent further execution of the nested elements like shown in the figure above. But this should be a very rare use case.

If you write an interceptor that can be used at different interception points and should do different work at different interception points, there is also the convenience class AbstractMethodInterceptor, which you can extend and which provides various methods for overriding that are called for the various interception points. Most of these methods have a double meaning, like interceptSetupMethod which is called for the setup interceptor and the setup method interceptor. If you attach your interceptor to both of them and need a differentiation, you can check for invocation.method.reflection, which will be set in the method interceptor case and null otherwise. Alternatively you can of course build two different interceptors or add a parameter to your interceptor and create two instances, telling each at addition time whether it is attached to the method interceptor or the other one.

There are many more ways to modify MutableClock just have a look at the JavaDocs, or the test code spock.util.time.MutableClockSpec.

Figure 7 shows the default case when parallel execution is disabled (runner.parallel.enabled=false) or when both specifications (defaultSpecificationExecutionMode) and features (defaultExecutionMode) are set to SAME_THREAD.

Figure 8 shows the result of setting defaultSpecificationExecutionMode=CONCURRENT and defaultExecutionMode=SAME_THREAD, the specifications will run concurrently but all features will run in the same thread as their specification.

Figure 9 shows the result of setting defaultSpecificationExecutionMode=SAME_THREAD and defaultExecutionMode=CONCURRENT, the specifications will run in the same thread, causing them to run one after the other. The features inside a specification will run concurrently.

Figure 10 shows the result of setting defaultSpecificationExecutionMode=CONCURRENT and defaultExecutionMode=CONCURRENT, both specifications and features will run concurrently.

If a parent node has a READ_WRITE lock, it forces its children to run in the same thread. As READ_WRITE locks cause serialized execution anyway, this is effectively not different from what would happen if the lock would be applied to every child directly. However, if the parent node has only READ locks, then it allows parallel execution of its children.

To avoid deadlocks, Spock pulls up locks to the specification, when locks are defined on both the specification and features. The Specification will then contain all defined locks. If the features both had READ_WRITE and READ locks for the same resource, then the READ will be merged into the READ_WRITE.

Sometimes, you want to modify and test something that affects every other feature, you could put a READ @ResourceLock on every feature, but that is impractical. The @Isolated extension enforces, that only this feature runs without any other features running at the same time. You can think of this as an implicit global lock.

As with other locks, the features in an @Isolated specification will run in SAME_THREAD mode. @Isolated can only be applied at the specification level so if you have a large specification and only need it for a few features, you might want to consider splitting the spec into @Isolated and non isolated.

Spock 1.1 introduced the DetachedMockFactory and the SpockMockFactoryBean which allow the creation of Spock mocks outside of a specification.

Spock ignores bean that is not a singleton (in the singleton scope) by default. To enable mocks to work for scoped beans you need to add @ScanScopedBeans to the spec and make sure that the scope allows access to the bean during the setup phase.

You can limit the scanning to certain scopes by using the value property of @ScanScopedBeans.

Due to certain limitations, injection into shared fields is not enabled by default but can be opted-in to. Refer to javadoc of org.spockframework.spring.EnableSharedInjection for further information.

Thanks to all the contributors to this release: Marc Philipp, Miles Thomason, BJ Hargrave, Marcin Zajączkowski, Lőrinc Pap, Felipe Pedrosa, Marcin Świerczyński, Benedikt Ritter

... and many more, read the full release notes for every detail.

The Migration Guide 1.x - 2.0 covers the major breaking changes between 1.3 and 2.0

Thanks to all the contributors (all 2.0 Milestones): Björn Kautler, Marcin Zajączkowski, DQYuan, Marcin Erdmann, Alexander Kriegisch, Jasper Vandemalle, Tom Wieczorek, Josh Soref, Vaidotas Valuckas, Raymond Augé, Roman Tretiak, Camilo Jorquera, Shil Sinha, Ryan Gardner, k3v1n0x90

Special thanks goes to Marc Philipp who helped a lot with the integration of the JUnit Platform.

Thanks to all the contributors to this release: Marcin Erdmann, Björn Kautler, Alexander Kriegisch, Josh Soref, Vaidotas Valuckas

Thanks to all the contributors to this release: Björn Kautler, Marcin Zajączkowski, Raymond Augé, Roman Tretiak, Camilo Jorquera, Shil Sinha

The main feature of this milestone is support for Groovy 3. To use Spock in your Groovy 3 project just select the spock-\*-2.0-M2 artifact(s) ending with -groovy-3.0.