spock.lang

Class Specification

java.lang.Object

org.spockframework.lang.SpecInternals

spock.mock.MockingApi

spock.lang.Specification

All Implemented Interfaces:

MockFactory

@Testable
public abstract class Specification
extends MockingApi

Base class for Spock specifications. All specifications must inherit from this class, either directly or indirectly.

Field Summary

Fields

Modifier and Type	Field and Description
static Object	_ The wildcard symbol.

Constructor Summary

Constructors

Constructor and Description
Specification()

Method Summary

Modifier and Type	Method and Description
void	noExceptionThrown() Specifies that no exception should be thrown, failing with a UnallowedExceptionThrownError otherwise.
void	notThrown(Class<? extends Throwable> type) Specifies that no exception of the given type should be thrown, failing with a UnallowedExceptionThrownError otherwise.
<T> T	old(T expression) Used in a then-block to access an expression's value at the time just before the previous where-block was entered.
<T extends Throwable> T	thrown() Specifies that the preceding when block should throw an exception.
<T extends Throwable> T	thrown(Class<T> type) Specifies that the preceding when block should throw an exception of the given type.
void	verifyAll(Closure closure) All assertions in this block are executed and the errors recorded and reported at the end.
<U> void	verifyAll(Object target, Class<U> type, Closure closure) A combination of with(Object, Class, Closure) and verifyAll(Closure).
<U> void	verifyAll(U target, Closure<?> closure) A combination of with(Object, Closure) and verifyAll(Closure).
<U> void	verifyEach(Iterable<U> things, Closure<?> closure) Performs assertions on each item, collecting up failures instead of stopping at first.
<U> void	verifyEach(Iterable<U> things, Function<? super U,?> namer, Closure<?> closure) Performs assertions on each item, collecting up failures instead of stopping at first.
<U> void	with(Object target, Class<U> type, Closure closure) Same as with(Object, groovy.lang.Closure), except that it also states that the specified target has the specified type, throwing a SpockAssertionError otherwise.
<U> void	with(U target, Closure<?> closure) Sets the specified object as the implicit target of the top-level conditions and/or interactions contained in the specified code block, thereby avoiding the need to repeat the same expression multiple times.

Methods inherited from class spock.mock.MockingApi

GroovyMock, GroovyMock, GroovyMock, GroovyMock, GroovyMock, GroovyMock, GroovyMock, GroovyMock, GroovySpy, GroovySpy, GroovySpy, GroovySpy, GroovySpy, GroovySpy, GroovySpy, GroovySpy, GroovySpy, GroovySpy, GroovyStub, GroovyStub, GroovyStub, GroovyStub, GroovyStub, GroovyStub, GroovyStub, GroovyStub, interaction, Mock, Mock, Mock, Mock, Mock, Mock, Mock, Mock, runWithThreadAwareMocks, Spy, Spy, Spy, Spy, Spy, Spy, Spy, Spy, Spy, Spy, SpyStatic, SpyStatic, Stub, Stub, Stub, Stub, Stub, Stub, Stub, Stub, withActiveThreadAwareMocks

Methods inherited from class org.spockframework.lang.SpecInternals

createMock, createMock, getSpecificationContext

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

_

public static final Object _

The wildcard symbol. Used in several places as a don't care value:

• Mock interactions
Example: 1 * foo.bar(_)
• Data parameterizations
Example: [foo, _] << loadDataFromDb()

Constructor Detail

Specification

public Specification()

Method Detail

thrown

public <T extends Throwable> T thrown()

Specifies that the preceding when block should throw an exception. May only occur as the initializer expression of a typed variable declaration in a then block; the expected exception type is inferred from the variable type.

This form of exception condition is typically used if the thrown exception instance is used in subsequent conditions.

Example:

 when:
 "".charAt(0)

 then:
 IndexOutOfBoundsException e = thrown()
 e.message.contains(...)
 

Returns:

the thrown exception instance

thrown

public <T extends Throwable> T thrown(Class<T> type)

Specifies that the preceding when block should throw an exception of the given type. May only occur in a then block.

This form of exception condition is typically used if the thrown exception instance is not used in subsequent conditions.

Example:

 when:
 "".charAt(0)

 then:
 thrown(IndexOutOfBoundsException)

Type Parameters:

T - the expected exception type

Parameters:

type - the expected exception type

Returns:

the thrown exception instance

notThrown

public void notThrown(Class<? extends Throwable> type)

Specifies that no exception of the given type should be thrown, failing with a UnallowedExceptionThrownError otherwise.

Parameters:

type - the exception type that should not be thrown

noExceptionThrown

public void noExceptionThrown()

Specifies that no exception should be thrown, failing with a UnallowedExceptionThrownError otherwise.

old

public <T> T old(T expression)

Used in a then-block to access an expression's value at the time just before the previous where-block was entered.

Type Parameters:

T - the expression's type

Parameters:

expression - an arbitrary expression, except that it may not reference variables defined in the then-block

Returns:

the expression's value at the time the previous where-block was entered

with

@Beta
public <U> void with(U target,
                           @DelegatesTo(strategy=1)
                           Closure<?> closure)

Sets the specified object as the implicit target of the top-level conditions and/or interactions contained in the specified code block, thereby avoiding the need to repeat the same expression multiple times. Implicit conditions are supported. (In other words, the assert keyword may be omitted.) If the target is null, a SpockAssertionError is thrown.

A with block can be used anywhere in a spec, including nested positions and helper methods.

Condition example:

 def fred = new Person(name: "Fred", age: 42)
 def spaceship = new Spaceship(pilot: fred)

 expect:
 with(spaceship.pilot) {
   name == "Fred" // shorthand for: spaceship.pilot.name == "Fred"
   age == 42
 }
 

Interaction example:

 def service = Mock(Service) // has start(), stop(), and doWork() methods
 def app = new Application(service) // controls the lifecycle of the service

 when:
 app.run()

 then:
 with(service) {
   1 * start() // shorthand for: 1 * service.start()
   1 * doWork()
   1 * stop()
 }
 

Type Parameters:

U - type of target

Parameters:

target - an implicit target for conditions and/or interactions

closure - a code block containing top-level conditions and/or interactions

with

@Beta
public <U> void with(Object target,
                           Class<U> type,
                           @DelegatesTo(genericTypeIndex=0,strategy=1)
                           Closure closure)

Same as with(Object, groovy.lang.Closure), except that it also states that the specified target has the specified type, throwing a SpockAssertionError otherwise. As a side effect, this may give better code completion in IDEs.

Example:

 def fred = new Employee(name: "Fred", age: 42, employer: "MarsTravelUnited")
 def spaceship = new Spaceship(pilot: fred)

 expect:
 with(spaceship.pilot, Employee) {
   name == "Fred" // shorthand for: spaceship.pilot.name == "Fred"
   age == 42
   employer == "MarsTravelUnited"
 }
 

Type Parameters:

U - type of target

Parameters:

target - an implicit target for conditions and/or interactions

type - the expected type of the target

closure - a code block containing top-level conditions and/or interactions

verifyAll

@Beta
public void verifyAll(Closure closure)

All assertions in this block are executed and the errors recorded and reported at the end.

Example:

 expect:
 verifyAll {
   1 == 2
   2 == 3
 }
 

This will report two errors, instead of just the first.

Parameters:

closure - a code block containing top-level conditions and/or interactions

verifyAll

@Beta
public <U> void verifyAll(U target,
                                @DelegatesTo(strategy=1)
                                Closure<?> closure)

A combination of with(Object, Closure) and verifyAll(Closure).

Type Parameters:

U - type of target

Parameters:

target - an implicit target for conditions and/or interactions

closure - a code block containing top-level conditions and/or interactions

Since:

1.2

verifyAll

@Beta
public <U> void verifyAll(Object target,
                                Class<U> type,
                                @DelegatesTo(genericTypeIndex=0,strategy=1)
                                Closure closure)

A combination of with(Object, Class, Closure) and verifyAll(Closure).

Type Parameters:

U - type of target

Parameters:

target - an implicit target for conditions and/or interactions

type - the expected type of the target

closure - a code block containing top-level conditions and/or interactions

Since:

1.2

verifyEach

@Beta
public <U> void verifyEach(Iterable<U> things,
                                 @DelegatesTo(type="U",strategy=1)
                                 Closure<?> closure)

Performs assertions on each item, collecting up failures instead of stopping at first.

Exception messages will contain a toString() of the item to identify it.

The closure can either use one or two parameters. The first parameter will always be the item. The second optional parameter will be the iteration index of the item.

Type Parameters:

U - type of items in things

Parameters:

things - the iterable to inspect

closure - a code block containing top-level conditions

Since:

2.4

verifyEach

@Beta
public <U> void verifyEach(Iterable<U> things,
                                 Function<? super U,?> namer,
                                 @DelegatesTo(type="U",strategy=1)
                                 Closure<?> closure)

Performs assertions on each item, collecting up failures instead of stopping at first.

Exception messages will contain the result of calling the namer for an item to identify it.

The closure can either use one or two parameters. The first parameter will always be the item. The second optional parameter will be the iteration index of the item.

Type Parameters:

U - type of items in things

Parameters:

things - the iterable to inspect

namer - the namer function to use when rendering the exception

closure - a code block containing top-level conditions

Since:

2.4