Add example to run test with distributed engine using docker-compose

Author: rabelenda-abstracta

.github/fix-docs-version.sh

@@ -16,6 +16,7 @@ update_file_versions() {
 update_file_versions ${VERSION} README.md
 update_file_versions ${VERSION} docs/index.md
 update_file_versions ${VERSION} docs/guide/README.md
+update_file_versions ${VERSION} docs/guide/distributed/test/pom.xml
 
 git add README.md docs/index.md docs/guide/README.md
 git config --local user.email "$(git log --format='%ae' HEAD^!)"

docs/guide/README.md

@@ -417,6 +417,10 @@ To be able to run the test you require the `rmi_keystore.jks` file in working di
 In general, prefer using BlazeMeter or OctoPerf options which avoid all the setup and maintenance costs of the infrastructure required by JMeter remote testing, in addition to additional useful features (like reporting capabilities).
 :::
 
+::: tip
+[Here](../../docs/guide/distributed) is an example project using `docker-compose` that starts a jmeter server/slave and executes a test with it. If you want to do a similar setup generate your own keystore and properly tune RMI remote server in server/slave. 
+:::
+
 Check [DistributedJmeterEngine](../../jmeter-java-dsl/src/main/java/us/abstracta/jmeter/javadsl/core/engines/DistributedJmeterEngine.java) and [JMeter documentation](http://jmeter.apache.org/usermanual/remote-test.html) for proper setup and additional options.
 
 ## Advanced threads configuration

docs/guide/distributed/docker-compose.yml

@@ -0,0 +1,15 @@
+version: '3'
+services:
+  test:
+    image: maven:3.8
+    working_dir: /usr/src/test
+    volumes:
+      - ./test:/usr/src/test
+      - ./rmi_keystore.jks:/usr/src/test/rmi_keystore.jks
+      - ~/.m2:/root/.m2
+    command: mvn clean test
+  server:
+    build: jmeter
+    volumes:
+      - ./rmi_keystore.jks:/opt/jmeter/rmi_keystore.jks
+    command: jmeter-server -Dserver.rmi.localport=2020 -Djava.rmi.server.hostname=server

docs/guide/distributed/jmeter/Dockerfile

@@ -0,0 +1,15 @@
+FROM eclipse-temurin:8
+
+ENV JMETER_VERSION=5.5
+ENV JMETER_HOME=/opt/jmeter
+ENV JMETER_TGZ_PATH=/tmp/jmeter.tgz
+
+WORKDIR ${JMETER_HOME}
+
+RUN curl -L -s -o ${JMETER_TGZ_PATH} https://archive.apache.org/dist/jmeter/binaries/apache-jmeter-${JMETER_VERSION}.tgz \
+  && tar -xzf ${JMETER_TGZ_PATH} \
+  && mv apache-jmeter-${JMETER_VERSION}/* . \
+  && rm -r apache-jmeter-${JMETER_VERSION} \
+  && rm ${JMETER_TGZ_PATH}
+
+ENV PATH $PATH:$JMETER_HOME/bin

docs/guide/distributed/rmi_keystore.jks

@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <groupId>us.abstracta.jmeter</groupId>
+  <artifactId>sample-distributed-test</artifactId>
+  <version>0.1-SNAPSHOT</version>
+
+  <properties>
+    <!-- using Java 11 instead of 17 since is the latest LTS JMeter has support for -->
+    <maven.compiler.release>11</maven.compiler.release>
+  </properties>
+
+  <build>
+    <pluginManagement>
+      <plugins>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-compiler-plugin</artifactId>
+          <version>3.10.1</version>
+        </plugin>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-surefire-plugin</artifactId>
+          <version>3.0.0-M7</version>
+        </plugin>
+      </plugins>
+    </pluginManagement>
+  </build>
+
+  <dependencies>
+    <dependency>
+      <groupId>us.abstracta.jmeter</groupId>
+      <artifactId>jmeter-java-dsl</artifactId>
+      <version>0.63</version>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter-engine</artifactId>
+      <version>5.8.2</version>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.assertj</groupId>
+      <artifactId>assertj-core</artifactId>
+      <version>3.22.0</version>
+      <scope>test</scope>
+    </dependency>
+  </dependencies>
+</project>

docs/guide/distributed/test/pom.xml

@@ -0,0 +1,20 @@
+import static org.assertj.core.api.Assertions.assertThat;
+import static us.abstracta.jmeter.javadsl.JmeterDsl.*;
+
+import org.junit.jupiter.api.Test;
+import us.abstracta.jmeter.javadsl.core.TestPlanStats;
+import us.abstracta.jmeter.javadsl.core.engines.DistributedJmeterEngine;
+
+public class PerformanceTest {
+
+  @Test
+  public void shouldGetExpectedCountWhenRunTestInRemoteEngine() throws Exception {
+    TestPlanStats stats = testPlan(
+        threadGroup(1, 1,
+            httpSampler("https://myservice")
+        )
+    ).runIn(new DistributedJmeterEngine("server:1099"));
+    assertThat(stats.overall().samplesCount()).isEqualTo(1);
+  }
+
+}