Add support to easily run any JMX with the DSL

Additionally, use config jmeter dependency to avoid copying required properties file to resources folder and keep project cleaner.

Author: rabelenda-abstracta

.github/workflows/build.yml

@@ -1,7 +1,5 @@
 name: run tests
-on:
-  push:
-    branches: '*'
+on: push
 jobs:
   test:
     runs-on: ubuntu-latest

README.md

@@ -20,6 +20,7 @@ Here is a simple example test in [JUnit 5](https://junit.org/junit5/)+ with 2 th
 import static org.assertj.core.api.Assertions.assertThat;
 import static us.abstracta.jmeter.javadsl.JmeterDsl.*;
 
+import java.io.IOException;
 import java.time.Duration;
 import org.eclipse.jetty.http.MimeTypes.Type;
 import org.junit.jupiter.api.Test;
@@ -57,7 +58,7 @@ There are many tools to script performance/load tests, being [JMeter] and [Gatli
 
 JMeter is great for people with no programming knowledge since it provides a graphical interface to create test plans and run them. Additionally, it is the most popular tool (with a lot of supporting tools built on it) and has a big amount of supported protocols and plugins that makes it very versatile. 
 
-But, JMeter has some problems as well: sometimes might be slow to create test plans in JMeter GUI, and you can't get the full picture of the test plan unless you dig in every tree node to check its properties. Furthermore, it doesn't provide a simple programmer friendly API (you can check [here](https://www.blazemeter.com/blog/5-ways-launch-jmeter-test-without-using-jmeter-gui/) for an example on how to run jmeter programmatically without jmeter-java-dsl), nor a VCS friendly format (too verbose and hard to review). For example, for the same test plan previously showed with jmeter-java-dsl, in JMeter you would need a JMX file like [this](docs/sample.jmx), and even then, it wouldn't be as simple to do assertions on collected statistics as in provided example.
+But, JMeter has some problems as well: sometimes might be slow to create test plans in JMeter GUI, and you can't get the full picture of the test plan unless you dig in every tree node to check its properties. Furthermore, it doesn't provide a simple programmer friendly API (you can check [here](https://www.blazemeter.com/blog/5-ways-launch-jmeter-test-without-using-jmeter-gui/) for an example on how to run JMeter programmatically without jmeter-java-dsl), nor a VCS friendly format (too verbose and hard to review). For example, for the same test plan previously showed with jmeter-java-dsl, in JMeter you would need a JMX file like [this](docs/sample.jmx), and even then, it wouldn't be as simple to do assertions on collected statistics as in provided example.
 
 Gatling does provide a simple API and a VCS friendly format, but requires scala knowledge and environment. Additionally, it doesn't provide as rich environment as JMeter (protocol support, plugins, tools) and requires learning a new framework for testing (if you already use JMeter, which is the most popular tool).
 
@@ -166,7 +167,59 @@ public class SaveTestPlanAsJMX {
 
 > Take into consideration that currently there is no automatic way to migrate changes done in JMX to the Java DSL.
 
-This can be helpful to share a Java DSL defined test plan with people not used to the DSL, or to use some JMeter feature (or plugin) that is not yet supported by the DSL (**but, we strongly encourage you to report it as an issue**, so we can implement support for it).  
+This can be helpful to share a Java DSL defined test plan with people not used to the DSL, or to use some JMeter feature (or plugin) that is not yet supported by the DSL (**but, we strongly encourage you to report it as an issue**, so we can implement support for it).
+
+### Run JMX file
+
+jmeter-java-dsl also provides means to easily run a test plan from a JMX file either locally or in BlazeMeter (through previously mentioned jmeter-java-dsl-blazemeter module). Here is an example:
+
+```java
+import static org.assertj.core.api.Assertions.assertThat;
+
+import java.io.IOException;
+import java.time.Duration;
+import org.junit.jupiter.api.Test;
+import us.abstracta.jmeter.javadsl.core.DslTestPlan;
+import us.abstracta.jmeter.javadsl.core.TestPlanStats;
+
+public class RunJmxTestPlan {
+  
+  @Test
+  public void testPerformance() throws IOException {
+    TestPlanStats stats = DslTestPlan.fromJmx("test-plan.jmx").run();
+    assertThat(stats.overall().elapsedTimePercentile99()).isLessThan(Duration.ofSeconds(5));
+  }
+  
+}
+``` 
+
+This can be used to just run existing JMX files, or when DSL has no support for some JMeter functionality or plugin and you need to use JMeter GUI to build the test plan but still want to use jmeter-java-dsl to run the test plan embedded in Java test or code.
+
+> When the JMX uses some custom plugins or JMeter protocol support, you might need to add required dependencies to be able to run the test in an embedded engine. For example, when running a TN3270 JMX test plan using RTE plugin you will need to add following repository and dependencies:
+> ```xml
+> <repositories>
+>   <repository>
+>     <id>jitpack.io</id>
+>     <url>https://jitpack.io</url>
+>   </repository>
+> </repositories>
+>
+> <dependencies>
+>    ...
+>    <dependency>
+>      <groupId>com.github.Blazemeter</groupId>
+>      <artifactId>RTEPlugin</artifactId>
+>      <version>3.1</version>
+>      <scope>test</scope>
+>    </dependency>
+>    <dependency>
+>      <groupId>com.github.Blazemeter</groupId>
+>      <artifactId>dm3270</artifactId>
+>      <version>0.12.3-lib</version>
+>      <scope>test</scope>
+>    </dependency>
+> </dependencies>
+> ```     
 
 ## Contributing & Requesting features
 

docs/classes.puml

@@ -33,6 +33,7 @@ package core {
     TestPlanStats run()
     TestPlanStats runIn(DslJmeterEngine engine)
     void saveAsJmx(String filePath)
+    {static} DslTestPlan fromJmx(String filePath)
   }
 
   interface TestPlanChild extends DslTestElement {

jmeter-java-dsl/pom.xml

@@ -32,11 +32,21 @@
       <artifactId>ApacheJMeter_functions</artifactId>
       <version>${jmeter.version}</version>
     </dependency>
+    <dependency>
+      <groupId>org.apache.jmeter</groupId>
+      <artifactId>ApacheJMeter_config</artifactId>
+      <version>${jmeter.version}</version>
+    </dependency>
     <dependency>
       <groupId>org.eclipse.jetty</groupId>
       <artifactId>jetty-http</artifactId>
       <version>9.4.32.v20200930</version>
     </dependency>
+    <dependency>
+      <groupId>commons-io</groupId>
+      <artifactId>commons-io</artifactId>
+      <version>2.8.0</version>
+    </dependency>
 
     <dependency>
       <groupId>org.xmlunit</groupId>

jmeter-java-dsl/src/main/java/us/abstracta/jmeter/javadsl/core/DslTestPlan.java

@@ -7,6 +7,7 @@
 import org.apache.jmeter.control.gui.TestPlanGui;
 import org.apache.jmeter.testelement.TestElement;
 import org.apache.jmeter.testelement.TestPlan;
+import org.apache.jorphan.collections.HashTree;
 import us.abstracta.jmeter.javadsl.core.DslTestPlan.TestPlanChild;
 
 /**
@@ -55,7 +56,32 @@ public TestPlanStats runIn(DslJmeterEngine engine)
    * @throws IOException when there is a problem saving to the file.
    */
   public void saveAsJmx(String filePath) throws IOException {
-    new EmbeddedJmeterEngine().saveToJmx(filePath, this);
+    EmbeddedJmeterEngine.saveTestPlanToJmx(this, filePath);
+  }
+
+  public static DslTestPlan fromJmx(String filePath) throws IOException {
+    return EmbeddedJmeterEngine.loadTestPlanFromJmx(filePath);
+  }
+
+  public static DslTestPlan fromTree(HashTree tree) {
+    return new JmxTestPlan(tree);
+  }
+
+  private static class JmxTestPlan extends DslTestPlan {
+
+    private final HashTree tree;
+
+    private JmxTestPlan(HashTree tree) {
+      super(null);
+      this.tree = tree;
+    }
+
+    @Override
+    public HashTree buildTreeUnder(HashTree parent) {
+      parent.putAll(tree);
+      return tree.values().iterator().next();
+    }
+
   }
 
   /**

jmeter-java-dsl/src/main/java/us/abstracta/jmeter/javadsl/core/EmbeddedJmeterEngine.java

@@ -7,6 +7,7 @@
 import java.net.URISyntaxException;
 import java.nio.file.Files;
 import java.nio.file.Path;
+import org.apache.commons.io.FileUtils;
 import org.apache.jmeter.engine.StandardJMeterEngine;
 import org.apache.jmeter.functions.EvalFunction;
 import org.apache.jmeter.reporters.ResultCollector;
@@ -42,28 +43,27 @@ public TestPlanStats run(DslTestPlan testPlan) throws IOException {
 
   private static class JMeterEnvironment implements Closeable {
 
-    private final Path propsFilePath;
+    private final File propsDir;
 
     private JMeterEnvironment() throws IOException {
-      propsFilePath = Files.createTempFile("jmeter", ".properties");
+      propsDir = Files.createTempDirectory("jmeter-java-dsl").toFile();
       try {
-        setupJMeterProperties(propsFilePath);
+        setupJMeterProperties(propsDir);
       } catch (IOException | RuntimeException e) {
-        deleteFile(propsFilePath);
+        FileUtils.deleteDirectory(propsDir);
         throw e;
       }
     }
 
-    private void setupJMeterProperties(Path propsFilePath) throws IOException {
-      deleteFile(propsFilePath);
-      Files.copy(getClass().getResourceAsStream("/saveservice.properties"), propsFilePath);
-      JMeterUtils.loadJMeterProperties(propsFilePath.toString());
+    private void setupJMeterProperties(File propsDir) throws IOException {
+      File propsFile = new File(propsDir, "jmeter.properties");
+      propsFile.createNewFile();
+      JMeterUtils.loadJMeterProperties(propsFile.toString());
       JMeterUtils.setProperty("search_paths", getFunctionsJarPath());
-      JMeterUtils.setProperty("saveservice_properties", propsFilePath.toString());
-    }
-
-    private void deleteFile(Path propsFilePath) {
-      propsFilePath.toFile().delete();
+      JMeterUtils.setProperty("saveservice_properties",
+          installPropertiesFile(propsDir, "saveservice.properties"));
+      JMeterUtils.setProperty("upgrade_properties",
+          installPropertiesFile(propsDir, "upgrade.properties"));
     }
 
     private String getFunctionsJarPath() {
@@ -75,9 +75,16 @@ private String getFunctionsJarPath() {
       }
     }
 
+    private String installPropertiesFile(File propsDir, String propsFileName)
+        throws IOException {
+      Path saveServicePropsPath = propsDir.toPath().resolve(propsFileName);
+      Files.copy(getClass().getResourceAsStream("/bin/" + propsFileName), saveServicePropsPath);
+      return saveServicePropsPath.toString();
+    }
+
     @Override
-    public void close() {
-      deleteFile(propsFilePath);
+    public void close() throws IOException {
+      FileUtils.deleteDirectory(propsDir);
     }
 
   }
@@ -106,7 +113,8 @@ private void addTestSummariserToTree(HashTree tree) {
     tree.add(new ResultCollector(new Summariser()));
   }
 
-  public void saveToJmx(String filePath, DslTestPlan dslTestPlan) throws IOException {
+  public static void saveTestPlanToJmx(DslTestPlan dslTestPlan, String filePath)
+      throws IOException {
     try (JMeterEnvironment env = new JMeterEnvironment();
         FileOutputStream output = new FileOutputStream(filePath)) {
       HashTree tree = new ListedHashTree();
@@ -115,4 +123,11 @@ public void saveToJmx(String filePath, DslTestPlan dslTestPlan) throws IOExcepti
     }
   }
 
+  public static DslTestPlan loadTestPlanFromJmx(String filePath) throws IOException {
+    try (JMeterEnvironment env = new JMeterEnvironment()) {
+      HashTree tree = SaveService.loadTree(new File(filePath));
+      return DslTestPlan.fromTree(tree);
+    }
+  }
+
 }