[sling-org-apache-sling-junit-core] branch SLING-9915-junit-annotation-int-tests updated: Updated README with more detailed instructions for debugging

[cr...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

cris pushed a commit to branch SLING-9915-junit-annotation-int-tests
in repository https://gitbox.apache.org/repos/asf/sling-org-apache-sling-junit-core.git


The following commit(s) were added to refs/heads/SLING-9915-junit-annotation-int-tests by this push:
     new b487d1c  Updated README with more detailed instructions for debugging
b487d1c is described below

commit b487d1c55df202a6566c10cede356183c8f93b69
Author: Cris Rockwell <cm...@umich.edu>
AuthorDate: Mon Nov 30 13:43:59 2020 -0500

    Updated README with more detailed instructions for debugging
---
 src/it/annotations-it/README.md                    | 35 ++++++++++++++++++++--
 src/it/annotations-it/pom.xml                      |  2 +-
 .../sling/junit/annotations/ReferenceIT.java       |  1 -
 3 files changed, 34 insertions(+), 4 deletions(-)

diff --git a/src/it/annotations-it/README.md b/src/it/annotations-it/README.md
index 788e923..e6dd277 100644
--- a/src/it/annotations-it/README.md
+++ b/src/it/annotations-it/README.md
@@ -1,8 +1,39 @@
-Integration tests for the server testing annotation @TestReference
+#Integration tests for the server testing annotation @TestReference
+This bundle provides server-side junit test `TestReferenceJITest.java` which can be run with SlingAnnotationsTestRunner via a `POST` request to `/system/sling/junit/org.apache.sling.junit.tests.TestReferenceJTest.html`
+with a debugging breakpoint set with ReferenceIT.java `waitForSling()` method. 
 
-To run or debug the tests from this folder, use:
+Note: If additional tests of this type are needed, name the test class such that it satisfies the configured 
+regular expression found in bnd.bnd `Sling-Test-Regexp: .*JITest`
 
+
+##To run or debug the tests from this folder, use:
+
+### Build
   mvn clean verify -Dannotations.bundle.version=VVV
 
 Where VVV is the version of the junit-core bundle to test.
 
+### Debug
+
+Two separate remote debugger clients may be needed: 
+`ReferenceIT.java` is a junit test class which runs outside of Sling, 
+which can be debugged using the following commands... 
+  
+* `cd sling-org-apache-sling-junit-core/src/it/annotations-it`
+* `mvn clean verify  -Dannotations.bundle.version=1.1.1-SNAPSHOT -Dmaven.failsafe.debug`
+* The test will wait for debugger to connect before continuing.
+* Set a breakpoint in `waitForSling` within  ReferenceIT.java   
+* Connect a debugger client over 5005 (default) or the selected port [1]  
+* Make note of the localhost URL and port (which is dynamically selected) by inspecting the `URI url` variable
+
+With the test paused via this debugger, it is now possible to connect a browser to the running (temporary) Sling test instance,
+or connect another debugger to access classes such as `TestReferenceJITest.java` or other classes, which run within Sling.
+* Configure `annotations-it/pom.xml` with the following or equivalent  
+```
+   <pax.vm.options>
+    -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5015
+   </pax.vm.options>
+```
+* Reconnect the `ReferenceIT.java` debugger as described above
+
+[1] https://maven.apache.org/surefire/maven-failsafe-plugin/examples/debugging.html
diff --git a/src/it/annotations-it/pom.xml b/src/it/annotations-it/pom.xml
index e82c0e2..be42e6c 100644
--- a/src/it/annotations-it/pom.xml
+++ b/src/it/annotations-it/pom.xml
@@ -33,7 +33,7 @@
     <org.ops4j.pax.exam.version>4.13.4</org.ops4j.pax.exam.version>
     <junit.version>4.13</junit.version>
     <hamcrest.version>1.3</hamcrest.version>
-    <!-- additional options that can be passed to Pax before executing the tests -->
+    <!-- additional options that can be passed to Pax before executing the tests. See README for Debugging instructions. -->
     <pax.vm.options />
     <bundle.filename>${basedir}/target/${project.build.finalName}.jar</bundle.filename>
     <annotations.bundle.version>MUST_BE_SET_BY_INVOKER</annotations.bundle.version>
diff --git a/src/it/annotations-it/src/test/java/org/apache/sling/junit/annotations/ReferenceIT.java b/src/it/annotations-it/src/test/java/org/apache/sling/junit/annotations/ReferenceIT.java
index f9816b3..d9389f7 100644
--- a/src/it/annotations-it/src/test/java/org/apache/sling/junit/annotations/ReferenceIT.java
+++ b/src/it/annotations-it/src/test/java/org/apache/sling/junit/annotations/ReferenceIT.java
@@ -42,7 +42,6 @@ import static org.ops4j.pax.exam.CoreOptions.composite;
 import static org.ops4j.pax.exam.CoreOptions.mavenBundle;
 import static org.ops4j.pax.exam.CoreOptions.systemProperty;
 import static org.ops4j.pax.exam.CoreOptions.when;
-import static org.ops4j.pax.exam.CoreOptions.junitBundles;
 import org.apache.sling.testing.paxexam.TestSupport;