Update documentation

leonard84 · Dec 13, 2023 · 002947d · 002947d
1 parent 83ac527
commit 002947d
Show file tree

Hide file tree

Showing 3 changed files with 15 additions and 0 deletions.
diff --git a/docs/interaction_based_testing.adoc b/docs/interaction_based_testing.adoc
@@ -952,6 +952,8 @@ it is only used to describe the interaction.
 NOTE: A global mock can only be created for a class type. It effectively replaces
 all instances of that type for the duration from mock creation up until the end of the feature method.
 
+CAUTION: Using global mocks for standard types from the JDK, for example `ArrayList`, is a bad idea and can lead to unforeseen and widespread consequences.
+
 CAUTION: The declaration order of global mocks is relevant.
          The `GroovySpy(global:true, <type>)` must come before all creations of new mocked/spied objects of `<type>`.
          The global spies will only take effect on objects of that type, if the `GroovySpy(global:true, <type>)` was
@@ -983,6 +985,15 @@ When `Specifications` or `Features` are executed concurrently you have to make s
 global mocks on the same types are properly guarded against each other, because a global mock changes the global state
 for the mocked `Class` during execution.
 
+[[global-mocks-parallel-execution]]
+==== Global mocks and parallel execution
+
+Creating a global `GroovyMock`/`GroovyStub`/`GroovySpy` when <<parallel-execution.adoc#parallel-execution,parallel execution>> is enabled,
+requires that the spec is annotated with <<parallel-execution.adoc#isolated-execution, @Isolated>> or `@@ResourceLock(org.spockframework.runtime.model.parallel.Resources.META_CLASS_REGISTRY)`.
+If it is only used for a feature, then it suffices that the feature is annotated with `@ResourceLock(org.spockframework.runtime.model.parallel.Resources.META_CLASS_REGISTRY)`.
+The rule of thumb to choose between `@ResourceLock` and `@Isolated`, is to look at how widespread the mocked type is used.
+If it is widely used, then `@Isolated` is the safe choice, otherwise `@ResourceLock` may be sufficient.
+
 .How Are Global Groovy Mocks Implemented?
 ****
 Global Groovy mocks get their super powers from Groovy meta-programming. To be more precise,

diff --git a/docs/parallel_execution.adoc b/docs/parallel_execution.adoc
@@ -643,6 +643,7 @@ skinparam shadowing false
 @endwbs
 ....
 
+[[isolated-execution]]
 === Isolated Execution
 
 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.

diff --git a/docs/release_notes.adoc b/docs/release_notes.adoc
@@ -8,6 +8,9 @@ include::include.adoc[]
 === Breaking Changes
 
 * Calling `old(...)` with multiple arguments is now a compilation error. Previously the additional arguments were simply ignored.
+* Creating `GroovyMock`/`GroovyStub`/`GroovySpy` for an already mocked type will now fail.
+* Creating a global `GroovyMock`/`GroovyStub`/`GroovySpy` when <<parallel-execution.adoc#parallel-execution, parallel execution>> is enabled,
+  will now require that the spec is annotated with <<parallel-execution.adoc#isolated-execution, @Isolated>> or `@@ResourceLock(org.spockframework.runtime.model.parallel.Resources.META_CLASS_REGISTRY)`. See <<interaction-based-testing.adoc#global-mocks-parallel-execution, Global mocks and parallel execution>>
 
 == 2.4-M1 (2022-11-30)