You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@sling.apache.org by "adamcin (via GitHub)" <gi...@apache.org> on 2023/10/11 02:24:11 UTC

[PR] add documentation for OSGi Mocks Config Annotations [sling-site]

adamcin opened a new pull request, #135:
URL: https://github.com/apache/sling-site/pull/135

   this is documentation for features introduced by https://github.com/apache/sling-org-apache-sling-testing-osgi-mock/pull/31


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@sling.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] SLING-12038 add documentation for OSGi Mocks Config Annotations [sling-site]

Posted by "adamcin (via GitHub)" <gi...@apache.org>.
adamcin commented on code in PR #135:
URL: https://github.com/apache/sling-site/pull/135#discussion_r1355134428


##########
src/main/jbake/content/documentation/development/osgi-mock.md:
##########
@@ -231,3 +235,192 @@ More examples:
 [mockito-junit5-extension]: https://www.javadoc.io/page/org.mockito/mockito-junit-jupiter/latest/org/mockito/junit/jupiter/MockitoExtension.html
 [caconfig-mock-plugin]: https://github.com/apache/sling-org-apache-sling-testing-caconfig-mock-plugin/blob/master/src/main/java/org/apache/sling/testing/mock/caconfig/ContextPlugins.java
 [caconfig-mock-plugin-test]: https://github.com/apache/sling-org-apache-sling-testing-caconfig-mock-plugin/blob/master/src/test/java/org/apache/sling/testing/mock/caconfig/ContextPluginsTest.java
+
+## Config Annotations
+
+Since osgi-mock 3.4.0, it is possible to use the provided `@UpdateConfig` and `@ApplyConfig` annotations to directly construct component property type ("Config") annotations for use as first-class values in unit tests. Both osgi-mock.junit4 and osgi-mock.junit5 provide different approaches for convenient reflection and injection of these annotations.
+
+### JUnit 5: OSGi Config Parameters JUnit Extension
+
+Given an OSGi component class that looks like this:
+
+    #!java
+    import org.osgi.service.component.annotations.Activate;
+    import org.osgi.service.component.annotations.Component;
+    import java.lang.annotation.Retention;
+    import java.lang.annotation.RetentionPolicy;
+
+    @Component(service = MyService.class)
+    public class MyService {
+
+        // specify runtime retention to allow for direct usage in unit tests 
+        @Retention(RetentionPolicy.RUNTIME)
+        public @interface Config {
+            String path() default "/";
+        }
+
+        private final String path;
+
+        @Activate
+        public MyService(Config config) {
+            this.path = config.path();
+        }
+
+        public String getPath() {
+            return path;
+        }
+    }
+
+A companion unit test in JUnit 5 might look like this:
+
+    #!java
+    import org.apache.sling.testing.mock.osgi.config.annotations.ApplyConfig;
+    import org.apache.sling.testing.mock.osgi.config.annotations.UpdateConfig;
+    import org.apache.sling.testing.mock.osgi.junit5.OsgiConfigParametersExtension;
+    import org.junit.jupiter.api.Test;
+    import org.junit.jupiter.api.extension.ExtendWith;
+
+    import static org.junit.jupiter.api.Assertions.assertEquals;
+
+    @ExtendWith(OsgiConfigParametersExtension.class)
+    class MyServiceTest {
+
+        @Test
+        @MyService.Config(path = "/apps") // requires @Retention(RetentionPolicy.RUNTIME)
+        void getPath(MyService.Config config) {
+            MyService myService = new MyService(config);
+            assertEquals("/apps", myService.getPath());
+        }
+
+        @Test
+        @ApplyConfig(type = MyService.Config.class, property = "path=/libs")
+        void getPath_applyConfig(MyService.Config config) {
+            MyService myService = new MyService(config);
+            assertEquals("/libs", myService.getPath());
+        }
+
+        @Test
+        @UpdateConfig(pid = "new-pid", property = "path=/content")
+        @ApplyConfig(pid = "new-pid", type = MyService.Config.class)
+        void getPath_updateConfig(MyService.Config config) {
+            MyService myService = new MyService(config);
+            assertEquals("/content", myService.getPath());
+        }
+    }
+
+
+### JUnit 4: Config Collector JUnit Rule
+
+Given the same example OSGi component from before:
+
+    #!java
+    import org.osgi.service.component.annotations.Activate;
+    import org.osgi.service.component.annotations.Component;
+    import java.lang.annotation.Retention;
+    import java.lang.annotation.RetentionPolicy;
+
+    @Component(service = MyService.class)
+    public class MyService {
+
+        // specify runtime retention to allow for direct usage in unit tests 
+        @Retention(RetentionPolicy.RUNTIME)
+        public @interface Config {
+            String path() default "/";
+        }
+
+        private final String path;
+
+        @Activate
+        public MyService(Config config) {
+            this.path = config.path();
+        }
+
+        public String getPath() {
+            return path;
+        }
+    }
+
+
+A companion unit test in JUnit 4 might look like this:
+
+    #!java
+    import org.apache.sling.testing.mock.osgi.config.annotations.ApplyConfig;
+    import org.apache.sling.testing.mock.osgi.config.annotations.UpdateConfig;
+    import org.apache.sling.testing.mock.osgi.junit.ConfigCollector;
+    import org.apache.sling.testing.mock.osgi.junit.OsgiContext;
+    import org.apache.sling.testing.mock.osgi.junit.OsgiContextBuilder;
+    import org.junit.Rule;
+
+    import static org.junit.Assert.assertEquals;
+
+    public class MyServiceTest {
+
+        @Rule
+        public OsgiContext context = new OsgiContextBuilder().build();
+
+        @Rule
+        public ConfigCollector configs = new ConfigCollector(context, MyService.Config.class);
+
+        @Test
+        @MyService.Config(path = "/apps") // requires @Retention(RetentionPolicy.RUNTIME)
+        public void myServiceMethod() {
+            MyService.Config config = configs.configStream(MyService.Config.class)
+                    .findFirst()
+                    .orElseThrow();
+            MyService myService = new MyService(config);
+            assertEquals("/apps", myService.getPath());
+        }
+
+        @Test
+        @ApplyConfig(type = MyService.Config.class, property = "path=/libs")
+        public void myServiceMethod() {
+            MyService.Config config = configs.configStream(MyService.Config.class)
+                    .findFirst()
+                    .orElseThrow();
+            MyService myService = new MyService(config);
+            assertEquals("/libs", myService.getPath());
+        }
+
+        @Test
+        @UpdateConfig(pid = "new-pid", property = "path=/content")
+        @ApplyConfig(pid = "new-pid", type = MyService.Config.class)
+        public void myServiceMethod() {
+            MyService.Config config = configs.configStream(MyService.Config.class)
+                    .findFirst()
+                    .orElseThrow();
+            MyService myService = new MyService(config);
+            assertEquals("/content", myService.getPath());
+        }
+    }
+
+### Config Annotations: SlingContext Compatibility
+
+The OSGi Mock Config Annotations and JUnit4/JUnit5 extensions are compatible with the `SlingContext` from Sling Mocks and other libraries that provide extensions of `OsgiContextImpl`.
+
+To setup a project with Sling Mocks and OSGi Mocks Config Annotations, adjust the project pom.xml for either JUnit4 or JUnit5:
+
+For JUnit 5:
+
+    #!xml
+    <dependency>

Review Comment:
   I had checked `sling-mock.junit5` for a dependency on `osgi-mock.junit5`, but [it doesn't have one](https://github.com/apache/sling-org-apache-sling-testing-sling-mock/blob/852f247e0c6ef7ed92f8e2684ea1d15c41e1a672/junit5/pom.xml#L37-L49). I just assumed that `sling-mock.junit4` was the same situation, but upon checking it now, I see that [it does have an osgi-mock.junit4 dependency](https://github.com/apache/sling-org-apache-sling-testing-sling-mock/blob/852f247e0c6ef7ed92f8e2684ea1d15c41e1a672/junit4/pom.xml#L51-L55). 
   
   So really, no additional maven configuration should be necessary for use of Config Annotations with either `sling-mock.junit4` or `sling-mock.junit5`, but we'll need to update the `sling-mock.junit5` pom.xml so that it follows this expectation. 
   
   It looks like the same situation with [aem-mock.junit4](https://github.com/wcm-io/io.wcm.testing.aem-mock/blob/8606c9d8b98cd844ba79b31b2fc56b4706b898e0/junit4/pom.xml#L61-L85) and [aem-mock.junit5](https://github.com/wcm-io/io.wcm.testing.aem-mock/blob/8606c9d8b98cd844ba79b31b2fc56b4706b898e0/junit5/pom.xml#L68), so a similar change should be applied to `aem-mock.junit5`'s pom.xml.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@sling.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] SLING-12038 add documentation for OSGi Mocks Config Annotations [sling-site]

Posted by "stefanseifert (via GitHub)" <gi...@apache.org>.
stefanseifert merged PR #135:
URL: https://github.com/apache/sling-site/pull/135


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@sling.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] SLING-12038 add documentation for OSGi Mocks Config Annotations [sling-site]

Posted by "adamcin (via GitHub)" <gi...@apache.org>.
adamcin commented on code in PR #135:
URL: https://github.com/apache/sling-site/pull/135#discussion_r1355897991


##########
src/main/jbake/content/documentation/development/osgi-mock.md:
##########
@@ -231,3 +235,192 @@ More examples:
 [mockito-junit5-extension]: https://www.javadoc.io/page/org.mockito/mockito-junit-jupiter/latest/org/mockito/junit/jupiter/MockitoExtension.html
 [caconfig-mock-plugin]: https://github.com/apache/sling-org-apache-sling-testing-caconfig-mock-plugin/blob/master/src/main/java/org/apache/sling/testing/mock/caconfig/ContextPlugins.java
 [caconfig-mock-plugin-test]: https://github.com/apache/sling-org-apache-sling-testing-caconfig-mock-plugin/blob/master/src/test/java/org/apache/sling/testing/mock/caconfig/ContextPluginsTest.java
+
+## Config Annotations
+
+Since osgi-mock 3.4.0, it is possible to use the provided `@UpdateConfig` and `@ApplyConfig` annotations to directly construct component property type ("Config") annotations for use as first-class values in unit tests. Both osgi-mock.junit4 and osgi-mock.junit5 provide different approaches for convenient reflection and injection of these annotations.

Review Comment:
   @stefanseifert I decided to rename `@ApplyConfig` to `@ConfigType` after spending time on the javadocs and refactoring the related logic out of OsgiContextImpl. I've added the guidance to the page. 



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@sling.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] add documentation for OSGi Mocks Config Annotations [sling-site]

Posted by "adamcin (via GitHub)" <gi...@apache.org>.
adamcin commented on PR #135:
URL: https://github.com/apache/sling-site/pull/135#issuecomment-1756639452

   @stefanseifert @klcodanr @kwin Updated site docs in this PR.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@sling.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] SLING-12038 add documentation for OSGi Mocks Config Annotations [sling-site]

Posted by "stefanseifert (via GitHub)" <gi...@apache.org>.
stefanseifert commented on code in PR #135:
URL: https://github.com/apache/sling-site/pull/135#discussion_r1355154305


##########
src/main/jbake/content/documentation/development/osgi-mock.md:
##########
@@ -231,3 +235,192 @@ More examples:
 [mockito-junit5-extension]: https://www.javadoc.io/page/org.mockito/mockito-junit-jupiter/latest/org/mockito/junit/jupiter/MockitoExtension.html
 [caconfig-mock-plugin]: https://github.com/apache/sling-org-apache-sling-testing-caconfig-mock-plugin/blob/master/src/main/java/org/apache/sling/testing/mock/caconfig/ContextPlugins.java
 [caconfig-mock-plugin-test]: https://github.com/apache/sling-org-apache-sling-testing-caconfig-mock-plugin/blob/master/src/test/java/org/apache/sling/testing/mock/caconfig/ContextPluginsTest.java
+
+## Config Annotations
+
+Since osgi-mock 3.4.0, it is possible to use the provided `@UpdateConfig` and `@ApplyConfig` annotations to directly construct component property type ("Config") annotations for use as first-class values in unit tests. Both osgi-mock.junit4 and osgi-mock.junit5 provide different approaches for convenient reflection and injection of these annotations.
+
+### JUnit 5: OSGi Config Parameters JUnit Extension
+
+Given an OSGi component class that looks like this:
+
+    #!java
+    import org.osgi.service.component.annotations.Activate;
+    import org.osgi.service.component.annotations.Component;
+    import java.lang.annotation.Retention;
+    import java.lang.annotation.RetentionPolicy;
+
+    @Component(service = MyService.class)
+    public class MyService {
+
+        // specify runtime retention to allow for direct usage in unit tests 
+        @Retention(RetentionPolicy.RUNTIME)
+        public @interface Config {
+            String path() default "/";
+        }
+
+        private final String path;
+
+        @Activate
+        public MyService(Config config) {
+            this.path = config.path();
+        }
+
+        public String getPath() {
+            return path;
+        }
+    }
+
+A companion unit test in JUnit 5 might look like this:
+
+    #!java
+    import org.apache.sling.testing.mock.osgi.config.annotations.ApplyConfig;
+    import org.apache.sling.testing.mock.osgi.config.annotations.UpdateConfig;
+    import org.apache.sling.testing.mock.osgi.junit5.OsgiConfigParametersExtension;
+    import org.junit.jupiter.api.Test;
+    import org.junit.jupiter.api.extension.ExtendWith;
+
+    import static org.junit.jupiter.api.Assertions.assertEquals;
+
+    @ExtendWith(OsgiConfigParametersExtension.class)
+    class MyServiceTest {
+
+        @Test
+        @MyService.Config(path = "/apps") // requires @Retention(RetentionPolicy.RUNTIME)
+        void getPath(MyService.Config config) {
+            MyService myService = new MyService(config);
+            assertEquals("/apps", myService.getPath());
+        }
+
+        @Test
+        @ApplyConfig(type = MyService.Config.class, property = "path=/libs")
+        void getPath_applyConfig(MyService.Config config) {
+            MyService myService = new MyService(config);
+            assertEquals("/libs", myService.getPath());
+        }
+
+        @Test
+        @UpdateConfig(pid = "new-pid", property = "path=/content")
+        @ApplyConfig(pid = "new-pid", type = MyService.Config.class)
+        void getPath_updateConfig(MyService.Config config) {
+            MyService myService = new MyService(config);
+            assertEquals("/content", myService.getPath());
+        }
+    }
+
+
+### JUnit 4: Config Collector JUnit Rule
+
+Given the same example OSGi component from before:
+
+    #!java
+    import org.osgi.service.component.annotations.Activate;
+    import org.osgi.service.component.annotations.Component;
+    import java.lang.annotation.Retention;
+    import java.lang.annotation.RetentionPolicy;
+
+    @Component(service = MyService.class)
+    public class MyService {
+
+        // specify runtime retention to allow for direct usage in unit tests 
+        @Retention(RetentionPolicy.RUNTIME)
+        public @interface Config {
+            String path() default "/";
+        }
+
+        private final String path;
+
+        @Activate
+        public MyService(Config config) {
+            this.path = config.path();
+        }
+
+        public String getPath() {
+            return path;
+        }
+    }
+
+
+A companion unit test in JUnit 4 might look like this:
+
+    #!java
+    import org.apache.sling.testing.mock.osgi.config.annotations.ApplyConfig;
+    import org.apache.sling.testing.mock.osgi.config.annotations.UpdateConfig;
+    import org.apache.sling.testing.mock.osgi.junit.ConfigCollector;
+    import org.apache.sling.testing.mock.osgi.junit.OsgiContext;
+    import org.apache.sling.testing.mock.osgi.junit.OsgiContextBuilder;
+    import org.junit.Rule;
+
+    import static org.junit.Assert.assertEquals;
+
+    public class MyServiceTest {
+
+        @Rule
+        public OsgiContext context = new OsgiContextBuilder().build();
+
+        @Rule
+        public ConfigCollector configs = new ConfigCollector(context, MyService.Config.class);
+
+        @Test
+        @MyService.Config(path = "/apps") // requires @Retention(RetentionPolicy.RUNTIME)
+        public void myServiceMethod() {
+            MyService.Config config = configs.configStream(MyService.Config.class)
+                    .findFirst()
+                    .orElseThrow();
+            MyService myService = new MyService(config);
+            assertEquals("/apps", myService.getPath());
+        }
+
+        @Test
+        @ApplyConfig(type = MyService.Config.class, property = "path=/libs")
+        public void myServiceMethod() {
+            MyService.Config config = configs.configStream(MyService.Config.class)
+                    .findFirst()
+                    .orElseThrow();
+            MyService myService = new MyService(config);
+            assertEquals("/libs", myService.getPath());
+        }
+
+        @Test
+        @UpdateConfig(pid = "new-pid", property = "path=/content")
+        @ApplyConfig(pid = "new-pid", type = MyService.Config.class)
+        public void myServiceMethod() {
+            MyService.Config config = configs.configStream(MyService.Config.class)
+                    .findFirst()
+                    .orElseThrow();
+            MyService myService = new MyService(config);
+            assertEquals("/content", myService.getPath());
+        }
+    }
+
+### Config Annotations: SlingContext Compatibility
+
+The OSGi Mock Config Annotations and JUnit4/JUnit5 extensions are compatible with the `SlingContext` from Sling Mocks and other libraries that provide extensions of `OsgiContextImpl`.
+
+To setup a project with Sling Mocks and OSGi Mocks Config Annotations, adjust the project pom.xml for either JUnit4 or JUnit5:
+
+For JUnit 5:
+
+    #!xml
+    <dependency>

Review Comment:
   ah, you're right. each *-mock.junit4/5 module comes with their own specific code, and the dependency chain goes only over the *-mock.core modules which does not contain the actual junit4/5 code.
   
   however, it's still not recommended to include multiple *-mock.junit4/5 modules of osgi/sling/aem in the same project (also it works fine technically), as you usually need only one of them with the fitting (Osgi|Sling|Aem)Context implementation of your choice.
   
   maybe it would make sense to put the new annotations in a separate module for junit5 and 4 in osgi-mock, which then is included as dependency in the other ones. but let's finish the basic discussion in https://github.com/apache/sling-org-apache-sling-testing-osgi-mock/pull/31 first.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@sling.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] SLING-12038 add documentation for OSGi Mocks Config Annotations [sling-site]

Posted by "stefanseifert (via GitHub)" <gi...@apache.org>.
stefanseifert commented on code in PR #135:
URL: https://github.com/apache/sling-site/pull/135#discussion_r1354537308


##########
src/main/jbake/content/documentation/development/osgi-mock.md:
##########
@@ -231,3 +235,192 @@ More examples:
 [mockito-junit5-extension]: https://www.javadoc.io/page/org.mockito/mockito-junit-jupiter/latest/org/mockito/junit/jupiter/MockitoExtension.html
 [caconfig-mock-plugin]: https://github.com/apache/sling-org-apache-sling-testing-caconfig-mock-plugin/blob/master/src/main/java/org/apache/sling/testing/mock/caconfig/ContextPlugins.java
 [caconfig-mock-plugin-test]: https://github.com/apache/sling-org-apache-sling-testing-caconfig-mock-plugin/blob/master/src/test/java/org/apache/sling/testing/mock/caconfig/ContextPluginsTest.java
+
+## Config Annotations
+
+Since osgi-mock 3.4.0, it is possible to use the provided `@UpdateConfig` and `@ApplyConfig` annotations to directly construct component property type ("Config") annotations for use as first-class values in unit tests. Both osgi-mock.junit4 and osgi-mock.junit5 provide different approaches for convenient reflection and injection of these annotations.
+
+### JUnit 5: OSGi Config Parameters JUnit Extension
+
+Given an OSGi component class that looks like this:
+
+    #!java
+    import org.osgi.service.component.annotations.Activate;
+    import org.osgi.service.component.annotations.Component;
+    import java.lang.annotation.Retention;
+    import java.lang.annotation.RetentionPolicy;
+
+    @Component(service = MyService.class)
+    public class MyService {
+
+        // specify runtime retention to allow for direct usage in unit tests 
+        @Retention(RetentionPolicy.RUNTIME)
+        public @interface Config {
+            String path() default "/";
+        }
+
+        private final String path;
+
+        @Activate
+        public MyService(Config config) {
+            this.path = config.path();
+        }
+
+        public String getPath() {
+            return path;
+        }
+    }
+
+A companion unit test in JUnit 5 might look like this:
+
+    #!java
+    import org.apache.sling.testing.mock.osgi.config.annotations.ApplyConfig;
+    import org.apache.sling.testing.mock.osgi.config.annotations.UpdateConfig;
+    import org.apache.sling.testing.mock.osgi.junit5.OsgiConfigParametersExtension;
+    import org.junit.jupiter.api.Test;
+    import org.junit.jupiter.api.extension.ExtendWith;
+
+    import static org.junit.jupiter.api.Assertions.assertEquals;
+
+    @ExtendWith(OsgiConfigParametersExtension.class)
+    class MyServiceTest {
+
+        @Test
+        @MyService.Config(path = "/apps") // requires @Retention(RetentionPolicy.RUNTIME)
+        void getPath(MyService.Config config) {
+            MyService myService = new MyService(config);
+            assertEquals("/apps", myService.getPath());
+        }
+
+        @Test
+        @ApplyConfig(type = MyService.Config.class, property = "path=/libs")
+        void getPath_applyConfig(MyService.Config config) {
+            MyService myService = new MyService(config);
+            assertEquals("/libs", myService.getPath());
+        }
+
+        @Test
+        @UpdateConfig(pid = "new-pid", property = "path=/content")
+        @ApplyConfig(pid = "new-pid", type = MyService.Config.class)
+        void getPath_updateConfig(MyService.Config config) {
+            MyService myService = new MyService(config);
+            assertEquals("/content", myService.getPath());
+        }
+    }
+
+
+### JUnit 4: Config Collector JUnit Rule
+
+Given the same example OSGi component from before:
+
+    #!java
+    import org.osgi.service.component.annotations.Activate;
+    import org.osgi.service.component.annotations.Component;
+    import java.lang.annotation.Retention;
+    import java.lang.annotation.RetentionPolicy;
+
+    @Component(service = MyService.class)
+    public class MyService {
+
+        // specify runtime retention to allow for direct usage in unit tests 
+        @Retention(RetentionPolicy.RUNTIME)
+        public @interface Config {
+            String path() default "/";
+        }
+
+        private final String path;
+
+        @Activate
+        public MyService(Config config) {
+            this.path = config.path();
+        }
+
+        public String getPath() {
+            return path;
+        }
+    }
+
+
+A companion unit test in JUnit 4 might look like this:
+
+    #!java
+    import org.apache.sling.testing.mock.osgi.config.annotations.ApplyConfig;
+    import org.apache.sling.testing.mock.osgi.config.annotations.UpdateConfig;
+    import org.apache.sling.testing.mock.osgi.junit.ConfigCollector;
+    import org.apache.sling.testing.mock.osgi.junit.OsgiContext;
+    import org.apache.sling.testing.mock.osgi.junit.OsgiContextBuilder;
+    import org.junit.Rule;
+
+    import static org.junit.Assert.assertEquals;
+
+    public class MyServiceTest {
+
+        @Rule
+        public OsgiContext context = new OsgiContextBuilder().build();
+
+        @Rule
+        public ConfigCollector configs = new ConfigCollector(context, MyService.Config.class);
+
+        @Test
+        @MyService.Config(path = "/apps") // requires @Retention(RetentionPolicy.RUNTIME)
+        public void myServiceMethod() {
+            MyService.Config config = configs.configStream(MyService.Config.class)
+                    .findFirst()
+                    .orElseThrow();
+            MyService myService = new MyService(config);
+            assertEquals("/apps", myService.getPath());
+        }
+
+        @Test
+        @ApplyConfig(type = MyService.Config.class, property = "path=/libs")
+        public void myServiceMethod() {
+            MyService.Config config = configs.configStream(MyService.Config.class)
+                    .findFirst()
+                    .orElseThrow();
+            MyService myService = new MyService(config);
+            assertEquals("/libs", myService.getPath());
+        }
+
+        @Test
+        @UpdateConfig(pid = "new-pid", property = "path=/content")
+        @ApplyConfig(pid = "new-pid", type = MyService.Config.class)
+        public void myServiceMethod() {
+            MyService.Config config = configs.configStream(MyService.Config.class)
+                    .findFirst()
+                    .orElseThrow();
+            MyService myService = new MyService(config);
+            assertEquals("/content", myService.getPath());
+        }
+    }
+
+### Config Annotations: SlingContext Compatibility
+
+The OSGi Mock Config Annotations and JUnit4/JUnit5 extensions are compatible with the `SlingContext` from Sling Mocks and other libraries that provide extensions of `OsgiContextImpl`.
+
+To setup a project with Sling Mocks and OSGi Mocks Config Annotations, adjust the project pom.xml for either JUnit4 or JUnit5:
+
+For JUnit 5:
+
+    #!xml
+    <dependency>
+      <groupId>org.apache.sling</groupId>
+      <artifactId>org.apache.sling.testing.osgi-mock.junit5</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.sling</groupId>
+      <artifactId>org.apache.sling.testing.sling-mock.junit5</artifactId>
+    </dependency>
+
+For JUnit 4:
+
+    #!xml
+    <dependency>

Review Comment:
   same comment as above for osgi-mock.junit5



##########
src/main/jbake/content/documentation/development/osgi-mock.md:
##########
@@ -231,3 +235,192 @@ More examples:
 [mockito-junit5-extension]: https://www.javadoc.io/page/org.mockito/mockito-junit-jupiter/latest/org/mockito/junit/jupiter/MockitoExtension.html
 [caconfig-mock-plugin]: https://github.com/apache/sling-org-apache-sling-testing-caconfig-mock-plugin/blob/master/src/main/java/org/apache/sling/testing/mock/caconfig/ContextPlugins.java
 [caconfig-mock-plugin-test]: https://github.com/apache/sling-org-apache-sling-testing-caconfig-mock-plugin/blob/master/src/test/java/org/apache/sling/testing/mock/caconfig/ContextPluginsTest.java
+
+## Config Annotations
+
+Since osgi-mock 3.4.0, it is possible to use the provided `@UpdateConfig` and `@ApplyConfig` annotations to directly construct component property type ("Config") annotations for use as first-class values in unit tests. Both osgi-mock.junit4 and osgi-mock.junit5 provide different approaches for convenient reflection and injection of these annotations.

Review Comment:
   i struggled first to understand the difference of `@ApplyConfig` and `@UpdateConfig` and hat to lookup the javadocs of both to get a better understanding. it would be helpful to put in here some advice when which annotation should be used.
   this also relates to my general comments in https://github.com/apache/sling-org-apache-sling-testing-osgi-mock/pull/31#pullrequestreview-1670498368



##########
src/main/jbake/content/documentation/development/osgi-mock.md:
##########
@@ -231,3 +235,192 @@ More examples:
 [mockito-junit5-extension]: https://www.javadoc.io/page/org.mockito/mockito-junit-jupiter/latest/org/mockito/junit/jupiter/MockitoExtension.html
 [caconfig-mock-plugin]: https://github.com/apache/sling-org-apache-sling-testing-caconfig-mock-plugin/blob/master/src/main/java/org/apache/sling/testing/mock/caconfig/ContextPlugins.java
 [caconfig-mock-plugin-test]: https://github.com/apache/sling-org-apache-sling-testing-caconfig-mock-plugin/blob/master/src/test/java/org/apache/sling/testing/mock/caconfig/ContextPluginsTest.java
+
+## Config Annotations
+
+Since osgi-mock 3.4.0, it is possible to use the provided `@UpdateConfig` and `@ApplyConfig` annotations to directly construct component property type ("Config") annotations for use as first-class values in unit tests. Both osgi-mock.junit4 and osgi-mock.junit5 provide different approaches for convenient reflection and injection of these annotations.
+
+### JUnit 5: OSGi Config Parameters JUnit Extension
+
+Given an OSGi component class that looks like this:
+
+    #!java
+    import org.osgi.service.component.annotations.Activate;
+    import org.osgi.service.component.annotations.Component;
+    import java.lang.annotation.Retention;
+    import java.lang.annotation.RetentionPolicy;
+
+    @Component(service = MyService.class)
+    public class MyService {
+
+        // specify runtime retention to allow for direct usage in unit tests 
+        @Retention(RetentionPolicy.RUNTIME)
+        public @interface Config {
+            String path() default "/";
+        }
+
+        private final String path;
+
+        @Activate
+        public MyService(Config config) {
+            this.path = config.path();
+        }
+
+        public String getPath() {
+            return path;
+        }
+    }
+
+A companion unit test in JUnit 5 might look like this:
+
+    #!java
+    import org.apache.sling.testing.mock.osgi.config.annotations.ApplyConfig;
+    import org.apache.sling.testing.mock.osgi.config.annotations.UpdateConfig;
+    import org.apache.sling.testing.mock.osgi.junit5.OsgiConfigParametersExtension;
+    import org.junit.jupiter.api.Test;
+    import org.junit.jupiter.api.extension.ExtendWith;
+
+    import static org.junit.jupiter.api.Assertions.assertEquals;
+
+    @ExtendWith(OsgiConfigParametersExtension.class)
+    class MyServiceTest {
+
+        @Test
+        @MyService.Config(path = "/apps") // requires @Retention(RetentionPolicy.RUNTIME)
+        void getPath(MyService.Config config) {
+            MyService myService = new MyService(config);
+            assertEquals("/apps", myService.getPath());
+        }
+
+        @Test
+        @ApplyConfig(type = MyService.Config.class, property = "path=/libs")
+        void getPath_applyConfig(MyService.Config config) {
+            MyService myService = new MyService(config);
+            assertEquals("/libs", myService.getPath());
+        }
+
+        @Test
+        @UpdateConfig(pid = "new-pid", property = "path=/content")
+        @ApplyConfig(pid = "new-pid", type = MyService.Config.class)
+        void getPath_updateConfig(MyService.Config config) {
+            MyService myService = new MyService(config);
+            assertEquals("/content", myService.getPath());
+        }
+    }
+
+
+### JUnit 4: Config Collector JUnit Rule
+
+Given the same example OSGi component from before:
+
+    #!java
+    import org.osgi.service.component.annotations.Activate;
+    import org.osgi.service.component.annotations.Component;
+    import java.lang.annotation.Retention;
+    import java.lang.annotation.RetentionPolicy;
+
+    @Component(service = MyService.class)
+    public class MyService {
+
+        // specify runtime retention to allow for direct usage in unit tests 
+        @Retention(RetentionPolicy.RUNTIME)
+        public @interface Config {
+            String path() default "/";
+        }
+
+        private final String path;
+
+        @Activate
+        public MyService(Config config) {
+            this.path = config.path();
+        }
+
+        public String getPath() {
+            return path;
+        }
+    }
+
+
+A companion unit test in JUnit 4 might look like this:
+
+    #!java
+    import org.apache.sling.testing.mock.osgi.config.annotations.ApplyConfig;
+    import org.apache.sling.testing.mock.osgi.config.annotations.UpdateConfig;
+    import org.apache.sling.testing.mock.osgi.junit.ConfigCollector;
+    import org.apache.sling.testing.mock.osgi.junit.OsgiContext;
+    import org.apache.sling.testing.mock.osgi.junit.OsgiContextBuilder;
+    import org.junit.Rule;
+
+    import static org.junit.Assert.assertEquals;
+
+    public class MyServiceTest {
+
+        @Rule
+        public OsgiContext context = new OsgiContextBuilder().build();
+
+        @Rule
+        public ConfigCollector configs = new ConfigCollector(context, MyService.Config.class);
+
+        @Test
+        @MyService.Config(path = "/apps") // requires @Retention(RetentionPolicy.RUNTIME)
+        public void myServiceMethod() {
+            MyService.Config config = configs.configStream(MyService.Config.class)
+                    .findFirst()
+                    .orElseThrow();
+            MyService myService = new MyService(config);
+            assertEquals("/apps", myService.getPath());
+        }
+
+        @Test
+        @ApplyConfig(type = MyService.Config.class, property = "path=/libs")
+        public void myServiceMethod() {
+            MyService.Config config = configs.configStream(MyService.Config.class)
+                    .findFirst()
+                    .orElseThrow();
+            MyService myService = new MyService(config);
+            assertEquals("/libs", myService.getPath());
+        }
+
+        @Test
+        @UpdateConfig(pid = "new-pid", property = "path=/content")
+        @ApplyConfig(pid = "new-pid", type = MyService.Config.class)
+        public void myServiceMethod() {
+            MyService.Config config = configs.configStream(MyService.Config.class)
+                    .findFirst()
+                    .orElseThrow();
+            MyService myService = new MyService(config);
+            assertEquals("/content", myService.getPath());
+        }
+    }
+
+### Config Annotations: SlingContext Compatibility
+
+The OSGi Mock Config Annotations and JUnit4/JUnit5 extensions are compatible with the `SlingContext` from Sling Mocks and other libraries that provide extensions of `OsgiContextImpl`.
+
+To setup a project with Sling Mocks and OSGi Mocks Config Annotations, adjust the project pom.xml for either JUnit4 or JUnit5:
+
+For JUnit 5:
+
+    #!xml
+    <dependency>

Review Comment:
   sling-mock.junit5 as a direct depenency to osgi-mock.junit5. it is recommended to always only define a dependency to sling-mock.junit5 (or aem-mock.junit5) and not the upstream libraries, to not have to manage the dependencies of all of them (and maybe get those versions mixed in a wrong way). sling-mock and aem-mock always include the latest (and compatible) version of the upstream mock dependencies.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@sling.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] SLING-12038 add documentation for OSGi Mocks Config Annotations [sling-site]

Posted by "adamcin (via GitHub)" <gi...@apache.org>.
adamcin commented on code in PR #135:
URL: https://github.com/apache/sling-site/pull/135#discussion_r1355177562


##########
src/main/jbake/content/documentation/development/osgi-mock.md:
##########
@@ -231,3 +235,192 @@ More examples:
 [mockito-junit5-extension]: https://www.javadoc.io/page/org.mockito/mockito-junit-jupiter/latest/org/mockito/junit/jupiter/MockitoExtension.html
 [caconfig-mock-plugin]: https://github.com/apache/sling-org-apache-sling-testing-caconfig-mock-plugin/blob/master/src/main/java/org/apache/sling/testing/mock/caconfig/ContextPlugins.java
 [caconfig-mock-plugin-test]: https://github.com/apache/sling-org-apache-sling-testing-caconfig-mock-plugin/blob/master/src/test/java/org/apache/sling/testing/mock/caconfig/ContextPluginsTest.java
+
+## Config Annotations
+
+Since osgi-mock 3.4.0, it is possible to use the provided `@UpdateConfig` and `@ApplyConfig` annotations to directly construct component property type ("Config") annotations for use as first-class values in unit tests. Both osgi-mock.junit4 and osgi-mock.junit5 provide different approaches for convenient reflection and injection of these annotations.

Review Comment:
   @stefanseifert I've honestly had the hardest time naming the `@ApplyConfig` annotation throughout its development, so I'm still open to suggestions as long as that PR is open. My first choice was to call it `@ComponentPropertyType`, but this annotation is already defined by the OSGi spec for use as a marker annotation on the same config annotations I'm trying to construct, which would just invite confusion when one is accidentally used in place of the other.  I also tried `@DynamicConfig` and `@ConfigMapping`, but I ultimately decided on `@ApplyConfig` when it became clear I should create a separate `@UpdateConfig` annotation. 
   
   Maybe either `@GetConfig` or `@MapConfigType` would be better?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@sling.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org