Repository: micronaut-projects/micronaut-test
Pull request #866 (2023-10-13 08:59:22)

doc: split documentation into sections
This PR splits documentation into sections. It shows documentation sections in the left menu. Moreover, it allows quickly grabbing a URL pointing to a particular section of the Micronaut Test documentation.


Patch:
diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml
index 0073fcd3..3a1663bd 100644
--- a/gradle/libs.versions.toml
+++ b/gradle/libs.versions.toml
@@ -7,7 +7,7 @@ groovy = "4.0.11"
 managed-assertj = "3.24.2"
 managed-hamcrest = "2.2"
 managed-mockito = "5.6.0"
-managed-mockk = "1.13.7"
+managed-mockk = "1.13.8"
 managed-junit = "5.10.0"
 managed-rest-assured = "5.3.2"
 managed-kotest = "5.7.2"
@@ -16,12 +16,12 @@ managed-spock = "2.3-groovy-4.0"
 kotlin = "1.9.10"
 graal-svm = "23.1.0"
 
-micronaut-data = "4.1.3"
+micronaut-data = "4.1.4"
 micronaut-hibernate-validator = "4.0.2"
 micronaut-serde = "2.2.6"
 micronaut-spring = "5.0.2"
 micronaut-sql = "5.0.3"
-micronaut-reactor = "3.0.2"
+micronaut-reactor = "3.0.3"
 
 micronaut-gradle-plugin = "4.1.1"
 
diff --git a/src/main/docs/guide/junit5.adoc b/src/main/docs/guide/junit5.adoc
index 7a4991fa..e69de29b 100644
--- a/src/main/docs/guide/junit5.adoc
+++ b/src/main/docs/guide/junit5.adoc
@@ -1,199 +0,0 @@
-=== Setting up JUnit 5
-
-To get started using JUnit 5 you need the following dependencies in your build configuration:
-
-.build.gradle
-[source,groovy,subs="attributes"]
-----
-dependencies {
-    testAnnotationProcessor "io.micronaut:micronaut-inject-java"
-    ...
-    testImplementation("org.junit.jupiter:junit-jupiter-api")
-    testImplementation("io.micronaut.test:micronaut-test-junit5")
-    testRuntimeOnly("org.junit.jupiter:junit-jupiter-engine")
-    testImplementation("org.junit.jupiter:junit-jupiter-engine")
-}
-
-// use JUnit 5 platform
-test {
-    useJUnitPlatform()
-}
-----
-
-NOTE: If you plan to define mock beans you will also need `inject-groovy` on your `testCompile` classpath or `inject-java` for Java or Kotlin (this should already be configured if you used `mn create-app`) and the `testAnnotationProcessor`.
-
-Or for Maven:
-
-.pom.xml
-[source,xml]
-----
-<dependency>
-    <groupId>io.micronaut.test</groupId>
-    <artifactId>micronaut-test-junit5</artifactId>
-    <scope>test</scope>
-</dependency>
-----
-
-=== Writing a Micronaut Test with JUnit 5
-
-Let's take a look at an example using JUnit 5. Consider you have the following interface:
-
-.The MathService Interface
-[source,java]
-----
-include::{junit5tests}/MathService.java[]
-----
-
-And a simple implementation that computes the value times 4 and is defined as Micronaut bean:
-
-.The MathService implementation
-[source,java]
-----
-include::{junit5tests}/MathServiceImpl.java[]
-----
-
-You can define the following test to test the implementation:
-
-.The MathService specification
-[source,groovy]
-----
-include::{junit5tests}/MathServiceTest.java[]
-----
-
-<1> The test is declared as Micronaut test with `@MicronautTest`
-<2> The `@Inject` annotation is used to inject the bean
-<3> The test itself tests the injected bean
-
-
-=== Environments, Classpath Scanning etc.
-
-include::src/main/docs/guide/includes/environments-classpath-scanning.adoc[]
-
-=== Transaction semantics
-
-include::src/main/docs/guide/includes/transaction.adoc[]
-
-=== Using Mockito Mocks
-
-Now let's say you want to replace the implementation with a Mockito Mock. You can do so by defining a method that returns a mock and is annotated with `@MockBean`, for example:
-
-.The MathService specification
-[source,java]
-----
-include::{junit5tests}/MathMockServiceTest.java[]
-----
-
-<1> The `@MockBean` annotation is used to indicate the method returns a mock bean. The value to the method is the type being replaced.
-<2> Mockito's `mock(..)` method creates the actual mock
-<3> The Mock is injected into the test
-<4> Mockito is used to verify the mock is called
-
-Note that because the bean is an inner class of the test, it will be active only for the scope of the test. This approach allows you to define beans that are isolated per test class.
-
-=== Mocking Collaborators
-
-Note that in most cases you won't define a `@MockBean` and then inject it only to verify interaction with the Mock directly, instead the Mock will be a collaborator within your application. For example say you have a `MathController`:
-
-.The MathController
-[source,java]
-----
-include::{junit5tests}/MathController.java[]
-----
-
-The above controller uses the `MathService` to expose a `/math/compute/{number}` endpoint. See the following example for a test that tests interaction with the mock collaborator:
-
-.Mocking Collaborators
-[source,java]
-----
-include::{junit5tests}/MathCollaboratorTest.java[]
-----
-
-<1> Like the previous example a Mock is defined using `@MockBean`
-<2> This time we inject an instance of `HttpClient` to test the controller.
-<3> We invoke the controller and retrieve the result
-<4> The interaction with mock collaborator is verified.
-
-The way this works is that `@MicronautTest` will inject the `Mock(..)` instance into the test, but the controller will have a proxy that points to the `Mock(..)` instance injected. For each iteration of the test the mock is refreshed (in fact it uses Micronaut's built in `RefreshScope`).
-
-For Factory injected beans, you can use Factory Replacement to inject Mocks. Refer to the https://docs.micronaut.io/latest/guide/index.html#_factory_replacement[factory replacement documentation] for more information.
-
-=== Using `@Requires` on Tests
-
-Since `@MicronautTest` turns tests into beans themselves, it means you can use the `@Requires` annotation on the test to enable/disable tests. For example:
-
-[source,java]
-----
-@MicronautTest
-@Requires(env = "my-env")
-class RequiresTest {
-    ...
-}
-----
-
-The above test will only run if `my-env` is active (you can activate it by passing the system property `micronaut.environments`).
-
-=== Defining Additional Test Specific Properties
-
-You can define additional test specific properties using the `@Property` annotation. The following example demonstrates usage:
-
-.Using `@Property`
-[source,java]
-----
-include::{junit5tests}/PropertyValueTest.java[]
-----
-
-Note that when a `@Property` is defined at the test method level, it causes a `RefreshEvent` to be triggered which will update any `@ConfigurationProperties` related  to the property.
-
-Alternatively you can specify additional `propertySources` in any supported format (YAML, JSON, Java properties file etc.) using the `@MicronautTest` annotation:
-
-.Using `propertySources` stored in files
-[source,java]
-----
-include::{junit5tests}/PropertySourceTest.java[]
-----
-
-The above example expects a file located at `src/test/resources/io/micronaut/junit5/myprops.properties`. You can however use a prefix to indicate where the file should be searched for. The following are valid values:
-
-* `file:myprops.properties` - A relative path to a file somewhere on the file system
-* `classpath:myprops.properties` - A file relative to the root of the classpath
-* `myprops.properties` - A file relative on the classpath relative to the test being run.
-
-If you need more dynamic property definition or the property you want to define requires some setup then you can implement the api:test.support.TestPropertyProvider[] interface in your test and do whatever setup is necessary then return the properties you want to expose the the application.
-
-For example:
-
-.Using the `TestPropertyProvider` interface
-[source,java]
-----
-include::{junit5tests}/PropertySourceMapTest.java[]
-----
-
-NOTE: When using `TestPropertyProvider` your test must be declared with JUnit's `@TestInstance(TestInstance.Lifecycle.PER_CLASS)` annotation.
-
-=== Refreshing injected beans based on `@Requires` upon properties changes
-
-include::src/main/docs/guide/includes/refreshing-requires.adoc[]
-
-.Combining `@Requires` and `@Property` in a `@Refreshable` test class.
-[source,java]
-----
-include::{junit5tests}/PropertyValueRequiresTest.java[]
-----
-
-=== Testing External Servers
-
-You can write integration tests that test external servers in a couple of different ways.
-
-One way is with the `micronaut.test.server.executable` property that allows you to specify the location of an executable JAR or native image of a server that should be started and shutdown for the lifecycle of test.
-
-In this case Micronaut Test will replace the regular server with an instance of api:test.support.server.TestExecutableEmbeddedServer[] that executes the process to start the server and closes the process when the test ends.
-
-For example:
-
-.Using `micronaut.test.server.executable`
-[source,java]
-----
-include::{junit5tests}/server/ProcessServerTest.java[tags="executable"]
-----
-
-Alternatively if you have independently started an `EmbeddedServer` instance programmatically you can also specify the URL to the server with the `micronaut.test.server.url` property.
diff --git a/src/main/docs/guide/junit5/junit5EnvironmentClasspathScanning.adoc b/src/main/docs/guide/junit5/junit5EnvironmentClasspathScanning.adoc
new file mode 100644
index 00000000..efe982c5
--- /dev/null
+++ b/src/main/docs/guide/junit5/junit5EnvironmentClasspathScanning.adoc
@@ -0,0 +1,1 @@
+include::src/main/docs/guide/includes/environments-classpath-scanning.adoc[]
diff --git a/src/main/docs/guide/junit5/junit5MockingCollaborators.adoc b/src/main/docs/guide/junit5/junit5MockingCollaborators.adoc
new file mode 100644
index 00000000..e433499e
--- /dev/null
+++ b/src/main/docs/guide/junit5/junit5MockingCollaborators.adoc
@@ -0,0 +1,24 @@
+Note that in most cases you won't define a `@MockBean` and inject it, only to verify interaction with the Mock directly. Instead, the Mock will be a collaborator within your application. For example say you have a `MathController`:
+
+.The MathController
+[source,java]
+----
+include::{junit5tests}/MathController.java[]
+----
+
+The above controller uses the `MathService` to expose a `/math/compute/{number}` endpoint. See the following example for a test that tests interaction with the mock collaborator:
+
+.Mocking Collaborators
+[source,java]
+----
+include::{junit5tests}/MathCollaboratorTest.java[]
+----
+
+<1> Like the previous example a Mock is defined using `@MockBean`
+<2> This time we inject an instance of `HttpClient` to test the controller.
+<3> We invoke the controller and retrieve the result
+<4> The interaction with mock collaborator is verified.
+
+The way this works is that `@MicronautTest` will inject the `Mock(..)` instance into the test, but the controller will have a proxy that points to the `Mock(..)` instance injected. For each iteration of the test the mock is refreshed (in fact it uses Micronaut's built in `RefreshScope`).
+
+For Factory injected beans, you can use Factory Replacement to inject Mocks. Refer to the https://docs.micronaut.io/latest/guide/index.html#_factory_replacement[factory replacement documentation] for more information.
diff --git a/src/main/docs/guide/junit5/junit5RefreshingInjectedBeansBasedOnRequiresUponPropertiesChanges.adoc b/src/main/docs/guide/junit5/junit5RefreshingInjectedBeansBasedOnRequiresUponPropertiesChanges.adoc
new file mode 100644
index 00000000..124624ad
--- /dev/null
+++ b/src/main/docs/guide/junit5/junit5RefreshingInjectedBeansBasedOnRequiresUponPropertiesChanges.adoc
@@ -0,0 +1,7 @@
+include::src/main/docs/guide/includes/refreshing-requires.adoc[]
+
+.Combining `@Requires` and `@Property` in a `@Refreshable` test class.
+[source,java]
+----
+include::{junit5tests}/PropertyValueRequiresTest.java[]
+----
diff --git a/src/main/docs/guide/junit5/junit5TransactionSemantics.adoc b/src/main/docs/guide/junit5/junit5TransactionSemantics.adoc
new file mode 100644
index 00000000..035c4b77
--- /dev/null
+++ b/src/main/docs/guide/junit5/junit5TransactionSemantics.adoc
@@ -0,0 +1,1 @@
+include::src/main/docs/guide/includes/transaction.adoc[]
diff --git a/src/main/docs/guide/junit5/settingUpJUnit5.adoc b/src/main/docs/guide/junit5/settingUpJUnit5.adoc
new file mode 100644
index 00000000..80e7172f
--- /dev/null
+++ b/src/main/docs/guide/junit5/settingUpJUnit5.adoc
@@ -0,0 +1,33 @@
+To get started using JUnit 5 you need the following dependencies in your build configuration:
+
+.build.gradle
+[source,groovy,subs="attributes"]
+----
+dependencies {
+    testAnnotationProcessor "io.micronaut:micronaut-inject-java"
+    ...
+    testImplementation("org.junit.jupiter:junit-jupiter-api")
+    testImplementation("io.micronaut.test:micronaut-test-junit5")
+    testRuntimeOnly("org.junit.jupiter:junit-jupiter-engine")
+    testImplementation("org.junit.jupiter:junit-jupiter-engine")
+}
+
+// use JUnit 5 platform
+test {
+    useJUnitPlatform()
+}
+----
+
+NOTE: If you plan to define mock beans you will also need `inject-groovy` on your `testCompile` classpath or `inject-java` for Java or Kotlin (this should already be configured if you used `mn create-app`) and the `testAnnotationProcessor`.
+
+Or for Maven:
+
+.pom.xml
+[source,xml]
+----
+<dependency>
+    <groupId>io.micronaut.test</groupId>
+    <artifactId>micronaut-test-junit5</artifactId>
+    <scope>test</scope>
+</dependency>
+----
diff --git a/src/main/docs/guide/junit5/usingMockitoMocks.adoc b/src/main/docs/guide/junit5/usingMockitoMocks.adoc
new file mode 100644
index 00000000..85ea8891
--- /dev/null
+++ b/src/main/docs/guide/junit5/usingMockitoMocks.adoc
@@ -0,0 +1,14 @@
+Now let's say you want to replace the implementation with a Mockito Mock. You can do so by defining a method that returns a mock and is annotated with `@MockBean`, for example:
+
+.The MathService specification
+[source,java]
+----
+include::{junit5tests}/MathMockServiceTest.java[]
+----
+
+<1> The `@MockBean` annotation is used to indicate the method returns a mock bean. The value to the method is the type being replaced.
+<2> Mockito's `mock(..)` method creates the actual mock
+<3> The Mock is injected into the test
+<4> Mockito is used to verify the mock is called
+
+Note that because the bean is an inner class of the test, it will be active only for the scope of the test. This approach allows you to define beans that are isolated per test class.
diff --git a/src/main/docs/guide/spock.adoc b/src/main/docs/guide/spock.adoc
index c754e5d4..e69de29b 100644
--- a/src/main/docs/guide/spock.adoc
+++ b/src/main/docs/guide/spock.adoc
@@ -1,157 +0,0 @@
-=== Setting up Spock
-
-To get started using Spock you need the following dependencies in your build configuration:
-
-.build.gradle
-[source,groovy,subs="attributes"]
-----
-testImplementation "io.micronaut.test:micronaut-test-spock"
-testImplementation("org.spockframework:spock-core") {
-    exclude group: "org.codehaus.groovy", module: "groovy-all"
-}
-----
-
-NOTE: If you plan to define mock beans you will also need `micronaut-inject-groovy` on your `testImplementation` classpath or `micronaut-inject-java` for Java or Kotlin (this should already be configured if you used `mn create-app`).
-
-Or for Maven:
-
-.pom.xml
-[source,xml,subs="attributes+"]
-----
-<dependency>
-    <groupId>io.micronaut.test</groupId>
-    <artifactId>micronaut-test-spock</artifactId>
-    <scope>test</scope>
-</dependency>
-----
-
-=== Writing a Micronaut Test with Spock
-
-Let's take a look at an example using Spock. Consider you have the following interface:
-
-.The MathService Interface
-[source,groovy]
-----
-include::{spocktests}/MathService.java[]
-----
-
-And a simple implementation that computes the value times 4 and is defined as Micronaut bean:
-
-.The MathService implementation
-[source,groovy]
-----
-include::{spocktests}/MathServiceImpl.groovy[]
-----
-
-You can define the following test to test it:
-
-.The MathService specification
-[source,groovy]
-----
-include::{spocktests}/MathServiceSpec.groovy[]
-----
-
-<1> The test is declared as Micronaut test with `@MicronautTest`
-<2> The `@Inject` annotation is used to inject the bean
-<3> The test itself tests the injected bean
-
-=== Environments, Classpath Scanning etc.
-
-include::src/main/docs/guide/includes/environments-classpath-scanning.adoc[]
-
-=== Transaction semantics
-
-include::src/main/docs/guide/includes/transaction.adoc[]
-
-=== Using Spock Mocks
-
-Now let's say you want to replace the implementation with a Spock Mock. You can do so by defining a method that returns a Spock mock and is annotated with `@MockBean`, for example:
-
-.The MathService specification
-[source,groovy]
-----
-include::{spocktests}/MathMockServiceSpec.groovy[]
-----
-
-<1> The `@MockBean` annotation is used to indicate the method returns a mock bean. The value to the method is the type being replaced.
-<2> Spock's `Mock(..)` method creates the actual mock
-<3> The Mock is injected into the test
-<4> Spock is used to verify the mock is called
-
-=== Mocking Collaborators
-
-Note that in most cases you won't define a `@MockBean` and then inject it only to verify interaction with the Mock directly, instead the Mock will be a collaborator within your application. For example say you have a `MathController`:
-
-.The MathController
-[source,groovy]
-----
-include::{spocktests}/MathController.groovy[]
-----
-
-The above controller uses the `MathService` to expose a `/math/compute/{number]` endpoint. See the following example for a test that tests interaction with the mock collaborator:
-
-.Mocking Collaborators
-[source,groovy]
-----
-include::{spocktests}/MathCollaboratorSpec.groovy[]
-----
-
-<1> Like the previous example a Mock is defined using `@MockBean`
-<2> This time we inject an instance of `HttpClient` to test the controller.
-<3> We invoke the controller and retrieve the result
-<4> The interaction with mock collaborator is verified.
-
-The way this works is that `@MicronautTest` will inject the `Mock(..)` instance into the test, but the controller will have a proxy that points to the `Mock(..)` instance injected. For each iteration of the test the mock is refreshed (in fact it uses Micronaut's built in `RefreshScope`).
-
-
-=== Using `@Requires` on Tests
-
-Since `@MicronautTest` turns tests into beans themselves, it means you can use the `@Requires` annotation on the test to enable/disable tests. For example:
-
-[source,java]
-----
-@MicronautTest
-@Requires(env = "my-env")
-class RequiresSpec extends Specification {
-    ...
-}
-----
-
-The above test will only run if `my-env` is active (you can activate it by passing the system property `micronaut.environments`).
-
-=== Defining Additional Test Specific Properties
-
-You can define additional test specific properties using the `@Property` annotation. The following example demonstrates usage:
-
-.Using `@Property`
-[source,java]
-----
-include::{spocktests}/PropertySpec.groovy[]
-----
-
-Note that when a `@Property` is defined at the test method level, it causes a `RefreshEvent` to be triggered which will update any `@ConfigurationProperties` related  to the property.
-
-
-Alternatively you can specify additional `propertySources` in any supported format (YAML, JSON, Java properties file etc.) using the `@MicronautTest` annotation:
-
-.Using `propertySources` stored in files
-[source,java]
-----
-include::{spocktests}/PropertySourceSpec.groovy[]
-----
-
-The above example expects a file located at `src/test/resources/io/micronaut/spock/myprops.properties`. You can however use a prefix to indicate where the file should be searched for. The following are valid values:
-
-* `file:myprops.properties` - A relative path to a file somewhere on the file system.
-* `classpath:myprops.properties` - A file relative to the root of the classpath.
-* `myprops.properties` - A file relative on the classpath relative to the test being run.
-
-=== Refreshing injected beans based on `@Requires` upon properties changes
-
-include::src/main/docs/guide/includes/refreshing-requires.adoc[]
-
-.Combining `@Requires` and `@Property` in a `@Refreshable` test class.
-[source,java]
-----
-include::{spocktests}/PropertyValueRequiresSpec.groovy[]
-----
diff --git a/src/main/docs/guide/spock/refreshingInjectedBeansBasedOnRequiresUponPropertiesChanges.adoc b/src/main/docs/guide/spock/refreshingInjectedBeansBasedOnRequiresUponPropertiesChanges.adoc
new file mode 100644
index 00000000..32bc73ea
--- /dev/null
+++ b/src/main/docs/guide/spock/refreshingInjectedBeansBasedOnRequiresUponPropertiesChanges.adoc
@@ -0,0 +1,7 @@
+include::src/main/docs/guide/includes/refreshing-requires.adoc[]
+
+.Combining `@Requires` and `@Property` in a `@Refreshable` test class.
+[source,java]
+----
+include::{spocktests}/PropertyValueRequiresSpec.groovy[]
+----
diff --git a/src/main/docs/guide/spock/settingUpSpock.adoc b/src/main/docs/guide/spock/settingUpSpock.adoc
new file mode 100644
index 00000000..36c1b99c
--- /dev/null
+++ b/src/main/docs/guide/spock/settingUpSpock.adoc
@@ -0,0 +1,24 @@
+To get started using Spock you need the following dependencies in your build configuration:
+
+.build.gradle
+[source,groovy,subs="attributes"]
+----
+testImplementation "io.micronaut.test:micronaut-test-spock"
+testImplementation("org.spockframework:spock-core") {
+    exclude group: "org.codehaus.groovy", module: "groovy-all"
+}
+----
+
+NOTE: If you plan to define mock beans you will also need `micronaut-inject-groovy` on your `testImplementation` classpath or `micronaut-inject-java` for Java or Kotlin (this should already be configured if you used `mn create-app`).
+
+Or for Maven:
+
+.pom.xml
+[source,xml,subs="attributes+"]
+----
+<dependency>
+    <groupId>io.micronaut.test</groupId>
+    <artifactId>micronaut-test-spock</artifactId>
+    <scope>test</scope>
+</dependency>
+----
diff --git a/src/main/docs/guide/spock/spockEnvironmentClasspathScanning.adoc b/src/main/docs/guide/spock/spockEnvironmentClasspathScanning.adoc
new file mode 100644
index 00000000..efe982c5
--- /dev/null
+++ b/src/main/docs/guide/spock/spockEnvironmentClasspathScanning.adoc
@@ -0,0 +1,1 @@
+include::src/main/docs/guide/includes/environments-classpath-scanning.adoc[]
diff --git a/src/main/docs/guide/spock/spockTransactionSemantics.adoc b/src/main/docs/guide/spock/spockTransactionSemantics.adoc
new file mode 100644
index 00000000..035c4b77
--- /dev/null
+++ b/src/main/docs/guide/spock/spockTransactionSemantics.adoc
@@ -0,0 +1,1 @@
+include::src/main/docs/guide/includes/transaction.adoc[]
diff --git a/src/main/docs/guide/spock/spockUsingCollaborators.adoc b/src/main/docs/guide/spock/spockUsingCollaborators.adoc
new file mode 100644
index 00000000..11cbf454
--- /dev/null
+++ b/src/main/docs/guide/spock/spockUsingCollaborators.adoc
@@ -0,0 +1,23 @@
+Note that in most cases you won't define a `@MockBean` and inject it, only to verify interaction with the Mock directly. Instead, the Mock will be a collaborator within your application. For example say you have a `MathController`:
+
+.The MathController
+[source,groovy]
+----
+include::{spocktests}/MathController.groovy[]
+----
+
+The above controller uses the `MathService` to expose a `/math/compute/{number]` endpoint. See the following example for a test that tests interaction with the mock collaborator:
+
+.Mocking Collaborators
+[source,groovy]
+----
+include::{spocktests}/MathCollaboratorSpec.groovy[]
+----
+
+<1> Like the previous example a Mock is defined using `@MockBean`
+<2> This time we inject an instance of `HttpClient` to test the controller.
+<3> We invoke the controller and retrieve the result
+<4> The interaction with mock collaborator is verified.
+
+The way this works is that `@MicronautTest` will inject the `Mock(..)` instance into the test, but the controller will have a proxy that points to the `Mock(..)` instance injected. For each iteration of the test the mock is refreshed (in fact it uses Micronaut's built in `RefreshScope`).
+
diff --git a/src/main/docs/guide/spock/usingSpockMocks.adoc b/src/main/docs/guide/spock/usingSpockMocks.adoc
new file mode 100644
index 00000000..215dfed0
--- /dev/null
+++ b/src/main/docs/guide/spock/usingSpockMocks.adoc
@@ -0,0 +1,12 @@
+Now let's say you want to replace the implementation with a Spock Mock. You can do so by defining a method that returns a Spock mock and is annotated with `@MockBean`, for example:
+
+.The MathService specification
+[source,groovy]
+----
+include::{spocktests}/MathMockServiceSpec.groovy[]
+----
+
+<1> The `@MockBean` annotation is used to indicate the method returns a mock bean. The value to the method is the type being replaced.
+<2> Spock's `Mock(..)` method creates the actual mock
+<3> The Mock is injected into the test
+<4> Spock is used to verify the mock is called
diff --git a/src/main/docs/guide/toc.yml b/src/main/docs/guide/toc.yml
index 473279b3..7142d33d 100644
--- a/src/main/docs/guide/toc.yml
+++ b/src/main/docs/guide/toc.yml
@@ -1,9 +1,42 @@
 introduction:
   title: Introduction
 releaseHistory: Release History
-spock: Testing with Spock
-junit5: Testing with JUnit 5
-kotest5: Testing with Kotest 5
+spock:
+  title: Testing with Spock
+  settingUpSpock: Setting up Spock
+  writingAMicronautTestWithSpock: Writing a Micronaut Test with Spock
+  spockEnvironmentClasspathScanning: Environments, Classpath Scanning etc.
+  spockTransactionSemantics: Transaction semantics
+  usingSpockMocks: Using Spock Mocks
+  spockUsingCollaborators: Mocking Collaborators
+  usingRequiresOnTests: Using `@Requires` on Tests
+  definingAdditionalTestSpecificProperties: Defining Additional Test Specific Properties
+  refreshingInjectedBeansBasedOnRequiresUponPropertiesChanges: Refreshing injected beans based on `@Requires` upon properties changes
+junit5:
+  title: Testing with JUnit 5
+  settingUpJUnit5: Setting up JUnit 5
+  writingAMicronautTestWithJUnit5: Writing a Micronaut Test with JUnit 5
+  junit5EnvironmentClasspathScanning: Environments, Classpath Scanning etc.
+  junit5TransactionSemantics: Transaction semantics
+  usingMockitoMocks: Using Mockito Mocks
+  junit5MockingCollaborators: Mocking Collaborators
+  junit5UsingRequiresOnTests: Using `@Requires` on Tests
+  junit5DefiningAdditionalTestSpecificProperties: Defining Additional Test Specific Properties
+  junit5RefreshingInjectedBeansBasedOnRequiresUponPropertiesChanges: Refreshing injected beans based on `@Requires` upon properties changes
+  junit5TestingExternalServers: Testing External Servers
+kotest5:
+  title: Testing with Kotest 5
+  settingUpKoTest5: Setting up Kotest 5
+  kotest5BeforeYouBegin: Before You Begin
+  kotest5WritingAMicronautTest: Writing a Micronaut Test with Kotest
+  kotest5EnvironmentClasspathScanning: Environments, Classpath Scanning etc.
+  kotest5TransactionSemantics: Transaction semantics
+  usingMockkMocks: Using Mockk Mocks
+  kotest5MockingCollaborators: Mocking Collaborators
+  kotestUsingRequiresOnTests: Using `@Requires` on Tests
+  kotest5DefiningAdditionalTestSpecificProperties: Defining Additional Test Specific Properties
+  kotest5ConstructorInjectionCaveats: Constructor Injection Caveats
+  kotest5RefreshingInjectedBeansBasedOnRequiresUponPropertiesChanges: Refreshing injected beans based on `@Requires` upon properties changes
 restAssured: REST Assured
 #spek: Testing with Spek
 repository: Repository


Test patch:
diff --git a/src/main/docs/guide/junit5/junit5DefiningAdditionalTestSpecificProperties.adoc b/src/main/docs/guide/junit5/junit5DefiningAdditionalTestSpecificProperties.adoc
new file mode 100644
index 00000000..d2202a21
--- /dev/null
+++ b/src/main/docs/guide/junit5/junit5DefiningAdditionalTestSpecificProperties.adoc
@@ -0,0 +1,35 @@
+You can define additional test specific properties using the `@Property` annotation. The following example demonstrates usage:
+
+.Using `@Property`
+[source,java]
+----
+include::{junit5tests}/PropertyValueTest.java[]
+----
+
+Note that when a `@Property` is defined at the test method level, it causes a `RefreshEvent` to be triggered which will update any `@ConfigurationProperties` related  to the property.
+
+Alternatively you can specify additional `propertySources` in any supported format (YAML, JSON, Java properties file etc.) using the `@MicronautTest` annotation:
+
+.Using `propertySources` stored in files
+[source,java]
+----
+include::{junit5tests}/PropertySourceTest.java[]
+----
+
+The above example expects a file located at `src/test/resources/io/micronaut/junit5/myprops.properties`. You can however use a prefix to indicate where the file should be searched for. The following are valid values:
+
+* `file:myprops.properties` - A relative path to a file somewhere on the file system
+* `classpath:myprops.properties` - A file relative to the root of the classpath
+* `myprops.properties` - A file relative on the classpath relative to the test being run.
+
+If you need more dynamic property definition or the property you want to define requires some setup then you can implement the api:test.support.TestPropertyProvider[] interface in your test and do whatever setup is necessary then return the properties you want to expose the the application.
+
+For example:
+
+.Using the `TestPropertyProvider` interface
+[source,java]
+----
+include::{junit5tests}/PropertySourceMapTest.java[]
+----
+
+NOTE: When using `TestPropertyProvider` your test must be declared with JUnit's `@TestInstance(TestInstance.Lifecycle.PER_CLASS)` annotation.
diff --git a/src/main/docs/guide/junit5/junit5TestingExternalServers.adoc b/src/main/docs/guide/junit5/junit5TestingExternalServers.adoc
new file mode 100644
index 00000000..0022135a
--- /dev/null
+++ b/src/main/docs/guide/junit5/junit5TestingExternalServers.adoc
@@ -0,0 +1,15 @@
+You can write integration tests that test external servers in a couple of different ways.
+
+One way is with the `micronaut.test.server.executable` property that allows you to specify the location of an executable JAR or native image of a server that should be started and shutdown for the lifecycle of test.
+
+In this case Micronaut Test will replace the regular server with an instance of api:test.support.server.TestExecutableEmbeddedServer[] that executes the process to start the server and closes the process when the test ends.
+
+For example:
+
+.Using `micronaut.test.server.executable`
+[source,java]
+----
+include::{junit5tests}/server/ProcessServerTest.java[tags="executable"]
+----
+
+Alternatively if you have independently started an `EmbeddedServer` instance programmatically you can also specify the URL to the server with the `micronaut.test.server.url` property.
diff --git a/src/main/docs/guide/junit5/junit5UsingRequiresOnTests.adoc b/src/main/docs/guide/junit5/junit5UsingRequiresOnTests.adoc
new file mode 100644
index 00000000..37eb55a4
--- /dev/null
+++ b/src/main/docs/guide/junit5/junit5UsingRequiresOnTests.adoc
@@ -0,0 +1,12 @@
+Since `@MicronautTest` turns tests into beans themselves, it means you can use the `@Requires` annotation on the test to enable/disable tests. For example:
+
+[source,java]
+----
+@MicronautTest
+@Requires(env = "my-env")
+class RequiresTest {
+    ...
+}
+----
+
+The above test will only run if `my-env` is active (you can activate it by passing the system property `micronaut.environments`).
diff --git a/src/main/docs/guide/junit5/writingAMicronautTestWithJUnit5.adoc b/src/main/docs/guide/junit5/writingAMicronautTestWithJUnit5.adoc
new file mode 100644
index 00000000..950f5cdf
--- /dev/null
+++ b/src/main/docs/guide/junit5/writingAMicronautTestWithJUnit5.adoc
@@ -0,0 +1,28 @@
+Let's take a look at an example using JUnit 5. Consider you have the following interface:
+
+.The MathService Interface
+[source,java]
+----
+include::{junit5tests}/MathService.java[]
+----
+
+And a simple implementation that computes the value times 4 and is defined as a Micronaut bean:
+
+.The MathService implementation
+[source,java]
+----
+include::{junit5tests}/MathServiceImpl.java[]
+----
+
+You can define the following test to test the implementation:
+
+.The MathService specification
+[source,groovy]
+----
+include::{junit5tests}/MathServiceTest.java[]
+----
+
+<1> The test is declared as Micronaut test with `@MicronautTest`
+<2> The `@Inject` annotation is used to inject the bean
+<3> The test itself tests the injected bean
+
diff --git a/src/main/docs/guide/kotest5.adoc b/src/main/docs/guide/kotest5.adoc
index 9ca5db4f..e69de29b 100644
--- a/src/main/docs/guide/kotest5.adoc
+++ b/src/main/docs/guide/kotest5.adoc
@@ -1,302 +0,0 @@
-=== Setting up Kotest 5
-
-To get started using Kotest 5 you need the following dependencies in your build configuration:
-
-.build.gradle
-[source,groovy,subs="attributes"]
-----
-dependencies {
-    kaptTest "io.micronaut:micronaut-inject-java"
-    testImplementation "io.micronaut.test:micronaut-test-kotest5:{version}"
-    testImplementation "io.mockk:mockk:{mockkVersion}"
-    testImplementation "io.kotest:kotest-runner-junit5-jvm:{kotestVersion}"
-}
-
-// use JUnit 5 platform
-test {
-    useJUnitPlatform()
-}
-----
-
-Or for Maven:
-
-.pom.xml
-[source,xml,subs="attributes+"]
-----
-<dependency>
-    <groupId>io.micronaut.test</groupId>
-    <artifactId>micronaut-test-kotest5</artifactId>
-    <version>{version}</version>
-    <scope>test</scope>
-</dependency>
-<dependency>
-    <groupId>io.mockk</groupId>
-    <artifactId>mockk</artifactId>
-    <version>{mockkVersion}</version>
-    <scope>test</scope>
-</dependency>
-<dependency>
-    <groupId>io.kotest</groupId>
-    <artifactId>kotest-runner-junit5-jvm</artifactId>
-    <version>{kotestVersion}</version>
-    <scope>test</scope>
-</dependency>
-----
-
-Note that for Maven you will also need to configure the Surefire plugin to use JUnit platform and configure the kotlin maven plugin:
-
-.pom.xml
-[source,xml]
-----
-<plugin>
-    <groupId>org.apache.maven.plugins</groupId>
-    <artifactId>maven-surefire-plugin</artifactId>
-    <version>2.22.2</version>
-    <dependencies>
-        <dependency>
-            <groupId>org.junit.jupiter</groupId>
-            <artifactId>junit-jupiter-engine</artifactId>
-            <version>5.6.2</version>
-        </dependency>
-    </dependencies>
-</plugin>
-<plugin>
-    <artifactId>kotlin-maven-plugin</artifactId>
-    <groupId>org.jetbrains.kotlin</groupId>
-    <version>1.4.10</version>
-    <configuration>
-        <compilerPlugins>
-            <plugin>all-open</plugin>
-        </compilerPlugins>
-        <pluginOptions>
-            <option>all-open:annotation=io.micronaut.aop.Around</option>
-        </pluginOptions>
-    </configuration>
-    <executions>
-        <execution>
-            <id>kapt</id>
-            <goals>
-                <goal>kapt</goal>
-            </goals>
-            <configuration>
-                <sourceDirs>
-                    <sourceDir>${project.baseDir}/src/main/kotlin</sourceDir>
-                </sourceDirs>
-                <annotationProcessorPaths>
-                    <annotationProcessorPath>
-                        <groupId>io.micronaut</groupId>
-                        <artifactId>micronaut-inject-java</artifactId>
-                        <version>${micronaut.version}</version>
-                    </annotationProcessorPath>
-                    <annotationProcessorPath>
-                        <groupId>io.micronaut</groupId>
-                        <artifactId>micronaut-validation</artifactId>
-                        <version>${micronaut.version}</version>
-                    </annotationProcessorPath>
-                </annotationProcessorPaths>
-            </configuration>
-        </execution>
-        <execution>
-            <id>compile</id>
-            <goals>
-                <goal>compile</goal>
-            </goals>
-            <configuration>
-                <sourceDirs>
-                    <sourceDir>${project.basedir}/src/main/kotlin</sourceDir>
-                    <sourceDir>${project.basedir}/src/main/java</sourceDir>
-                </sourceDirs>
-            </configuration>
-        </execution>
-        <execution>
-            <id>test-kapt</id>
-            <goals>
-                <goal>test-kapt</goal>
-            </goals>
-            <configuration>
-                <sourceDirs>
-                    <sourceDir>src/test/kotlin</sourceDir>
-                </sourceDirs>
-                <annotationProcessorPaths>
-                    <annotationProcessorPath>
-                        <groupId>io.micronaut</groupId>
-                        <artifactId>micronaut-inject-java</artifactId>
-                        <version>${micronaut.version}</version>
-                    </annotationProcessorPath>
-                </annotationProcessorPaths>
-            </configuration>
-        </execution>
-        <execution>
-            <id>test-compile</id>
-            <goals>
-                <goal>test-compile</goal>
-            </goals>
-            <configuration>
-                <sourceDirs>
-                    <sourceDir>${project.basedir}/src/test/kotlin</sourceDir>
-                    <sourceDir>${project.basedir}/target/generated-sources/kapt/test</sourceDir>
-                </sourceDirs>
-            </configuration>
-        </execution>
-    </executions>
-    <dependencies>
-        <dependency>
-            <groupId>org.jetbrains.kotlin</groupId>
-            <artifactId>kotlin-maven-allopen</artifactId>
-            <version>${kotlinVersion}</version>
-        </dependency>
-    </dependencies>
-</plugin>
-----
-
-=== Before You Begin
-
-Before you can get started writing tests with Kotest, it is necessary to inform Kotest of the Micronaut extensions. The way to do that is by providing a `ProjectConfig`. Here is how to do so for Micronaut Test:
-
-[source,kotlin]
-----
-include::test-kotest5/src/test/kotlin/io/micronaut/test/kotest5/ProjectConfig.kt[]
-----
-
-=== Writing a Micronaut Test with Kotest
-
-Let's take a look at an example using Kotest. Consider you have the following interface:
-
-.The MathService Interface
-[source,kotlin]
-----
-include::{kotest5tests}/MathService.kt[]
-----
-
-And a simple implementation that computes the value times 4 and is defined as Micronaut bean:
-
-.The MathService implementation
-[source,kotlin]
-----
-include::{kotest5tests}/MathServiceImpl.kt[]
-----
-
-You can define the following test to test the implementation:
-
-.The MathService specification
-[source,groovy]
-----
-include::{kotest5tests}/MathServiceTest.kt[]
-----
-
-<1> The test is declared as Micronaut test with `@MicronautTest`
-<2> The constructor is used to inject the bean
-<3> The test itself tests the injected bean
-
-
-=== Environments, Classpath Scanning etc.
-
-include::src/main/docs/guide/includes/environments-classpath-scanning.adoc[]
-
-=== Transaction semantics
-
-include::src/main/docs/guide/includes/transaction.adoc[]
-
-=== Using Mockk Mocks
-
-Now let's say you want to replace the implementation with a Mockk. You can do so by defining a method that returns a mock and is annotated with `@MockBean`, for example:
-
-.The MathService specification
-[source,kotlin]
-----
-include::{kotest5tests}/MathMockServiceTest.kt[]
-----
-
-<1> The `@MockBean` annotation is used to indicate the method returns a mock bean. The value to the method is the type being replaced.
-<2> Mockk's `mockk(..)` method creates the actual mock
-<3> The math service proxy is injected into the test
-<4> The call to `getMock` is used to retrieve the underlying mock
-<5> Mockk is used to verify the mock is called
-
-Note that because the bean is a method of the test, it will be active only for the scope of the test. This approach allows you to define beans that are isolated per test class.
-
-IMPORTANT: Because Kotlin uses constructor injection, it's not possible to automatically replace the mock proxy with the mock implementation as is done with the other test implementations. The `getMock` method was created to make retrieving the underlying mock object easier.
-
-=== Mocking Collaborators
-
-Note that in most cases you won't define a `@MockBean` and then inject it only to verify interaction with the Mock directly, instead the Mock will be a collaborator within your application. For example say you have a `MathController`:
-
-.The MathController
-[source,kotlin]
-----
-include::{kotest5tests}/MathController.kt[]
-----
-
-The above controller uses the `MathService` to expose a `/math/compute/{number}` endpoint. See the following example for a test that tests interaction with the mock collaborator:
-
-.Mocking Collaborators
-[source,kotlin]
-----
-include::{kotest5tests}/MathCollaboratorTest.kt[]
-----
-
-<1> Like the previous example a Mock is defined using `@MockBean`
-<2> This time we inject an instance of `HttpClient` to test the controller.
-<3> We invoke the controller and retrieve the result
-<4> The interaction with mock collaborator is verified.
-
-The way this works is that `@MicronautTest` will inject a proxy that points to the mock instance. For each iteration of the test the mock is refreshed (in fact it uses Micronaut's built in `RefreshScope`).
-
-=== Using `@Requires` on Tests
-
-Since `@MicronautTest` turns tests into beans themselves, it means you can use the `@Requires` annotation on the test to enable/disable tests. For example:
-
-[source,kotlin]
-----
-@MicronautTest
-@Requires(env = "my-env")
-class RequiresTest {
-    ...
-}
-----
-
-The above test will only run if `my-env` is active (you can activate it by passing the system property `micronaut.environments`).
-
-=== Defining Additional Test Specific Properties
-
-You can define additional test specific properties using the `@Property` annotation. The following example demonstrates usage:
-
-.Using `@Property`
-[source,kotlin]
-----
-include::{kotest5tests}/PropertyValueTest.kt[]
-----
-
-Alternatively you can specify additional `propertySources` in any supported format (YAML, JSON, Java properties file etc.) using the `@MicronautTest` annotation:
-
-.Using `propertySources` stored in files
-[source,kotlin]
-----
-include::{kotest5tests}/PropertySourceTest.kt[]
-----
-
-The above example expects a file located at `src/test/resources/io/micronaut/kotest/myprops.properties`. You can however use a prefix to indicate where the file should be searched for. The following are valid values:
-
-* `file:myprops.properties` - A relative path to a file somewhere on the file system
-* `classpath:myprops.properties` - A file relative to the root of the classpath
-* `myprops.properties` - A file relative on the classpath relative to the test being run.
-
-NOTE: Because Kotlin doesn't support multiple annotations, the `@PropertySource` annotation must be used to define multiple properties.
-
-=== Constructor Injection Caveats
-
-There are a couple caveats to using constructor injection to be aware of.
-
-1. In order for `TestPropertyProvider` to work, test classes must have not have any constructor arguments. This is because the class needs constructed prior to bean creation in order to add the properties to the context. Fields and methods will still be injected.
-
-1. `@Requires()` cannot be used with constructor injection because Kotest requires the instance to be created regardless if the test should be ignored or not. If the requirements disable the bean, it cannot be created from the context and thus construction responsibility will be delegated to the default behavior.
-
-=== Refreshing injected beans based on `@Requires` upon properties changes
-
-include::src/main/docs/guide/includes/refreshing-requires.adoc[]
-
-.Combining `@Requires` and `@Property` in a `@Refreshable` test class.
-[source,kotlin]
-----
-include::{kotest5tests}/PropertyValueRequiresTest.kt[]
-----
diff --git a/src/main/docs/guide/kotest5/kotest5BeforeYouBegin.adoc b/src/main/docs/guide/kotest5/kotest5BeforeYouBegin.adoc
new file mode 100644
index 00000000..c21c5fa5
--- /dev/null
+++ b/src/main/docs/guide/kotest5/kotest5BeforeYouBegin.adoc
@@ -0,0 +1,6 @@
+Before you can get started writing tests with Kotest, it is necessary to inform Kotest of the Micronaut extensions. The way to do that is by providing a `ProjectConfig`. Here is how to do so for Micronaut Test:
+
+[source,kotlin]
+----
+include::test-kotest5/src/test/kotlin/io/micronaut/test/kotest5/ProjectConfig.kt[]
+----
diff --git a/src/main/docs/guide/kotest5/kotest5ConstructorInjectionCaveats.adoc b/src/main/docs/guide/kotest5/kotest5ConstructorInjectionCaveats.adoc
new file mode 100644
index 00000000..54220e74
--- /dev/null
+++ b/src/main/docs/guide/kotest5/kotest5ConstructorInjectionCaveats.adoc
@@ -0,0 +1,5 @@
+There are a couple caveats to using constructor injection to be aware of.
+
+1. In order for `TestPropertyProvider` to work, test classes must have not have any constructor arguments. This is because the class needs to be constructed prior to bean creation, in order to add the properties to the context. Fields and methods will still be injected.
+
+1. `@Requires()` cannot be used with constructor injection because Kotest requires the instance to be created regardless if the test should be ignored or not. If the requirements disable the bean, it cannot be created from the context and thus construction responsibility will be delegated to the default behavior.
diff --git a/src/main/docs/guide/kotest5/kotest5DefiningAdditionalTestSpecificProperties.adoc b/src/main/docs/guide/kotest5/kotest5DefiningAdditionalTestSpecificProperties.adoc
new file mode 100644
index 00000000..581a3970
--- /dev/null
+++ b/src/main/docs/guide/kotest5/kotest5DefiningAdditionalTestSpecificProperties.adoc
@@ -0,0 +1,23 @@
+You can define additional test specific properties using the `@Property` annotation. The following example demonstrates usage:
+
+.Using `@Property`
+[source,kotlin]
+----
+include::{kotest5tests}/PropertyValueTest.kt[]
+----
+
+Alternatively you can specify additional `propertySources` in any supported format (YAML, JSON, Java properties file etc.) using the `@MicronautTest` annotation:
+
+.Using `propertySources` stored in files
+[source,kotlin]
+----
+include::{kotest5tests}/PropertySourceTest.kt[]
+----
+
+The above example expects a file located at `src/test/resources/io/micronaut/kotest/myprops.properties`. You can however use a prefix to indicate where the file should be searched for. The following are valid values:
+
+* `file:myprops.properties` - A relative path to a file somewhere on the file system
+* `classpath:myprops.properties` - A file relative to the root of the classpath
+* `myprops.properties` - A file relative on the classpath relative to the test being run.
+
+NOTE: Because Kotlin doesn't support multiple annotations, the `@PropertySource` annotation must be used to define multiple properties.
diff --git a/src/main/docs/guide/kotest5/kotest5EnvironmentClasspathScanning.adoc b/src/main/docs/guide/kotest5/kotest5EnvironmentClasspathScanning.adoc
new file mode 100644
index 00000000..efe982c5
--- /dev/null
+++ b/src/main/docs/guide/kotest5/kotest5EnvironmentClasspathScanning.adoc
@@ -0,0 +1,1 @@
+include::src/main/docs/guide/includes/environments-classpath-scanning.adoc[]
diff --git a/src/main/docs/guide/kotest5/kotest5MockingCollaborators.adoc b/src/main/docs/guide/kotest5/kotest5MockingCollaborators.adoc
new file mode 100644
index 00000000..f5434fea
--- /dev/null
+++ b/src/main/docs/guide/kotest5/kotest5MockingCollaborators.adoc
@@ -0,0 +1,23 @@
+Note that in most cases you won't define a `@MockBean` and inject it only to verify interaction with the Mock directly. Instead, the Mock will be a collaborator within your application. For example say you have a `MathController`:
+
+.The MathController
+[source,kotlin]
+----
+include::{kotest5tests}/MathController.kt[]
+----
+
+The above controller uses the `MathService` to expose a `/math/compute/{number}` endpoint. See the following example for a test that tests interaction with the mock collaborator:
+
+.Mocking Collaborators
+[source,kotlin]
+----
+include::{kotest5tests}/MathCollaboratorTest.kt[]
+----
+
+<1> Like the previous example a Mock is defined using `@MockBean`
+<2> This time we inject an instance of `HttpClient` to test the controller.
+<3> We invoke the controller and retrieve the result
+<4> The interaction with mock collaborator is verified.
+
+The way this works is that `@MicronautTest` will inject a proxy that points to the mock instance. For each iteration of the test the mock is refreshed (in fact it uses Micronaut's built in `RefreshScope`).
+
diff --git a/src/main/docs/guide/kotest5/kotest5RefreshingInjectedBeansBasedOnRequiresUponPropertiesChanges.adoc b/src/main/docs/guide/kotest5/kotest5RefreshingInjectedBeansBasedOnRequiresUponPropertiesChanges.adoc
new file mode 100644
index 00000000..8fed6e38
--- /dev/null
+++ b/src/main/docs/guide/kotest5/kotest5RefreshingInjectedBeansBasedOnRequiresUponPropertiesChanges.adoc
@@ -0,0 +1,7 @@
+include::src/main/docs/guide/includes/refreshing-requires.adoc[]
+
+.Combining `@Requires` and `@Property` in a `@Refreshable` test class.
+[source,kotlin]
+----
+include::{kotest5tests}/PropertyValueRequiresTest.kt[]
+----
diff --git a/src/main/docs/guide/kotest5/kotest5TransactionSemantics.adoc b/src/main/docs/guide/kotest5/kotest5TransactionSemantics.adoc
new file mode 100644
index 00000000..035c4b77
--- /dev/null
+++ b/src/main/docs/guide/kotest5/kotest5TransactionSemantics.adoc
@@ -0,0 +1,1 @@
+include::src/main/docs/guide/includes/transaction.adoc[]
diff --git a/src/main/docs/guide/kotest5/kotest5WritingAMicronautTest.adoc b/src/main/docs/guide/kotest5/kotest5WritingAMicronautTest.adoc
new file mode 100644
index 00000000..21982555
--- /dev/null
+++ b/src/main/docs/guide/kotest5/kotest5WritingAMicronautTest.adoc
@@ -0,0 +1,27 @@
+Let's take a look at an example using Kotest. Consider you have the following interface:
+
+.The MathService Interface
+[source,kotlin]
+----
+include::{kotest5tests}/MathService.kt[]
+----
+
+And a simple implementation that computes the value times 4 and is defined as a Micronaut bean:
+
+.The MathService implementation
+[source,kotlin]
+----
+include::{kotest5tests}/MathServiceImpl.kt[]
+----
+
+You can define the following test to test the implementation:
+
+.The MathService specification
+[source,groovy]
+----
+include::{kotest5tests}/MathServiceTest.kt[]
+----
+
+<1> The test is declared as Micronaut test with `@MicronautTest`
+<2> The constructor is used to inject the bean
+<3> The test itself tests the injected bean
diff --git a/src/main/docs/guide/kotest5/kotestUsingRequiresOnTests.adoc b/src/main/docs/guide/kotest5/kotestUsingRequiresOnTests.adoc
new file mode 100644
index 00000000..133b5f8e
--- /dev/null
+++ b/src/main/docs/guide/kotest5/kotestUsingRequiresOnTests.adoc
@@ -0,0 +1,13 @@
+Since `@MicronautTest` turns tests into beans themselves, it means you can use the `@Requires` annotation on the test to enable/disable tests. For example:
+
+[source,kotlin]
+----
+@MicronautTest
+@Requires(env = "my-env")
+class RequiresTest {
+    ...
+}
+----
+
+The above test will only run if `my-env` is active (you can activate it by passing the system property `micronaut.environments`).
+
diff --git a/src/main/docs/guide/kotest5/settingUpKoTest5.adoc b/src/main/docs/guide/kotest5/settingUpKoTest5.adoc
new file mode 100644
index 00000000..c08b0f20
--- /dev/null
+++ b/src/main/docs/guide/kotest5/settingUpKoTest5.adoc
@@ -0,0 +1,148 @@
+To get started using Kotest 5 you need the following dependencies in your build configuration:
+
+.build.gradle
+[source,groovy,subs="attributes"]
+----
+dependencies {
+    kaptTest "io.micronaut:micronaut-inject-java"
+    testImplementation "io.micronaut.test:micronaut-test-kotest5:{version}"
+    testImplementation "io.mockk:mockk:{mockkVersion}"
+    testImplementation "io.kotest:kotest-runner-junit5-jvm:{kotestVersion}"
+}
+
+// use JUnit 5 platform
+test {
+    useJUnitPlatform()
+}
+----
+
+Or for Maven:
+
+.pom.xml
+[source,xml,subs="attributes+"]
+----
+<dependency>
+    <groupId>io.micronaut.test</groupId>
+    <artifactId>micronaut-test-kotest5</artifactId>
+    <version>{version}</version>
+    <scope>test</scope>
+</dependency>
+<dependency>
+    <groupId>io.mockk</groupId>
+    <artifactId>mockk</artifactId>
+    <version>{mockkVersion}</version>
+    <scope>test</scope>
+</dependency>
+<dependency>
+    <groupId>io.kotest</groupId>
+    <artifactId>kotest-runner-junit5-jvm</artifactId>
+    <version>{kotestVersion}</version>
+    <scope>test</scope>
+</dependency>
+----
+
+Note that for Maven you will also need to configure the Surefire plugin to use JUnit platform and configure the kotlin maven plugin:
+
+.pom.xml
+[source,xml]
+----
+<plugin>
+    <groupId>org.apache.maven.plugins</groupId>
+    <artifactId>maven-surefire-plugin</artifactId>
+    <version>2.22.2</version>
+    <dependencies>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-engine</artifactId>
+            <version>5.6.2</version>
+        </dependency>
+    </dependencies>
+</plugin>
+<plugin>
+    <artifactId>kotlin-maven-plugin</artifactId>
+    <groupId>org.jetbrains.kotlin</groupId>
+    <version>1.4.10</version>
+    <configuration>
+        <compilerPlugins>
+            <plugin>all-open</plugin>
+        </compilerPlugins>
+        <pluginOptions>
+            <option>all-open:annotation=io.micronaut.aop.Around</option>
+        </pluginOptions>
+    </configuration>
+    <executions>
+        <execution>
+            <id>kapt</id>
+            <goals>
+                <goal>kapt</goal>
+            </goals>
+            <configuration>
+                <sourceDirs>
+                    <sourceDir>${project.baseDir}/src/main/kotlin</sourceDir>
+                </sourceDirs>
+                <annotationProcessorPaths>
+                    <annotationProcessorPath>
+                        <groupId>io.micronaut</groupId>
+                        <artifactId>micronaut-inject-java</artifactId>
+                        <version>${micronaut.version}</version>
+                    </annotationProcessorPath>
+                    <annotationProcessorPath>
+                        <groupId>io.micronaut</groupId>
+                        <artifactId>micronaut-validation</artifactId>
+                        <version>${micronaut.version}</version>
+                    </annotationProcessorPath>
+                </annotationProcessorPaths>
+            </configuration>
+        </execution>
+        <execution>
+            <id>compile</id>
+            <goals>
+                <goal>compile</goal>
+            </goals>
+            <configuration>
+                <sourceDirs>
+                    <sourceDir>${project.basedir}/src/main/kotlin</sourceDir>
+                    <sourceDir>${project.basedir}/src/main/java</sourceDir>
+                </sourceDirs>
+            </configuration>
+        </execution>
+        <execution>
+            <id>test-kapt</id>
+            <goals>
+                <goal>test-kapt</goal>
+            </goals>
+            <configuration>
+                <sourceDirs>
+                    <sourceDir>src/test/kotlin</sourceDir>
+                </sourceDirs>
+                <annotationProcessorPaths>
+                    <annotationProcessorPath>
+                        <groupId>io.micronaut</groupId>
+                        <artifactId>micronaut-inject-java</artifactId>
+                        <version>${micronaut.version}</version>
+                    </annotationProcessorPath>
+                </annotationProcessorPaths>
+            </configuration>
+        </execution>
+        <execution>
+            <id>test-compile</id>
+            <goals>
+                <goal>test-compile</goal>
+            </goals>
+            <configuration>
+                <sourceDirs>
+                    <sourceDir>${project.basedir}/src/test/kotlin</sourceDir>
+                    <sourceDir>${project.basedir}/target/generated-sources/kapt/test</sourceDir>
+                </sourceDirs>
+            </configuration>
+        </execution>
+    </executions>
+    <dependencies>
+        <dependency>
+            <groupId>org.jetbrains.kotlin</groupId>
+            <artifactId>kotlin-maven-allopen</artifactId>
+            <version>${kotlinVersion}</version>
+        </dependency>
+    </dependencies>
+</plugin>
+----
diff --git a/src/main/docs/guide/kotest5/usingMockkMocks.adoc b/src/main/docs/guide/kotest5/usingMockkMocks.adoc
new file mode 100644
index 00000000..cc342a0a
--- /dev/null
+++ b/src/main/docs/guide/kotest5/usingMockkMocks.adoc
@@ -0,0 +1,17 @@
+Now let's say you want to replace the implementation with a Mockk. You can do so by defining a method that returns a mock and is annotated with `@MockBean`, for example:
+
+.The MathService specification
+[source,kotlin]
+----
+include::{kotest5tests}/MathMockServiceTest.kt[]
+----
+
+<1> The `@MockBean` annotation is used to indicate the method returns a mock bean. The value to the method is the type being replaced.
+<2> Mockk's `mockk(..)` method creates the actual mock
+<3> The math service proxy is injected into the test
+<4> The call to `getMock` is used to retrieve the underlying mock
+<5> Mockk is used to verify the mock is called
+
+Note that because the bean is a method of the test, it will be active only for the scope of the test. This approach allows you to define beans that are isolated per test class.
+
+IMPORTANT: Because Kotlin uses constructor injection, it's not possible to automatically replace the mock proxy with the mock implementation as is done with the other test implementations. The `getMock` method was created to make retrieving the underlying mock object easier.
diff --git a/src/main/docs/guide/spock/definingAdditionalTestSpecificProperties.adoc b/src/main/docs/guide/spock/definingAdditionalTestSpecificProperties.adoc
new file mode 100644
index 00000000..6d80f7e9
--- /dev/null
+++ b/src/main/docs/guide/spock/definingAdditionalTestSpecificProperties.adoc
@@ -0,0 +1,24 @@
+You can define additional test specific properties using the `@Property` annotation. The following example demonstrates usage:
+
+.Using `@Property`
+[source,java]
+----
+include::{spocktests}/PropertySpec.groovy[]
+----
+
+Note that when a `@Property` is defined at the test method level, it causes a `RefreshEvent` to be triggered which will update any `@ConfigurationProperties` related  to the property.
+
+
+Alternatively you can specify additional `propertySources` in any supported format (YAML, JSON, Java properties file etc.) using the `@MicronautTest` annotation:
+
+.Using `propertySources` stored in files
+[source,java]
+----
+include::{spocktests}/PropertySourceSpec.groovy[]
+----
+
+The above example expects a file located at `src/test/resources/io/micronaut/spock/myprops.properties`. You can however use a prefix to indicate where the file should be searched for. The following are valid values:
+
+* `file:myprops.properties` - A relative path to a file somewhere on the file system.
+* `classpath:myprops.properties` - A file relative to the root of the classpath.
+* `myprops.properties` - A file relative on the classpath relative to the test being run.
diff --git a/src/main/docs/guide/spock/usingRequiresOnTests.adoc b/src/main/docs/guide/spock/usingRequiresOnTests.adoc
new file mode 100644
index 00000000..7656eb18
--- /dev/null
+++ b/src/main/docs/guide/spock/usingRequiresOnTests.adoc
@@ -0,0 +1,12 @@
+Since `@MicronautTest` turns tests into beans themselves, it means you can use the `@Requires` annotation on the test to enable/disable tests. For example:
+
+[source,java]
+----
+@MicronautTest
+@Requires(env = "my-env")
+class RequiresSpec extends Specification {
+    ...
+}
+----
+
+The above test will only run if `my-env` is active (you can activate it by passing the system property `micronaut.environments`).
diff --git a/src/main/docs/guide/spock/writingAMicronautTestWithSpock.adoc b/src/main/docs/guide/spock/writingAMicronautTestWithSpock.adoc
new file mode 100644
index 00000000..e7f1be38
--- /dev/null
+++ b/src/main/docs/guide/spock/writingAMicronautTestWithSpock.adoc
@@ -0,0 +1,27 @@
+Let's take a look at an example using Spock. Consider you have the following interface:
+
+.The MathService Interface
+[source,groovy]
+----
+include::{spocktests}/MathService.java[]
+----
+
+And a simple implementation that computes the value times 4 and is defined as a Micronaut bean:
+
+.The MathService implementation
+[source,groovy]
+----
+include::{spocktests}/MathServiceImpl.groovy[]
+----
+
+You can define the following test to test it:
+
+.The MathService specification
+[source,groovy]
+----
+include::{spocktests}/MathServiceSpec.groovy[]
+----
+
+<1> The test is declared as Micronaut test with `@MicronautTest`
+<2> The `@Inject` annotation is used to inject the bean
+<3> The test itself tests the injected bean