From 8993fa16ec737505c65463a499168c47d52702ee Mon Sep 17 00:00:00 2001 From: Tim Yates Date: Sat, 29 Oct 2022 05:44:40 +0100 Subject: [PATCH] doc: Remove the Kotest docs, now we only support Kotest 5 (#668) These had got left behind after the module removal --- src/main/docs/guide/kotest.adoc | 304 -------------------------------- src/main/docs/guide/toc.yml | 1 - 2 files changed, 305 deletions(-) delete mode 100644 src/main/docs/guide/kotest.adoc diff --git a/src/main/docs/guide/kotest.adoc b/src/main/docs/guide/kotest.adoc deleted file mode 100644 index 424fc8d2c..000000000 --- a/src/main/docs/guide/kotest.adoc +++ /dev/null @@ -1,304 +0,0 @@ -=== Setting up Kotest 4 - -NOTE: A new <> module is now available. This module is maintained for backwards compatibility but new users should consider moving to Kotest 5 - -To get started using Kotest 4 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-kotest:{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+"] ----- - - io.micronaut.test - micronaut-test-kotest - {version} - test - - - io.mockk - mockk - {mockkVersion} - test - - - io.kotest - kotest-runner-junit5-jvm - {kotestVersion} - test - ----- - -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] ----- - - org.apache.maven.plugins - maven-surefire-plugin - 2.22.2 - - - org.junit.jupiter - junit-jupiter-engine - 5.6.2 - - - - - kotlin-maven-plugin - org.jetbrains.kotlin - 1.4.10 - - - all-open - - - - - - - - kapt - - kapt - - - - ${project.baseDir}/src/main/kotlin - - - - io.micronaut - micronaut-inject-java - ${micronaut.version} - - - io.micronaut - micronaut-validation - ${micronaut.version} - - - - - - compile - - compile - - - - ${project.basedir}/src/main/kotlin - ${project.basedir}/src/main/java - - - - - test-kapt - - test-kapt - - - - src/test/kotlin - - - - io.micronaut - micronaut-inject-java - ${micronaut.version} - - - - - - test-compile - - test-compile - - - - ${project.basedir}/src/test/kotlin - ${project.basedir}/target/generated-sources/kapt/test - - - - - - - org.jetbrains.kotlin - kotlin-maven-allopen - ${kotlinVersion} - - - ----- - -=== 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-kotest/src/test/kotlin/io/micronaut/test/kotest/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::{kotesttests}/MathService.kt[] ----- - -And a simple implementation that computes the value times 4 and is defined as Micronaut bean: - -.The MathService implementation -[source,kotlin] ----- -include::{kotesttests}/MathServiceImpl.kt[] ----- - -You can define the following test to test the implementation: - -.The MathService specification -[source,groovy] ----- -include::{kotesttests}/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::{kotesttests}/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::{kotesttests}/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::{kotesttests}/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::{kotesttests}/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::{kotesttests}/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::{kotesttests}/PropertyValueRequiresTest.kt[] ----- diff --git a/src/main/docs/guide/toc.yml b/src/main/docs/guide/toc.yml index ee9ba22cc..473279b3b 100644 --- a/src/main/docs/guide/toc.yml +++ b/src/main/docs/guide/toc.yml @@ -3,7 +3,6 @@ introduction: releaseHistory: Release History spock: Testing with Spock junit5: Testing with JUnit 5 -kotest: Testing with Kotest 4 kotest5: Testing with Kotest 5 restAssured: REST Assured #spek: Testing with Spek