From 002947d57e62031e2e0ec759f7f30f9a1babfe87 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Leonard=20Br=C3=BCnings?= Date: Wed, 13 Dec 2023 18:15:27 +0100 Subject: [PATCH] Update documentation --- docs/interaction_based_testing.adoc | 11 +++++++++++ docs/parallel_execution.adoc | 1 + docs/release_notes.adoc | 3 +++ 3 files changed, 15 insertions(+) diff --git a/docs/interaction_based_testing.adoc b/docs/interaction_based_testing.adoc index 0cd6956152..e3a5d10e16 100644 --- 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, )` must come before all creations of new mocked/spied objects of ``. The global spies will only take effect on objects of that type, if the `GroovySpy(global:true, )` 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 <> is enabled, +requires that the spec is annotated with <> 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 index a927155b41..e632812874 100644 --- 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 index f3aaa0c409..80aa1334fc 100644 --- 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 <> is enabled, + will now require that the spec is annotated with <> or `@@ResourceLock(org.spockframework.runtime.model.parallel.Resources.META_CLASS_REGISTRY)`. See <> == 2.4-M1 (2022-11-30)