Skip to content

Update some docs still referencing Sputnik and JUnit runner and clarify situation of Jupiter extensions #2322

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Vampire wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Update some docs still referencing Sputnik and JUnit runner and clarify situation of Jupiter extensions #2322

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c1037d2
Update some docs still referencing Sputnik and JUnit runner and clari…
Vampire Mar 15, 2026
0287abe
Review Feedback Vol. 1
Vampire Mar 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 18 additions & 1 deletion docs/extensions.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -786,7 +786,24 @@ tasks.named("test", Test) {

== Third-Party Extensions

You can find a list of third-party extensions in the https://github.com/spockframework/spock/wiki/Third-Party-Extensions[Spock Wiki].
You can find a list with some third-party extensions in the https://github.com/spockframework/spock/wiki/Third-Party-Extensions[Spock Wiki].
Comment thread
Vampire marked this conversation as resolved.
This list is neither maintained nor curated by the Spock maintainers.
It is also not necessarily complete, so you might find further Spock extensions through web searches or other means.
It is a community-driven page where anyone can list Spock extensions they wrote or found.

[NOTE]
--
JUnit Jupiter is a separate test engine also running on JUnit Platform and thus is a sibling of the Spock engine.
Extensions written for JUnit Jupiter do _not_ work in Spock specifications out of the box.
Often terms are mixed up and some extension says it is for JUnit 5+, actually meaning it is for JUnit Jupiter, as there are no generic JUnit Platform extensions.
If you want to use an extension written for JUnit Jupiter, you can check whether the project also provides a Spock extension, if not ask them to also provide a Spock extension, search for an alternative extension that supports Spock, or port the Jupiter extension to being a Spock extension yourself.

There is also at least one 3rd party extension that as of this writing provides a partly functioning integration of JUnit Jupiter extensions within Spock specifications.
This extension though is neither maintained, nor recommended, nor discouraged by the Spock maintainers.
It can eventually make some JUnit Jupiter extensions work within Spock specifications, but it is always preferable to instead use a native Spock extension.
Often porting a JUnit Jupiter extension to also support Spock is not a big effort, so you might strongly consider to request a port by the extension maintainer or contribute a port to its project.
--


== Writing Custom Extensions

Expand Down
4 changes: 2 additions & 2 deletions docs/introduction.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ include::include.adoc[]
image::images/spock-main-logo.png[Spock Logo, align=center, width=20%]

Spock is a testing and specification framework for Java and Groovy applications. What makes it stand out from the crowd
is its beautiful and highly expressive specification language. Thanks to its JUnit runner, Spock is compatible with most
IDEs, build tools, and continuous integration servers. Spock is inspired from https://junit.org/[JUnit],
is its beautiful and highly expressive specification language. Thanks to being a JUnit Platform engine, Spock is compatible
with most IDEs, build tools, and continuous integration servers. Spock is inspired from https://junit.org/[JUnit],
https://www.jmock.org/[jMock], https://rspec.info/[RSpec], https://groovy-lang.org/[Groovy], https://scala-lang.org/[Scala],
https://en.wikipedia.org/wiki/Vulcan_(Star_Trek)[Vulcans], and other fascinating life forms.
2 changes: 1 addition & 1 deletion docs/parallel_execution.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ See <<extensions.adoc#spock-configuration-file, Spock Configuration File>> for g
include::{sourcedir}/parallel/ParallelConfigDoc.groovy[tag=enable]
----

NOTE: JUnit Jupiter also supports https://junit.org/junit5/docs/5.7.0/user-guide/#writing-tests-parallel-execution[parallel execution], both rely on the JUnit Platform implementation, but function independently of each other.
NOTE: JUnit Jupiter also supports https://junit.org/junit5/docs/5.7.0/user-guide/#writing-tests-parallel-execution[parallel execution], both rely on the JUnit Platform implementation, but function independently of each other.
If you enable parallel execution in Spock it won't affect Jupiter and vice versa.
The JUnit Platform executes the test engines (Spock, Jupiter) sequentially, so there should not be any interference between engines.

Expand Down
35 changes: 24 additions & 11 deletions docs/spock_primer.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ To learn more about unit testing, go to https://en.wikipedia.org/wiki/Unit_testi

Let's start with a few definitions: Spock lets you write https://en.wikipedia.org/wiki/Specification_by_example[_specifications_]
that describe expected _features_ (properties, aspects) exhibited by a system of interest. The system of interest could be
anything between a single class and a whole application, and is also called the _system under specification or SUS_.
anything between a single class and a whole application, and is also called the _system under specification_ or _SUS_.
The description of a feature starts from a specific snapshot of the SUS and its collaborators; this snapshot is called the feature's _fixture_.

The following sections walk you through all building blocks of which a Spock specification may be composed. A typical
Expand Down Expand Up @@ -48,9 +48,9 @@ A specification is represented as a Groovy class that extends from `spock.lang.S
usually relates to the system or system operation described by the specification. For example, `CustomerSpec`,
`H264VideoPlayback`, and `ASpaceshipAttackedFromTwoSides` are all reasonable names for a specification.

Class `Specification` contains a number of useful methods for writing specifications. Furthermore it instructs JUnit to
run specification with `Sputnik`, Spock's JUnit runner. Thanks to Sputnik, Spock specifications can be run by most modern
Java IDEs and build tools.
Class `Specification` contains a number of useful methods for writing specifications. Furthermore it marks the specification
as `@Testable`, which instructs tools that only look at the source code - like typically IDEs and similar - that this
class is something that executes tests via a JUnit Platform engine.

== Fields

Expand Down Expand Up @@ -841,20 +841,33 @@ block descriptions are enhanced diagnostic messages, and textual reports that ar

As we have seen, Spock offers lots of functionality for writing specifications. However, there always comes a time
when something else is needed. Therefore, Spock provides an interception-based extension mechanism. Extensions are
activated by annotations called _directives_. Currently, Spock ships with the following directives:
activated by annotations called _directives_. Currently, Spock ships - among others - with the following directives:

[horizontal]
`@Timeout`:: Sets a timeout for execution of a feature or fixture method.

`@Ignore`:: Ignores any feature method carrying this annotation.

`@IgnoreRest`:: Any feature method carrying this annotation will be executed, all others will be ignored. Useful for quickly running just a single method.
`@IgnoreRest`:: Any feature method carrying this annotation will be executed, all others will be ignored. Useful for quickly running just a few features.

`@FailsWith`:: Expects a feature method to complete abruptly. `@FailsWith` has two use cases: First, to document known bugs that cannot
be resolved immediately. Second, to replace exception conditions in certain corner cases where the latter cannot be
used (like specifying the behavior of exception conditions). In all other cases, exception conditions are preferable.

Go to the <<extensions.adoc#extensions,Extensions>> chapter to learn how to implement your own directives and extensions.
Go to the <<extensions.adoc#extensions,Extensions>> chapter to learn how to implement your own directives and extensions, to learn where to find some of the 3rd party extensions, and to learn about all built-in extensions and directives.

[NOTE]
Copy link
Copy Markdown
Member

@leonard84 leonard84 Mar 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why do we include this twice?

Copy link
Copy Markdown
Member Author

@Vampire Vampire Mar 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I feared you'd ask that. :-D

I think it is important information to reduce the amount of issues reported in the style of "this JUnit extension does not work with Spock".

Topic-wise I'd say it more belongs to the 3rd-party extensions section, as it is about 3rd-party "extensions", even though they are no Spock extensions but that is what users can wrongly assume easily and also in the Wiki article they might find a replacement or the bridging-extension.

But I think if a user reads the docs at all, then it is more likely that they read the Spock Primer, at least to start with, so wanted to increase visibility of this admonition by having it there too.

The Extensions chapter in the Spock primer is anyway just an information duplication chapter, as it lists an excerpt of the built-in extensions with short description (and even states or at least implies that those are the only ones built-in). So I thought it might be a good idea to have the note there a second time.

--
JUnit Jupiter is a separate test engine also running on JUnit Platform and thus is a sibling of the Spock engine.
Extensions written for JUnit Jupiter do _not_ work in Spock specifications out of the box.
Often terms are mixed up and some extension says it is for JUnit 5+, actually meaning it is for JUnit Jupiter, as there are no generic JUnit Platform extensions.
If you want to use an extension written for JUnit Jupiter, you can check whether the project also provides a Spock extension, if not ask them to also provide a Spock extension, search for an alternative extension that supports Spock, or port the Jupiter extension to being a Spock extension yourself.

There is also at least one 3rd party extension that as of this writing provides a partly functioning integration of JUnit Jupiter extensions within Spock specifications.
This extension though is neither maintained, nor recommended, nor discouraged by the Spock maintainers.
It can eventually make some JUnit Jupiter extensions work within Spock specifications, but it is always preferable to instead use a native Spock extension.
Often porting a JUnit Jupiter extension to also support Spock is not a big effort, so you might strongly consider to request a port by the extension maintainer or contribute a port to its project.
--

== Comparison to JUnit

Expand All @@ -864,10 +877,10 @@ Although Spock uses a different terminology, many of its concepts and features a
|Spock |JUnit

|Specification |Test class
|`setup()` |`@Before`
|`cleanup()` |`@After`
|`setupSpec()` |`@BeforeClass`
|`cleanupSpec()` |`@AfterClass`
|`setup()` |`@Before` / `@BeforeEach`
|`cleanup()` |`@After` / `@AfterEach`
|`setupSpec()` |`@BeforeClass` / `@BeforeAll`
|`cleanupSpec()` |`@AfterClass` / `@AfterAll`
|Feature |Test
|Feature method |Test method
|Data-driven feature |Theory
Expand Down
Loading