Fixed #180 - Enable debugging of plugin while running integration tests

khmarbaise · Apr 8, 2021 · b2fa104 · b2fa104
1 parent 6c6c231
commit b2fa104
Show file tree

Hide file tree

Showing 5 changed files with 165 additions and 5 deletions.
diff --git a/itf-documentation/src/main/asciidoc/release-notes/_release-notes-0.10.0.adoc b/itf-documentation/src/main/asciidoc/release-notes/_release-notes-0.10.0.adoc
@@ -43,6 +43,7 @@
 :issue-175: https://github.com/khmarbaise/maven-it-extension/issues/175[Fixed #175]
 :issue-176: https://github.com/khmarbaise/maven-it-extension/issues/176[Fixed #176]
 :issue-177: https://github.com/khmarbaise/maven-it-extension/issues/177[Fixed #177]
+:issue-180: https://github.com/khmarbaise/maven-it-extension/issues/180[Fixed #180]
 :issue-181: https://github.com/khmarbaise/maven-it-extension/issues/181[Fixed #181]
 :issue-182: https://github.com/khmarbaise/maven-it-extension/issues/182[Fixed #182]
 :issue-183: https://github.com/khmarbaise/maven-it-extension/issues/183[Fixed #183]
@@ -73,6 +74,10 @@
    * {issue-176} - Remove needless import on MavenProjectResult in docs.
    * {issue-186} - Typo in method name should be isSuccessful.
 
+*Enhancements*
+
+ * {issue-180} - Enable debugging of plugin while running integration tests.
+
 *Details*
 
  * {issue-128}  - Add automatic module name.

diff --git a/itf-documentation/src/main/asciidoc/usersguide/usersguide.adoc b/itf-documentation/src/main/asciidoc/usersguide/usersguide.adoc
@@ -1541,6 +1541,56 @@ class CompareDependenciesIT
 }
 ----
 
+[#_debugging]
+== Debugging Plugins
+
+:intellij-junit: https://www.jetbrains.com/help/idea/run-debug-configuration-junit.html#configTab
+:intellij-remote: https://www.jetbrains.com/help/idea/tutorial-remote-debug.html#335b9aea
+
+=== Overview
+
+Sometimes you need to debug your code of your implemented plugin because
+usual tests or even integration tests are not enough. The question is
+how?
+
+Generally you have to define the system property `ITF_DEBUG=true` before you
+run your integration test. This will start the integration test while executing `mvnDebug`
+instead of `mvn` and will simply wait for a connection of a remote debugger usually
+from your IDE.
+
+=== Limitations
+
+Debugging can only being done after you have run your whole integration tests once via
+command line. An idea for the future might be a plugin for IDE's to support that in a
+more convenient way (Help is appreciated).
+
+==== IDEA IntelliJ
+
+You have to define a {intellij-junit}[system property for debugging in your IDE run configuration].
+In the configuration you will find an entry for the VM which usually contains already `-ea` and
+exactly that field needs to be enhanced with the entry `-DITF_DEBUG=true`. By using this run
+configuration you can start the integration test just as before from within your IDE. The process
+will wait until you are connected.
+
+The next step is to {intellij-remote}[configure remote debugging] which means to define the port `8000`
+as port and check if you are using JDK8 or JDK9+ in your configuration.
+
+I recommend to start only a single integration test case via the above described run configuration,
+in debugging mode otherwise all processes woulduse the same port which would result in failure
+because only one can use that port.
+
+==== Eclipse
+
+Basically it should work the same.
+
+(Feedback is welcome to give more details on that.)
+
+==== Netbeans
+
+Basically it should work the same.
+
+(Feedback is welcome to give more details on that.)
+
 
 <<<
 

diff --git a/itf-jupiter-extension/src/main/java/com/soebes/itf/jupiter/extension/MavenITExtension.java b/itf-jupiter-extension/src/main/java/com/soebes/itf/jupiter/extension/MavenITExtension.java
@@ -43,6 +43,7 @@
 import java.lang.reflect.Method;
 import java.nio.file.FileSystems;
 import java.nio.file.Path;
+import java.nio.file.Paths;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Collections;
@@ -211,7 +212,6 @@ public void beforeTestExecution(ExtensionContext context)
 
     List<String> executionArguments = new ArrayList<>();
 
-
     //TODO: Reconsider about the default options which are being defined here? Documented? users guide?
     List<String> defaultArguments = Arrays.asList(
         "-Dmaven.repo.local=" + directoryResolverResult.getCacheDirectory().toString());

diff --git a/itf-jupiter-extension/src/main/java/com/soebes/itf/jupiter/extension/MavenLocator.java b/itf-jupiter-extension/src/main/java/com/soebes/itf/jupiter/extension/MavenLocator.java
@@ -48,10 +48,16 @@ class MavenLocator {
    */
   private static final String MAVEN_HOME = "maven.home";
 
+  /**
+   * The name of the system property to activate remote debugging.
+   */
+  private static final String ITF_DEBUG = "ITF_DEBUG";
+
 
   private final FileSystem fileSystem;
   private final Optional<String> pathEnvironment;
   private final boolean isRunningOnWindows;
+  private final String  mvnExecutable;
 
   /**
    * @param fileSystem The {@link FileSystem} which is used.
@@ -62,6 +68,7 @@ class MavenLocator {
     this.fileSystem = fileSystem;
     this.pathEnvironment = pathEnvironment;
     this.isRunningOnWindows = isRunningOnWindows;
+    this.mvnExecutable = Boolean.getBoolean(ITF_DEBUG) ? "mvnDebug" : "mvn";
   }
 
   private Path intoPath(String s) {
@@ -77,15 +84,15 @@ private Optional<String> mavenHomeFromSystemProperty() {
   }
 
   private Path toMvn(Path p) {
-    return p.resolve("mvn");
+    return p.resolve(this.mvnExecutable);
   }
 
   private Path toBat(Path p) {
-    return p.resolve("mvn.bat");
+    return p.resolve(this.mvnExecutable + ".bat");
   }
 
   private Path toCmd(Path p) {
-    return p.resolve("mvn.cmd");
+    return p.resolve(this.mvnExecutable + ".cmd");
   }
 
   private boolean isExecutable(Path s) {

diff --git a/itf-jupiter-extension/src/test/java/com/soebes/itf/jupiter/extension/MavenLocatorTest.java b/itf-jupiter-extension/src/test/java/com/soebes/itf/jupiter/extension/MavenLocatorTest.java
@@ -135,7 +135,6 @@ void find_via_path() throws IOException {
 
     }
 
-
     @Nested
     @DisplayName("Prefer maven.home over PATH")
     class PreferMavenHome {
@@ -176,6 +175,47 @@ void priority_works() throws IOException {
 
     }
 
+    @Nested
+    @DisplayName("ITF_DEBUG")
+    class ITFDebugging {
+
+      private final String LINUX_TOOLS_MAVEN_HOME_DIRECTORY = "/tools/apache-maven-3.6.3";
+      private final String LINUX_TOOLS_MAVEN_BIN_DIRECTORY = "/tools/apache-maven-3.6.3/bin";
+
+      private Properties backup;
+      private Optional<String> pathEnvironment;
+
+      void createMvn(FileSystem wfs) throws IOException {
+        create(wfs, LINUX_TOOLS_MAVEN_BIN_DIRECTORY, "mvnDebug");
+      }
+
+      @BeforeEach
+      void beforeEach() {
+        backup = new Properties();
+        backup.putAll(System.getProperties());
+        this.pathEnvironment = createLinuxEnvironmentPath();
+        System.setProperty("maven.home", LINUX_TOOLS_MAVEN_HOME_DIRECTORY);
+        System.setProperty("ITF_DEBUG", "true");
+      }
+
+      @AfterEach
+      void restore() {
+        System.setProperties(backup);
+      }
+
+      @Test
+      @DisplayName("mvnDebug")
+      void priority_works() throws IOException {
+        try (FileSystem wfs = MemoryFileSystemBuilder.newLinux().build("LinuxSystem")) {
+          createMvn(wfs);
+          MavenLocator mavenLocator = new MavenLocator(wfs, pathEnvironment, false);
+          Optional<Path> mvn = mavenLocator.findMvn();
+          assertThat(mvn).contains(wfs.getPath(LINUX_TOOLS_MAVEN_BIN_DIRECTORY, "mvnDebug"));
+        }
+      }
+
+    }
+
   }
 
   @Nested
@@ -344,6 +384,64 @@ void priority_works_with_cmd() throws IOException {
       }
 
     }
+    @Nested
+    @DisplayName("ITF_DEBUG")
+    class ITFDebugging {
+
+      private final String WINDOWS_TOOLS_MAVEN_HOME_DIRECTORY = "C:\\tools\\maven";
+      private final String WINDOWS_TOOLS_MAVEN_BIN_DIRECTORY = "C:\\tools\\maven\\bin";
+
+      private Properties backup;
+      private Optional<String> pathEnvironment;
+
+      void createToolsDebugBat(FileSystem wfs) throws IOException {
+        create(wfs, WINDOWS_TOOLS_MAVEN_BIN_DIRECTORY, "mvnDebug.bat");
+      }
+
+      void createToolsDebugCmd(FileSystem wfs) throws IOException {
+        create(wfs, WINDOWS_TOOLS_MAVEN_BIN_DIRECTORY, "mvnDebug.cmd");
+      }
+
+      @BeforeEach
+      void beforeEach() {
+        backup = new Properties();
+        backup.putAll(System.getProperties());
+        this.pathEnvironment = createWindowsEnvironmentPath();
+        System.setProperty("maven.home", WINDOWS_TOOLS_MAVEN_HOME_DIRECTORY);
+        System.setProperty("ITF_DEBUG", "true");
+      }
+
+      @AfterEach
+      void restore() {
+        System.setProperties(backup);
+      }
+
+      @Test
+      @DisplayName("mvnDebug.bat")
+      void priority_works_with_debug_bat() throws IOException {
+        try (FileSystem wfs = MemoryFileSystemBuilder.newWindows().build("WindowsSystem")) {
+          createMvnBat(wfs);
+          createToolsDebugBat(wfs);
+          MavenLocator mavenLocator = new MavenLocator(wfs, pathEnvironment, true);
+          Optional<Path> mvn = mavenLocator.findMvn();
+          assertThat(mvn).contains(wfs.getPath(WINDOWS_TOOLS_MAVEN_BIN_DIRECTORY, "mvnDebug.bat"));
+        }
+      }
+
+      @Test
+      @DisplayName("mvnDebug.cmd")
+      void priority_works_with_debug_cmd() throws IOException {
+        try (FileSystem wfs = MemoryFileSystemBuilder.newWindows().build("WindowsSystem")) {
+          createMvnCmd(wfs);
+          createToolsDebugCmd(wfs);
+
+          MavenLocator mavenLocator = new MavenLocator(wfs, pathEnvironment, true);
+          Optional<Path> mvn = mavenLocator.findMvn();
+          assertThat(mvn).contains(wfs.getPath(WINDOWS_TOOLS_MAVEN_BIN_DIRECTORY, "mvnDebug.cmd"));
+        }
+      }
+
+    }
 
   }