Skip to content

Commit 1d33682

Browse files
Captain1653Captain1653
authored
4.x: Add docs about ability to use HelidonTest in a meta-annotation (helidon-io#9944) (helidon-io#9978)
* 4.x: Add docs about ability to use HelidonTest in a meta-annotation (helidon-io#9944) * Remove empty lines in snippets * Add method-level meta-annotation examples and tests * Fix identical names in code snippets
1 parent 2268b91 commit 1d33682

8 files changed

Lines changed: 327 additions & 4 deletions

File tree

‎docs/src/main/asciidoc/mp/testing/testing-ng.adoc‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,22 @@ I.e. By default, the test instance is re-used between test methods.
6969
7070
NOTE: The test instance is not re-used between CDI container, using a dedicated CDI container implies a new test instance
7171
72+
=== Using meta-annotations
73+
Meta-annotations are supported on both test classes and test methods and can be used as a composition mechanism.
74+
75+
[source,java]
76+
.Class-level meta-annotation
77+
----
78+
include::{sourcedir}/mp/testing/TestingNgSnippets.java[tag=snippet_2, indent=0]
79+
----
80+
81+
[source,java]
82+
.Method-level meta-annotation
83+
----
84+
include::{sourcedir}/mp/testing/TestingNgSnippets.java[tag=snippet_3, indent=0]
85+
----
86+
1. `org.testng.annotations.Test` is not inheritable and should be placed on methods
87+
7288
== API
7389
7490
include::{rootdir}/mp/testing/testing-common.adoc[tag=api]

‎docs/src/main/asciidoc/mp/testing/testing.adoc‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,21 @@ NOTE: The test instance is not re-used between CDI container, using a dedicated
8989
include::{sourcedir}/mp/testing/TestingJunit5Snippets.java[tag=snippet_2, indent=0]
9090
----
9191
92+
=== Using meta-annotations
93+
Meta-annotations are supported on both test classes and test methods and can be used as a composition mechanism.
94+
95+
[source,java]
96+
.Class-level meta-annotation example
97+
----
98+
include::{sourcedir}/mp/testing/TestingJunit5Snippets.java[tag=snippet_4, indent=0]
99+
----
100+
101+
[source,java]
102+
.Method-level meta-annotation example
103+
----
104+
include::{sourcedir}/mp/testing/TestingJunit5Snippets.java[tag=snippet_5, indent=0]
105+
----
106+
92107
== API
93108
94109
include::{rootdir}/mp/testing/testing-common.adoc[tag=api]

‎docs/src/main/java/io/helidon/docs/mp/testing/TestingJunit5Snippets.java‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,14 @@
1616
package io.helidon.docs.mp.testing;
1717

1818
import io.helidon.microprofile.testing.junit5.HelidonTest;
19+
import io.helidon.microprofile.testing.AddBean;
20+
import io.helidon.microprofile.testing.DisableDiscovery;
21+
22+
import java.lang.annotation.Annotation;
23+
import java.lang.annotation.ElementType;
24+
import java.lang.annotation.Retention;
25+
import java.lang.annotation.RetentionPolicy;
26+
import java.lang.annotation.Target;
1927

2028
import jakarta.annotation.Priority;
2129
import jakarta.enterprise.context.ApplicationScoped;
@@ -113,4 +121,49 @@ String test() {
113121
}
114122
// end::snippet_3[]
115123
}
124+
125+
class Snippet4 {
126+
127+
class FirstBean {}
128+
129+
class SecondBean {}
130+
131+
// tag::snippet_4[]
132+
@HelidonTest
133+
@AddBean(FirstBean.class)
134+
@AddBean(SecondBean.class)
135+
@DisableDiscovery
136+
@Target(ElementType.TYPE)
137+
@Retention(RetentionPolicy.RUNTIME)
138+
public @interface CustomMetaAnnotation {
139+
}
140+
141+
@CustomMetaAnnotation
142+
class AnnotationOnClass {
143+
}
144+
// end::snippet_4[]
145+
146+
// tag::snippet_5[]
147+
@Test
148+
@AddBean(FirstBean.class)
149+
@AddBean(SecondBean.class)
150+
@DisableDiscovery
151+
@Target(ElementType.METHOD)
152+
@Retention(RetentionPolicy.RUNTIME)
153+
public @interface MyTestMethod {
154+
}
155+
156+
@HelidonTest
157+
class AnnotationOnMethod {
158+
159+
@MyTestMethod
160+
void testOne() {
161+
}
162+
163+
@MyTestMethod
164+
void testTwo() {
165+
}
166+
}
167+
// end::snippet_5[]
168+
}
116169
}

‎docs/src/main/java/io/helidon/docs/mp/testing/TestingNgSnippets.java‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,14 @@
1616
package io.helidon.docs.mp.testing;
1717

1818
import io.helidon.microprofile.testing.testng.HelidonTest;
19+
import io.helidon.microprofile.testing.AddBean;
20+
import io.helidon.microprofile.testing.DisableDiscovery;
21+
22+
import java.lang.annotation.Annotation;
23+
import java.lang.annotation.ElementType;
24+
import java.lang.annotation.Retention;
25+
import java.lang.annotation.RetentionPolicy;
26+
import java.lang.annotation.Target;
1927

2028
import jakarta.annotation.Priority;
2129
import jakarta.enterprise.context.ApplicationScoped;
@@ -89,4 +97,50 @@ String test() {
8997
}
9098
// end::snippet_1[]
9199
}
100+
101+
class Snippet2 {
102+
103+
class FirstBean {}
104+
105+
class SecondBean {}
106+
107+
// tag::snippet_2[]
108+
@HelidonTest
109+
@AddBean(FirstBean.class)
110+
@AddBean(SecondBean.class)
111+
@DisableDiscovery
112+
@Target(ElementType.TYPE)
113+
@Retention(RetentionPolicy.RUNTIME)
114+
public @interface CustomMetaAnnotation {
115+
}
116+
117+
@CustomMetaAnnotation
118+
class AnnotationOnClass {
119+
}
120+
// end::snippet_2[]
121+
122+
// tag::snippet_3[]
123+
@AddBean(FirstBean.class)
124+
@AddBean(SecondBean.class)
125+
@DisableDiscovery
126+
@Target(ElementType.METHOD)
127+
@Retention(RetentionPolicy.RUNTIME)
128+
public @interface MyTestMethod {
129+
}
130+
131+
@HelidonTest
132+
class AnnotationOnMethod {
133+
134+
@Test // <1>
135+
@MyTestMethod
136+
void testOne() {
137+
}
138+
139+
@Test // <1>
140+
@MyTestMethod
141+
void testTwo() {
142+
}
143+
}
144+
// end::snippet_3[]
145+
}
92146
}

microprofile/tests/testing/junit5/src/test/java/io/helidon/microprofile/tests/testing/junit5/TestMetaAnnotation.java renamed to microprofile/tests/testing/junit5/src/test/java/io/helidon/microprofile/tests/testing/junit5/TestClassLevelMetaAnnotation.java

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -33,8 +33,8 @@
3333
import static org.hamcrest.CoreMatchers.is;
3434
import static org.hamcrest.MatcherAssert.assertThat;
3535

36-
@TestMetaAnnotation.MetaAnnotation
37-
class TestMetaAnnotation {
36+
@TestClassLevelMetaAnnotation.MetaAnnotation
37+
class TestClassLevelMetaAnnotation {
3838

3939
@Inject
4040
MyBean bean;

‎microprofile/tests/testing/junit5/src/test/java/io/helidon/microprofile/tests/testing/junit5/TestMethodLevelMetaAnnotation.java‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
/*
2+
* Copyright (c) 2025 Oracle and/or its affiliates.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
package io.helidon.microprofile.tests.testing.junit5;
18+
19+
import io.helidon.microprofile.testing.AddBean;
20+
import io.helidon.microprofile.testing.AddConfig;
21+
import io.helidon.microprofile.testing.AddConfigBlock;
22+
import io.helidon.microprofile.testing.Configuration;
23+
import jakarta.inject.Inject;
24+
25+
import java.lang.annotation.Retention;
26+
import java.lang.annotation.RetentionPolicy;
27+
import java.lang.annotation.ElementType;
28+
import java.lang.annotation.Target;
29+
30+
import io.helidon.microprofile.testing.junit5.HelidonTest;
31+
32+
import org.eclipse.microprofile.config.inject.ConfigProperty;
33+
import org.junit.jupiter.api.Test;
34+
35+
import static org.hamcrest.CoreMatchers.is;
36+
import static org.hamcrest.MatcherAssert.assertThat;
37+
38+
@HelidonTest
39+
class TestMethodLevelMetaAnnotation {
40+
41+
@Inject
42+
private MyBean bean;
43+
44+
@Inject
45+
@ConfigProperty(name = "some.key1")
46+
private String value1;
47+
48+
@Inject
49+
@ConfigProperty(name = "some.key2")
50+
private String value2;
51+
52+
@Inject
53+
@ConfigProperty(name = "some.key")
54+
private String someKey;
55+
56+
@Inject
57+
@ConfigProperty(name = "another.key")
58+
private String anotherKey;
59+
60+
@Inject
61+
@ConfigProperty(name = "second-key")
62+
private String anotherValue;
63+
64+
@MyTestMethod
65+
void testAnnotationComposition() {
66+
assertThat(bean.hello(), is("hello"));
67+
assertThat(value1, is("some.value1"));
68+
assertThat(value2, is("some.value2"));
69+
assertThat(someKey, is("some.value"));
70+
assertThat(anotherKey, is("another.value"));
71+
assertThat(anotherValue, is("test-custom-config-second-value"));
72+
}
73+
74+
75+
@Test
76+
@Target(ElementType.METHOD)
77+
@Retention(RetentionPolicy.RUNTIME)
78+
@AddBean(MyBean.class)
79+
@AddConfigBlock("""
80+
some.key1=some.value1
81+
some.key2=some.value2
82+
""")
83+
@AddConfig(key = "second-key", value = "test-custom-config-second-value")
84+
@Configuration(configSources = {"testConfigSources.properties", "testConfigSources.yaml"})
85+
public @interface MyTestMethod { }
86+
87+
88+
static class MyBean {
89+
public String hello() {
90+
return "hello";
91+
}
92+
}
93+
94+
}

microprofile/tests/testing/testng/src/test/java/io/helidon/microprofile/tests/testing/testng/TestMetaAnnotation.java renamed to microprofile/tests/testing/testng/src/test/java/io/helidon/microprofile/tests/testing/testng/TestClassLevelMetaAnnotation.java

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -33,8 +33,8 @@
3333
import org.eclipse.microprofile.config.inject.ConfigProperty;
3434
import org.testng.annotations.Test;
3535

36-
@TestMetaAnnotation.MetaAnnotation
37-
public class TestMetaAnnotation {
36+
@TestClassLevelMetaAnnotation.MetaAnnotation
37+
public class TestClassLevelMetaAnnotation {
3838

3939
@Inject
4040
MyBean bean;

‎microprofile/tests/testing/testng/src/test/java/io/helidon/microprofile/tests/testing/testng/TestMethodLevelMetaAnnotation.java‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
/*
2+
* Copyright (c) 2025 Oracle and/or its affiliates.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
package io.helidon.microprofile.tests.testing.testng;
18+
19+
import io.helidon.microprofile.testing.AddBean;
20+
import io.helidon.microprofile.testing.AddConfig;
21+
import io.helidon.microprofile.testing.AddConfigBlock;
22+
import io.helidon.microprofile.testing.Configuration;
23+
import io.helidon.microprofile.testing.testng.HelidonTest;
24+
import jakarta.inject.Inject;
25+
import org.eclipse.microprofile.config.inject.ConfigProperty;
26+
import org.testng.annotations.Test;
27+
28+
import java.lang.annotation.ElementType;
29+
import java.lang.annotation.Retention;
30+
import java.lang.annotation.RetentionPolicy;
31+
import java.lang.annotation.Target;
32+
33+
import static org.hamcrest.CoreMatchers.is;
34+
import static org.hamcrest.MatcherAssert.assertThat;
35+
36+
@HelidonTest
37+
public class TestMethodLevelMetaAnnotation {
38+
39+
@Inject
40+
private MyBean bean;
41+
42+
@Inject
43+
@ConfigProperty(name = "some.key1")
44+
private String value1;
45+
46+
@Inject
47+
@ConfigProperty(name = "some.key2")
48+
private String value2;
49+
50+
@Inject
51+
@ConfigProperty(name = "some.key")
52+
private String someKey;
53+
54+
@Inject
55+
@ConfigProperty(name = "another.key")
56+
private String anotherKey;
57+
58+
@Inject
59+
@ConfigProperty(name = "second-key")
60+
private String anotherValue;
61+
62+
@Test // org.testng.annotations.Test is not inheritable and can't be used in meta-annotation
63+
@MyTestMethod
64+
void testAnnotationComposition() {
65+
assertThat(bean.hello(), is("hello"));
66+
assertThat(value1, is("some.value1"));
67+
assertThat(value2, is("some.value2"));
68+
assertThat(someKey, is("some.value"));
69+
assertThat(anotherKey, is("another.value"));
70+
assertThat(anotherValue, is("test-custom-config-second-value"));
71+
}
72+
73+
74+
@Target(ElementType.METHOD)
75+
@Retention(RetentionPolicy.RUNTIME)
76+
@AddBean(MyBean.class)
77+
@AddConfigBlock("""
78+
some.key1=some.value1
79+
some.key2=some.value2
80+
""")
81+
@AddConfig(key = "second-key", value = "test-custom-config-second-value")
82+
@Configuration(configSources = {"testConfigSources.properties", "testConfigSources.yaml"})
83+
public @interface MyTestMethod { }
84+
85+
86+
static class MyBean {
87+
public String hello() {
88+
return "hello";
89+
}
90+
}
91+
}

0 commit comments

Comments
 (0)