From 84e6e214b4687f217bb34b3f98e88b114ab79cc2 Mon Sep 17 00:00:00 2001 From: Dmitry Aleksandrov Date: Mon, 11 Jul 2022 14:52:59 +0300 Subject: [PATCH 1/5] JUnit5 Testing New style doc --- docs/mp/{testing => }/testing.adoc | 124 ++++++++++++++++++----------- 1 file changed, 79 insertions(+), 45 deletions(-) rename docs/mp/{testing => }/testing.adoc (69%) diff --git a/docs/mp/testing/testing.adoc b/docs/mp/testing.adoc similarity index 69% rename from docs/mp/testing/testing.adoc rename to docs/mp/testing.adoc index 84fe570f307..cbbc7506c7b 100644 --- a/docs/mp/testing/testing.adoc +++ b/docs/mp/testing.adoc @@ -17,12 +17,24 @@ /////////////////////////////////////////////////////////////////////////////// = Testing with JUnit5 -:description: Helidon Testing with JUnit15 +:h1Prefix: MP +:pagename: testing +:description: Helidon Testing with JUnit5 :keywords: helidon, mp, test, testing, junit :feature-name: Testing with JUnit -:rootdir: {docdir}/../.. +:rootdir: {docdir}/.. -include::{rootdir}/includes/mp.adoc[] +== ToC + +- <> +- <> +- <> +- <> +- <> +- <> +- <> + +== Overview Helidon provides built-in test support for CDI testing in JUnit5. @@ -36,11 +48,51 @@ include::{rootdir}/includes/dependencies.adoc[] ---- -== Usage - default +== Usage A test can be annotated with `io.helidon.microprofile.tests.junit5.HelidonTest` annotation to mark it as a CDI test. This annotation will start the CDI container before any test method is invoked, and stop it after the last method is invoked. This annotation also enables injection into the test class itself. +=== Usage - per method CDI container +A test can be annotated as follows: + +`@HelidonTest(resetPerTest = true)` + +This will change the behavior as follows: + +- A new CDI container is created for each test method invocation +- annotations to add config, beans and extension can be added for each method in addition to the class +- you cannot inject fields or constructor parameters of the test class itself (as a single instance is shared by more containers) +- you can add `SeContainer` as a method parameter of any test method and you will get the current container + +=== Usage - configuration +In addition to the `@AddConfig` annotation, you can also use +`@Configuration` to configure additional classpath properties config sources using `configSources`, and to +mark that a custom configuration is desired. +If `@Configuration(useExisting=true)`, the existing (or default) MicroProfile configuration would be used. In this case +it is important to set property `mp.initializer.allow=true` in order CDI container to start, when used with +`@HelidonTest`. +You can set up config in `@BeforeAll` method and register it with `ConfigProviderResolver` using MP Config APIs, and declare +`@Configuration(useExisting=true)`. +Note that this is not compatible with repeatable tests that use method sources that access CDI, as we must delay the CDI +startup to the test class instantiation (which is too late, as the method sources are already invoked by this time). + +*If you want to use method sources that use CDI with repeatable tests, please do not use `@Configuration(useExisting=true)`* + +=== Usage - added parameters and injection types +The following types are available for injection (when a single CDI container is used per test class): + +- `WebTarget` - a JAX-RS client's target configured for the current hostname and port when `helidon-micorprofile-server` is on +the classpath + +The following types are available as method parameters (in any type of Helidon tests): + +- `WebTarget` - a JAX-RS client's target configured for the current hostname and port when `helidon-micorprofile-server` is on +the classpath +- `SeContainer` - the current container instance + +== API + The annotations described in this section are inherited (for the non-repeatable ones), and additive (for repeatable). So if you declare `@DisableDiscovery` on abstract class, all implementations will have discovery disabled, unless you annotate the implementation class with `@DisableDiscovery(false)`. @@ -48,13 +100,23 @@ If you declare `@AddBean` on both abstract class and implementation class, both In addition to this simplification, the following annotations are supported: -- `io.helidon.microprofile.tests.junit5.AddBean` - to add one or more beans to the container - (if not part of a bean archive, or when discovery is disabled) -- `io.helidon.microprofile.tests.junit5.AddExtension` - to add one or more CDI extensions to the container - (if not added through service loader, or when discovery is disabled) -- `io.helidon.microprofile.tests.junit5.AddConfig` - to add one or more configuration properties to MicroProfile config - without the need of creating a `microprofile-config.properties` file -- `io.helidon.microprofile.tests.junit5.DisableDiscovery` - to disable automated discovery of beans and extensions +|=== +|Annotation | Usage + +|`@io.helidon.microprofile.tests.junit5.AddBean` +|to add one or more beans to the container (if not part of a bean archive, or when discovery is disabled) + +|`@io.helidon.microprofile.tests.junit5.AddExtension` +|to add one or more CDI extensions to the container (if not added through service loader, or when discovery is disabled) + +|`@io.helidon.microprofile.tests.junit5.AddConfig` +|to add one or more configuration properties to MicroProfile config without the need of creating a `microprofile-config.properties` file + +|`@io.helidon.microprofile.tests.junit5.DisableDiscovery` +|to disable automated discovery of beans and extensions +|=== + +== Examples [source,java] .Code sample @@ -64,7 +126,7 @@ In addition to this simplification, the following annotations are supported: @AddBean(MyBean.class) @AddExtension(ConfigCdiExtension.class) @AddConfig(key = "app.greeting", value = "TestHello") -class TestNoDiscovery { +class TestExample { @Inject private MyBean myBean; @@ -76,40 +138,12 @@ class TestNoDiscovery { } ---- -== Usage - per method CDI container -A test can be annotated as follows: - -`@HelidonTest(resetPerTest = true)` - -This will change the behavior as follows: - -- A new CDI container is created for each test method invocation -- annotations to add config, beans and extension can be added for each method in addition to the class -- you cannot inject fields or constructor parameters of the test class itself (as a single instance is shared by more containers) -- you can add `SeContainer` as a method parameter of any test method and you will get the current container - -== Usage - configuration -In addition to the `@AddConfig` annotation, you can also use - `@Configuration` to configure additional classpath properties config sources using `configSources`, and to -mark that a custom configuration is desired. -If `@Configuration(useExisting=true)`, the existing (or default) MicroProfile configuration would be used. In this case -it is important to set property `mp.initializer.allow=true` in order CDI container to start, when used with -`@HelidonTest`. -You can set up config in `@BeforeAll` method and register it with `ConfigProviderResolver` using MP Config APIs, and declare -`@Configuration(useExisting=true)`. -Note that this is not compatible with repeatable tests that use method sources that access CDI, as we must delay the CDI -startup to the test class instantiation (which is too late, as the method sources are already invoked by this time). - -*If you want to use method sources that use CDI with repeatable tests, please do not use `@Configuration(useExisting=true)`* +In current example Helidon container will be launched prior test. The _Bean Discovery_ will be disabled. _MyBean_ will be added to the test, so that it can be injected. _ConfigCdiExtension_ will be enabled for this test. And finally, a configuration property will be added using `@AddConfig` annotation. -== Usage - added parameters and injection types -The following types are available for injection (when a single CDI container is used per test class): +== Additional Information -- `WebTarget` - a JAX-RS client's target configured for the current hostname and port when `helidon-micorprofile-server` is on - the classpath +* https://medium.com/helidon/testing-helidon-9df2ea14e22[Official blog article about Helidon and JUnit usage] -The following types are available as method parameters (in any type of Helidon tests): +== Reference -- `WebTarget` - a JAX-RS client's target configured for the current hostname and port when `helidon-micorprofile-server` is on - the classpath -- `SeContainer` - the current container instance \ No newline at end of file +* https://junit.org/junit5/docs/current/user-guide/[JUnit 5 User Guide] From 09f5a6844a5b73179cbd0f44c4760160a987f220 Mon Sep 17 00:00:00 2001 From: Dmitry Aleksandrov Date: Mon, 11 Jul 2022 15:55:15 +0300 Subject: [PATCH 2/5] Minor refactoring. TestNG added. --- docs/mp/{testing => }/testing-ng.adoc | 106 +++++++++++++++++--------- docs/mp/testing.adoc | 6 +- 2 files changed, 72 insertions(+), 40 deletions(-) rename docs/mp/{testing => }/testing-ng.adoc (66%) diff --git a/docs/mp/testing/testing-ng.adoc b/docs/mp/testing-ng.adoc similarity index 66% rename from docs/mp/testing/testing-ng.adoc rename to docs/mp/testing-ng.adoc index a034455e00b..5ea6e114c03 100644 --- a/docs/mp/testing/testing-ng.adoc +++ b/docs/mp/testing-ng.adoc @@ -20,9 +20,18 @@ :description: Helidon Testing with TestNG :keywords: helidon, mp, test, testing, testng :feature-name: Testing with TestNG -:rootdir: {docdir}/../.. +:rootdir: {docdir}/.. -include::{rootdir}/includes/mp.adoc[] +== ToC + +- <> +- <> +- <> +- <> +- <> +- <> + +== Overview Helidon provides built-in test support for CDI testing in TestNG. @@ -42,6 +51,41 @@ A test can be annotated with `io.helidon.microprofile.tests.testng.HelidonTest` CDI test. This annotation will start the CDI container before any test method is invoked, and stop it after the last method is invoked. This annotation also enables injection into the test class itself. +== Usage + +A test can be annotated with `io.helidon.microprofile.tests.testng.HelidonTest` annotation to mark it as a +CDI test. This annotation will start the CDI container before any test method is invoked, and stop it after +the last method is invoked. This annotation also enables injection into the test class itself. + +=== Usage - per method CDI container +A test can be annotated as follows: + +`@HelidonTest(resetPerTest = true)` + +This will change the behavior as follows: + +- A new CDI container is created for each test method invocation +- annotations to add config, beans and extension can be added for each method in addition to the class +- you cannot inject fields or constructor parameters of the test class itself (as a single instance is shared by more containers) + +=== Usage - configuration +In addition to the `@AddConfig` annotation, you can also use +`@Configuration` to configure additional classpath properties config sources using `configSources`, and to +mark that a custom configuration is desired. +If `@Configuration(useExisting=true)`, the existing (or default) MicroProfile configuration would be used. In this case +it is important to set property `mp.initializer.allow=true` in order CDI container to start, when used with +`@HelidonTest`. +You can set up config in `@BeforeAll` method and register it with `ConfigProviderResolver` using MP Config APIs, and declare +`@Configuration(useExisting=true)`. +Note that this is not compatible with repeatable tests that use method sources that access CDI, as we must delay the CDI +startup to the test class instantiation (which is too late, as the method sources are already invoked by this time). + +*If you want to use method sources that use CDI with repeatable tests, please do not use `@Configuration(useExisting=true)`* + +NOTE: Test method parameters are currently not supported. + +== API + The annotations described in this section are inherited (for the non-repeatable ones), and additive (for repeatable). So if you declare `@DisableDiscovery` on abstract class, all implementations will have discovery disabled, unless you annotate the implementation class with `@DisableDiscovery(false)`. @@ -49,13 +93,26 @@ If you declare `@AddBean` on both abstract class and implementation class, both In addition to this simplification, the following annotations are supported: -- `io.helidon.microprofile.tests.testng.AddBean` - to add one or more beans to the container - (if not part of a bean archive, or when discovery is disabled) -- `io.helidon.microprofile.tests.testng.AddExtension` - to add one or more CDI extensions to the container - (if not added through service loader, or when discovery is disabled) -- `io.helidon.microprofile.tests.testng.AddConfig` - to add one or more configuration properties to MicroProfile config - without the need of creating a `microprofile-config.properties` file -- `io.helidon.microprofile.tests.testng.DisableDiscovery` - to disable automated discovery of beans and extensions + +|=== +|Annotation | Usage + +|`@io.helidon.microprofile.tests.testng.AddBean` +|to add one or more beans to the container (if not part of a bean archive, or when discovery is disabled) + +|`@io.helidon.microprofile.tests.testng.AddExtension` +|to add one or more CDI extensions to the container (if not added through service loader, or when discovery is disabled) + +|`@io.helidon.microprofile.tests.testng.AddConfig` +|to add one or more configuration properties to MicroProfile config without the need of creating a `microprofile-config.properties` file + +|`@io.helidon.microprofile.tests.testng.DisableDiscovery` +|to disable automated discovery of beans and extensions +|=== + +== Examples + +In current example Helidon container will be launched prior test. The _Bean Discovery_ will be disabled. _MyBean_ will be added to the test, so that it can be injected. _ConfigCdiExtension_ will be enabled for this test. And finally, a configuration property will be added using `@AddConfig` annotation. [source,java] .Code sample @@ -65,7 +122,7 @@ In addition to this simplification, the following annotations are supported: @AddBean(MyBean.class) @AddExtension(ConfigCdiExtension.class) @AddConfig(key = "app.greeting", value = "TestHello") -class TestNoDiscovery { +class TestExample { @Inject private MyBean myBean; @@ -77,32 +134,7 @@ class TestNoDiscovery { } ---- -== Usage - per method CDI container -A test can be annotated as follows: - -`@HelidonTest(resetPerTest = true)` - -This will change the behavior as follows: - -- A new CDI container is created for each test method invocation -- annotations to add config, beans and extension can be added for each method in addition to the class -- you cannot inject fields or constructor parameters of the test class itself (as a single instance is shared by more containers) - - -== Usage - configuration -In addition to the `@AddConfig` annotation, you can also use - `@Configuration` to configure additional classpath properties config sources using `configSources`, and to -mark that a custom configuration is desired. -If `@Configuration(useExisting=true)`, the existing (or default) MicroProfile configuration would be used. In this case -it is important to set property `mp.initializer.allow=true` in order CDI container to start, when used with -`@HelidonTest`. -You can set up config in `@BeforeAll` method and register it with `ConfigProviderResolver` using MP Config APIs, and declare -`@Configuration(useExisting=true)`. -Note that this is not compatible with repeatable tests that use method sources that access CDI, as we must delay the CDI -startup to the test class instantiation (which is too late, as the method sources are already invoked by this time). - -*If you want to use method sources that use CDI with repeatable tests, please do not use `@Configuration(useExisting=true)`* -== Usage - added parameters and injection types +== Reference -Test method parameters are currently not supported. \ No newline at end of file +* https://testng.org/doc/documentation-main.html[TestNG User Guide] diff --git a/docs/mp/testing.adoc b/docs/mp/testing.adoc index cbbc7506c7b..6f580f06364 100644 --- a/docs/mp/testing.adoc +++ b/docs/mp/testing.adoc @@ -28,8 +28,7 @@ - <> - <> -- <> -- <> +- < - <> - <> - <> @@ -118,6 +117,8 @@ In addition to this simplification, the following annotations are supported: == Examples +In current example Helidon container will be launched prior test. The _Bean Discovery_ will be disabled. _MyBean_ will be added to the test, so that it can be injected. _ConfigCdiExtension_ will be enabled for this test. And finally, a configuration property will be added using `@AddConfig` annotation. + [source,java] .Code sample ---- @@ -138,7 +139,6 @@ class TestExample { } ---- -In current example Helidon container will be launched prior test. The _Bean Discovery_ will be disabled. _MyBean_ will be added to the test, so that it can be injected. _ConfigCdiExtension_ will be enabled for this test. And finally, a configuration property will be added using `@AddConfig` annotation. == Additional Information From 494209282eed7b4f6fd79eb98f42081c9489597b Mon Sep 17 00:00:00 2001 From: Dmitry Aleksandrov Date: Tue, 12 Jul 2022 17:41:56 +0300 Subject: [PATCH 3/5] Minor guide reference fix --- docs/mp/guides/testing-junit5.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/mp/guides/testing-junit5.adoc b/docs/mp/guides/testing-junit5.adoc index d609123f7f2..90e69caced6 100644 --- a/docs/mp/guides/testing-junit5.adoc +++ b/docs/mp/guides/testing-junit5.adoc @@ -261,7 +261,7 @@ This guide demonstrated how to create tests for MicroProfile applications in a J Refer to the following references for additional information: * https://junit.org/junit5/docs/current/user-guide/[JUnit 5 User Guide] -* xref:../testing/testing.adoc[Testing with JUnit 5] +* xref:../testing.adoc[Testing with JUnit 5] From f360010d368a905f10fe255527badc4bdfcd0002 Mon Sep 17 00:00:00 2001 From: Dmitry Aleksandrov Date: Wed, 13 Jul 2022 09:56:54 +0300 Subject: [PATCH 4/5] Fix sitegen --- docs/sitegen.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/sitegen.yaml b/docs/sitegen.yaml index a576e4cff0e..e68807c87f0 100644 --- a/docs/sitegen.yaml +++ b/docs/sitegen.yaml @@ -515,7 +515,6 @@ backend: value: "save" - type: "MENU" title: "Testing" - dir: "testing" glyph: type: "icon" value: "thumbs_up_down" From 58d924e5d74bfaf5edec79d9795280e7a4338d00 Mon Sep 17 00:00:00 2001 From: Dmitry Aleksandrov Date: Wed, 13 Jul 2022 09:56:54 +0300 Subject: [PATCH 5/5] Fix comments --- docs/mp/testing-ng.adoc | 8 ++++---- docs/mp/testing.adoc | 12 ++++++------ 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/mp/testing-ng.adoc b/docs/mp/testing-ng.adoc index 5ea6e114c03..ff83eed50d6 100644 --- a/docs/mp/testing-ng.adoc +++ b/docs/mp/testing-ng.adoc @@ -98,16 +98,16 @@ In addition to this simplification, the following annotations are supported: |Annotation | Usage |`@io.helidon.microprofile.tests.testng.AddBean` -|to add one or more beans to the container (if not part of a bean archive, or when discovery is disabled) +|Used to add one or more beans to the container (if not part of a bean archive, or when discovery is disabled) |`@io.helidon.microprofile.tests.testng.AddExtension` -|to add one or more CDI extensions to the container (if not added through service loader, or when discovery is disabled) +|Used to add one or more CDI extensions to the container (if not added through service loader, or when discovery is disabled) |`@io.helidon.microprofile.tests.testng.AddConfig` -|to add one or more configuration properties to MicroProfile config without the need of creating a `microprofile-config.properties` file +|Used to add one or more configuration properties to MicroProfile config without the need of creating a `microprofile-config.properties` file |`@io.helidon.microprofile.tests.testng.DisableDiscovery` -|to disable automated discovery of beans and extensions +|Used to disable automated discovery of beans and extensions |=== == Examples diff --git a/docs/mp/testing.adoc b/docs/mp/testing.adoc index 6f580f06364..c540f2f1049 100644 --- a/docs/mp/testing.adoc +++ b/docs/mp/testing.adoc @@ -24,11 +24,11 @@ :feature-name: Testing with JUnit :rootdir: {docdir}/.. -== ToC +== Contents - <> - <> -- < +- <> - <> - <> - <> @@ -103,15 +103,15 @@ In addition to this simplification, the following annotations are supported: |Annotation | Usage |`@io.helidon.microprofile.tests.junit5.AddBean` -|to add one or more beans to the container (if not part of a bean archive, or when discovery is disabled) +|Used to add one or more beans to the container (if not part of a bean archive, or when discovery is disabled) |`@io.helidon.microprofile.tests.junit5.AddExtension` -|to add one or more CDI extensions to the container (if not added through service loader, or when discovery is disabled) +|Used to add one or more CDI extensions to the container (if not added through service loader, or when discovery is disabled) |`@io.helidon.microprofile.tests.junit5.AddConfig` -|to add one or more configuration properties to MicroProfile config without the need of creating a `microprofile-config.properties` file +|Used to add one or more configuration properties to MicroProfile config without the need of creating a `microprofile-config.properties` file -|`@io.helidon.microprofile.tests.junit5.DisableDiscovery` +|Used `@io.helidon.microprofile.tests.junit5.DisableDiscovery` |to disable automated discovery of beans and extensions |===