May. 7th, 2016

Five Ways To Launch a JMeter Test without Using the JMeter GUI

As we have already covered in JMeter Performance and Tuning Tips, the JMeter GUI should only be used for test development or debugging. We do not advise using JMeter in GUI mode if you are initiating an actual load test, even with JMeter's updated GUI in its 3.1 and 3.2 versions. This article highlights the most commonly used options for unattended test execution – from simple JMeter command-line mode to the use of the BlazeMeter API to initiate a 1,000-user load test without even opening a browser.

 

1. USE THE COMMAND LINE

 

You can execute JMeter test from the command line. It is as simple as

 

jmeter -n -t your_script.jmx

 

where

 

  • -n - tells JMeter to run in non-GUI mode
  • -t - specifies the path to source .jmx script to run

 

We often use these minimal options in combination with -l switch, which tells JMeter where to store test results. If a results file already exists, it will be appended. After the test execution you can open the resulting CSV file with any Listener, Excel, or any other analytics software.

 

If you want more details, see “How do I run JMeter in non-GUI mode?” or use the -h parameter to quickly view all possible command line options.

 

2. USE APACHE ANT

 

You can integrate JMeter with Apache Ant using the JMeter Ant Task. Once you have properly formed an Ant build XML configuration file, you can initiate the JMeter script using Ant. (To see a sample JMeter test plan, look in the /extras folder of your JMeter installation. It’s called Test.jmx. The example build.xml Ant configuration file is in the same location.)

 

Assuming Apache Ant is properly installed, go to the /extras folder and invoke an Ant command there. Ant looks for a build.xml file under the current directory and processes it.

 

 

As shown above, Ant picks up the Test.jmx file, executes it, and generates an easily-readable HTML report.

 

 

3. USE APACHE MAVEN

 

You can integrate JMeter with Apache Maven using the JMeter Maven Plugin. Maven uses a pom.xml file where POM stands for “Project Object Model” as a fundamental unit of work to be done. To enable JMeter integration, you must add a <build> event to pom.xml. The Maven project structure should look like the following:

 

JMeter can be integrated with Apache Maven via the JMeter Maven Plugin. Maven uses a pom.xml file where POM stands for “Project Object Model” as a fundamental unit of work to be done. To enable JMeter integration you need to add a <build> event to pom.xml file. The Maven project structure should look as follows:

 

Folder structure:

 

  • root folder
    • src
      • test
        • jmeter
          • Test.jmx
    • pom.xml

 

Where:

 

  • Test.jmx – can be copied???? from jmeter/extras
  • pom.xml - see the minimum listing below?

<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/maven-v4_0_0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.blazemeter</groupId>
    <artifactId>mvn-jmeter</artifactId>
    <packaging>jar</packaging>
    <version>1.0-SNAPSHOT</version>
    <name>maven-jmeter-demo</name>
    <url>http://maven.apache.org</url>
    <build>
        <plugins>
            <plugin>
                <groupId>com.lazerycode.jmeter</groupId>
                <artifactId>jmeter-maven-plugin</artifactId>
                <version>1.4.1</version>
                <executions>
                    <execution>
                        <id>jmeter-tests</id>
                        <phase>verify</phase>
                        <goals>
                            <goal>jmeter</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

 

To kick off the test, type mvn verify or mvn install in the root folder. You should see some Maven output in the command prompt:

 

 

For basic and advanced configuration options, consult the Maven JMeter Plugin Project Wiki.

 

The HTML report that’s created is identical to the one generated by Apache Ant.

 

4. RUN A JMETER TEST THROUGH A PROGRAM (FROM JAVA CODE)

 

Another option is to run a JMeter script from Java code. To execute an existing JMeter test from Java code or to create one through programming, basic Java knowledge is a must, and the following are mandatory:

 

  1. Have JMeter installed somewhere
  2. Have the required JMeter jars from /lib and especially /lib/ext folders of your JMeter installation in your project or module class path.

 

4.2 Running an existing JMeter Test from Java code

 

The main class, which is the “heart” of JMeter is StandardJMeterEngine. If you must execute a JMeter test from Java code, this is the best option. Alternatively, you can extend this class or implement your own version of the JMeterEngine interface.

 

The absolute minimal code to read the existing .jmx file (again we’re referring to Test.jmx from the /extras folder of the JMeter standard installation) and execute it will be as follows:

 

package com.blazemeter.demo;

import org.apache.jmeter.engine.StandardJMeterEngine;
import org.apache.jmeter.save.SaveService;
import org.apache.jmeter.util.JMeterUtils;
import org.apache.jorphan.collections.HashTree;
import java.io.FileInputStream;

public class JMeterFromExistingJMX {

    public static void main(String[] argv) throws Exception {
        // JMeter Engine
        StandardJMeterEngine jmeter = new StandardJMeterEngine();


        // Initialize Properties, logging, locale, etc.
        JMeterUtils.loadJMeterProperties("/path/to/your/jmeter/bin/jmeter.properties");
        JMeterUtils.setJMeterHome("/path/to/your/jmeter");
        JMeterUtils.initLogging();// you can comment this line out to see extra log messages of i.e. DEBUG level
        JMeterUtils.initLocale();

        // Initialize JMeter SaveService
        SaveService.loadProperties();

        // Load existing .jmx Test Plan
        FileInputStream in = new FileInputStream("/path/to/your/jmeter/extras/Test.jmx");
        HashTree testPlanTree = SaveService.loadTree(in);
        in.close();

        // Run JMeter Test
        jmeter.configure(testPlanTree);
        jmeter.run();
    }
}

 

Easy enough, isn’t it?

 

4.3 Creating a New JMeter Test Purely in Java

 

Here's how to build a JMeter Test Plan from scratch using Java code only. The key classes to look into are:

 

  1. StandardJMeterEngine - The main class that which configures the Test Plan and executes it.
  2. HashTree - A special collection that holds Test Plan elements.
  3. A minimum of JMeter Controllers necessary to run the test:

 

○      TestPlan - The root container for all below plus the place where all test properties can be specified

○      ThreadGroup - A pool of users to execute the test. A test must have at least one Thread Group with at least one thread and one loop.

○      LoopController - Since you must have at least one loop, it’s essential to have a Loop Controller instance set as a main Sampler controller for a Thread Group.

○      A Sampler to do the actual work.

 

This demo uses all of the above to send one GET request with one user in one loop using the HTTPSampler to the example.com domain.

 

This example is minimalistic and doesn’t have any extras. This simply gives you an idea of how to start. The code should be self-explanatory.

 

package com.blazemeter.demo;


import org.apache.jmeter.control.LoopController;
import org.apache.jmeter.engine.StandardJMeterEngine;
import org.apache.jmeter.protocol.http.sampler.HTTPSampler;
import org.apache.jmeter.testelement.TestPlan;
import org.apache.jmeter.threads.ThreadGroup;
import org.apache.jmeter.util.JMeterUtils;
import org.apache.jorphan.collections.HashTree;


public class JMeterFromScratch {

    public static void main(String[] argv) throws Exception {

        //JMeter Engine
        StandardJMeterEngine jmeter = new StandardJMeterEngine();

        //JMeter initialization (properties, log levels, locale, etc)
        JMeterUtils.loadJMeterProperties("/path/to/your/jmeter/bin/jmeter.properties");
        JMeterUtils.initLogging();// you can comment this line out to see extra log messages of i.e. DEBUG level
        JMeterUtils.initLocale();

        // JMeter Test Plan, basic all u JOrphan HashTree
        HashTree testPlanTree = new HashTree();

        // HTTP Sampler
        HTTPSampler httpSampler = new HTTPSampler();
        httpSampler.setDomain("example.com");
        httpSampler.setPort(80);
        httpSampler.setPath("/");
        httpSampler.setMethod("GET");

        // Loop Controller
        LoopController loopController = new LoopController();
        loopController.setLoops(1);
        loopController.addTestElement(httpSampler);
        loopController.setFirst(true);
        loopController.initialize();


        // Thread Group
        ThreadGroup threadGroup = new ThreadGroup();
        threadGroup.setNumThreads(1);
        threadGroup.setRampUp(1);
        threadGroup.setSamplerController(loopController);

        // Test Plan
        TestPlan testPlan = new TestPlan("Create JMeter Script From Java Code");

        // Construct Test Plan from previously initialized elements
        testPlanTree.add("testPlan", testPlan);
        testPlanTree.add("loopController", loopController);
        testPlanTree.add("threadGroup", threadGroup);
        testPlanTree.add("httpSampler", httpSampler);

        // Run Test Plan
        jmeter.configure(testPlanTree);
        jmeter.run();

    }
}

To verify the code actually sends GET request to example.com, a sniffer tool like Wireshark can be used.

 

 

Similarly, you can add any listener to your test to verify the output with JMeter GUI Listeners or third-party tools.

 

5. RUN A BLAZEMETER TEST USING A PROGRAM

 

BlazeMeter provides a REST API that enables you to perform various tasks in an unattended manner using any tool, library, or software capable of sending HTTP requests. That means you can do the following actions by sending a single request to one a BlazeMeter API endpoint:

 

  • Create a test
  • Upload new or update existing script file
  • Start the test
  • Get test status
  • Stop the test

 

All these tasks assume a user_key mandatory parameter. The user API key is available on the Profile Page. To reach the Profile Page, click your user name in the top right corner of the screen, to the left of the Logout link, and expand the User Key section at the Profile page.

 

This demo uses the curl command-line utility (a free, open-source, cross-platform and multi-protocol utility for transferring data to and from endpoints with a URL syntax).

 

Create the Test

 

Creating a new BlazeMeter test is as easy as sending a GET request to a REST URL. See details below:

 

Parameters:

 

URL

https://a.blazemeter.com/api/rest/blazemeter/testCreate

Method

GET

user_key

API user key available at the Profile page

test_name

any meaningful string

 

Example:

 

:~>curl "https://a.blazemeter.com/api/rest/blazemeter/testCreate?user_key=blazemeter_demo_key&test_name=MyFirstTest"

---

response_code: 200

error: null

test_id: 525901

test_name: null

 

The request goes before the three dashes (“---”). The response comes  after the three dashes. As you see, the response code is HTTP 200, which is OK. The ID of the test is returned. Mentioning the ID is a must to start or stop the test and to get its status and report link.

 

Upload a JMeter .jmx Test Script

 

Adding a new .jmx file to an existing test or replacing an old one with a newer version can be done as follows:

 

URL

https://a.blazemeter.com/api/rest/blazemeter/testScriptUpload

Method

POST

user_key

API user key available at Profile page

test_id

ID of test available as createTest response or at Test page after Test Name

 

Path to JMeter .jmx file to be uploaded

 

:~>curl -X POST "https://a.blazemeter.com/api/rest/blazemeter/testScriptUpload?user_key=blazemeter_demo_key&test_id=525901" -H "Content-Type: application/json" --data-binary "/path/to/your/jmeter/script/Test.jmx"

---

response_code: 200

error: null

 

Starting a Test in BlazeMeter

 

You can initiate a Blazemeter test by issuing a request in the following structure:

 

URL

http://blazemeter.com/api/rest/blazemeter/testStart/

user_key

API user key available at Profile page

test_id

ID of test available as createTest response or at Test page after Test Name

 

:~>curl "https://a.blazemeter.com/api/rest/blazemeter/testStart?user_key=blazemeter_demo_key&test_id=525901"

---

response_code: 200

error: null

test_id: 525901

type: null

test_name: MyFirstTest

session_id: r-ec53490fab83a51

:~>

 

Getting the Test Status in BlazeMeter

 

You can obtain the test status by sending a proper GET request to the getTestStatus endpoint.

 

URL

https://a.blazemeter.com/api/rest/blazemeter/testGetStatus

user_key

API user key available at Profile page

test_id

ID of test available as createTest response or at Test page after Test Name

 

:~>curl "https://a.blazemeter.com/api/rest/blazemeter/testGetStatus?user_key=blazemeter_demo_key&test_id=525901"

---

response_code: 200

error: null

test_id: 525901

session_id: r-ec534910ae2407d

status: Running

test_name: MyFirstTest

:~>

 

As we’ve just kicked off the test it’s currently in “Running” state.

 

Stopping a Test in BlazeMeter

 

Just like starting a test, you can also issue a command to stop test execution.

 

URL

https://a.blazemeter.com/api/rest/blazemeter/testStop

user_key

API user key available at Profile page

test_id

ID of test available as createTest response or at Test page after Test Name

 

:~>curl "https://a.blazemeter.com/api/rest/blazemeter/testStop?user_key=blazemeter_demo_key&test_id=525901"

---

response_code: 200

error: null

session_id: r-ec53490fab83a51

:~>

 

You can verify that the test has been actually stopped by querying the test status one more time:

 

:~>curl "https://a.blazemeter.com/api/rest/blazemeter/testGetStatus?user_key=blazemeter_demo_key&test_id=525901"

---

response_code: 200

error: null

test_id: 525901

session_id:

status: Not Running

test_name: MyFirstTest

:~>

 

As this confirms, the test is in a “Not Running” state.

 

SUMMARY / RESOURCES

 

In this article, we’ve highlighted the most common options executing a JMeter test. For additional information and other techniques, consider such as:

 

 

Regardless of which method you chose to match your environment and infrastructure, be sure to never use JMeter GUI for anything but test development and/or debugging.

 

Want to Learn More About JMeter & Load Testing?


If you are new to JMeter, and you’d like to learn more, please sign up for our free online JMeter training course.

 

For more experienced JMeter users, you'll want to view the on-demand webcast, How to Create Advanced Load Testing Scenarios with JMeter

 

 

Interested in writing for our Blog? Send us a pitch!