Getting Started with JMeter DSL

Apache JMeter used to be a developer tool. It was primarily created to test Apache JServ (replaced by TomCat project) by Stefano Mazzocchi. After several enhancements were made to the GUI, JMeter has become a tester-friendly tool. Modern developers use Gatling or k6 or Locust as their go-to performance testing tool to quickly test their services. Now the time has come to JMeter to gain more developers' attention via DSL. In this blog article, we are going to see about JMeter DSL, Hello World example, running a simple test, and more.

What is a Domain Specific Language?

Here is the definition from Wikipedia: A domain-specific language (DSL) is a computer language specialized in a particular application domain.

To simply put, DSL provides some sort of abstraction which solves certain problems. E.g. regular expressions, HTML, and more.

If you are into Gatling, then you are already working on DSL. You can also create your own DSL using the Meta Programming System, a topic for another blog.

What is JMeter DSL?

JMeter DSL is an open source initiative from Abstracta which provides JMeter-as-Code in Java.

Here are a couple of drawbacks of vanilla JMeter is:

• It is not Git friendly due to its XML nature.
• For Groovy scripting, no autocomplete or debugging feature

JMeter DSL solves the above problems, and provides more features such as CI/CD integration, Git and IDE friendly, extends the JMeter ecosystem and makes it more pluggable, and more

Hello World on JMeter DSL

No more theory. Let us get started with a simple example of JMeter DSL.

Prerequisites

• Basic JMeter knowledge
• Basic Java knowledge,
• favorite Java IDE

In this example, we are going to create a Gradle project using IntelliJ IDEA Community Edition. If you are using other IDEs, instructions would be similar.

Launch IntelliJ IDEA and create a new Gradle project as shown below.

Copy and paste the below code into the build.gradle file. Your IDE may suggest using the latest version of 028 for JMeter DSL. This issue has already been raised. Please ignore that suggestion as of now. It will be fixed in JMeter DSL 1.0.

plugins {
    id 'java'
}

group 'org.qainsights'
version '1.0-SNAPSHOT'

repositories {
    mavenCentral()
}

dependencies {
    testImplementation 'org.junit.jupiter:junit-jupiter-api:5.8.2'
    testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine:5.8.2'
    testImplementation group: 'org.assertj', name: 'assertj-core', version: '3.22.0'

    testImplementation 'us.abstracta.jmeter:jmeter-java-dsl:0.54'

    components {
        withModule("org.apache.jmeter:ApacheJMeter_core", JmeterRule)
        withModule("org.apache.jmeter:ApacheJMeter_java", JmeterRule)
        withModule("org.apache.jmeter:ApacheJMeter", JmeterRule)
        withModule("org.apache.jmeter:ApacheJMeter_http", JmeterRule)
        withModule("org.apache.jmeter:ApacheJMeter_functions", JmeterRule)
        withModule("org.apache.jmeter:ApacheJMeter_components", JmeterRule)
        withModule("org.apache.jmeter:ApacheJMeter_config", JmeterRule)
        withModule("org.apache.jmeter:jorphan", JmeterRule)
    }
}

test {
    useJUnitPlatform()
}

// this is required due to JMeter open issue: https://bz.apache.org/bugzilla/show_bug.cgi?id=64465
@CacheableRule
class JmeterRule implements ComponentMetadataRule {
    void execute(ComponentMetadataContext context) {
        context.details.allVariants {
            withDependencies {
                removeAll { it.group == "org.apache.jmeter" && it.name == "bom" }
            }
        }
    }
}

The above Gradle will add the dependencies such as JUnit, AssertJ Fluent Assertions, and optionally, you can add Log4j.

Create a new Java class called HelloWorldTest in src\test\java folder and import the below directives.

import org.junit.jupiter.api.Test;
import us.abstracta.jmeter.javadsl.core.TestPlanStats;

import java.io.IOException;
import java.time.Instant;

import static us.abstracta.jmeter.javadsl.JmeterDsl.*;

public class HelloWorldTest {

}

In this example, we are going to build a simple JMeter test plan with the following elements:

• a Thread Group with 1 thread and 1 iteration,
  • an HTTP Sampler to get https://example.com,
    • an assertion to validate the response message, Example Domain

Here is the actual JMeter visualization:

Copy and paste the below block of code into the HelloWorldTest class.

    @Test
    public void testHelloWorld() throws IOException {

        TestPlanStats helloWorld = testPlan(
                threadGroup(1,1,
                        httpSampler("https://example.com")
                                .children(
                                        responseAssertion().containsSubstrings("Example Domain")
                                )
                ),
                jtlWriter("HelloWorld" + Instant.now().toString().replace(":","-") + ".jtl")
        ).run();
    }

As you observe above, the code is self-explanatory. We are defining a new TestPlanStats called helloWorld which will hold the test plan with one thread group.

That thread group will have one HTTP Sampler hitting https://example.com and which has one childeren to verify the response Example Domain.

jtlWriter logs the performance status and creates a unique *.jtl file in the current directory.

.run() method will execute the test plan as per the thread configuration.

To execute, either right click anywhere in the code and run or click on Run button as shown below.

Here is the output. *.jtl file will have the performance stats.

Congratulations! Now you have completed writing DSL in Java for JMeter. Now, we can hook this code into JMeter engine to run distributed tests across multiple hosts or put it on the cloud. But, please do not hit example.com with the load, replace it with your application under test URL.

Features of DSL

DSL is under active development. The team also released JMeter to DSL converter (work in progress). I will write another blog article featuring the converter. DSL comes with loads of features such as advanced thread group configuration, debugging, reporting, extractions, logical controllers and more.

Use the below code snippet which will launch the GUI for validation purpose.

testPlan(
                threadGroup(1,1,
                        httpSampler("https://example.com")
                                .children(
                                        responseAssertion().containsSubstrings("Example Domain")
                                )
                ),
                jtlWriter("HelloWorld" + Instant.now().toString().replace(":","-") + ".jtl")
        ).showInGui();

JMeter DSL is also powered by third party integrations like Elasticsearch, InfluxDB, and more.

To save the DSL as JMX, use the below code which will convert the DSL to JMX in the current directory.

        testPlan(
                threadGroup(1,1,
                        httpSampler("https://example.com")
                                .children(
                                        responseAssertion().containsSubstrings("Example Domain")
                                )
                ),
                jtlWriter("HelloWorld" + Instant.now().toString().replace(":","-") + ".jtl")
        ).saveAsJmx("HelloWorld.jmx");

Final Thoughts

JMeter DSL is an excellent initiative and welcomes doors to more developers as well as test engineers. JMeter-as-Code opens another multiverse which will break the legacy XML format into more developer-friendly, Git and IDE friendly, gels with the CI/CD pipeline naturally, and more. Developers must know how JMeter works, its execution order, scoping rules and more. Test engineers must know Java to get started.

As JMeter is heavy on the resource side, JMeter DSL inherits the same problem. It's too early to talk about Project Loom in JMeter ecosystem.