Running JMeter Using Local Command Line

Apache JMeter is a powerful open-source tool designed for performance and load testing of web applications and other services like databases, FTP, and APIs. While it is commonly used with its intuitive graphical interface, running JMeter from the command line offers significant advantages in automation, scalability, and resource efficiency.

Command line execution is valuable for continuous integration (CI) workflows, large-scale testing, and running tests without impacting system resources. It allows teams to automate and integrate testing seamlessly into their development pipelines.

This article explores various ways to launch JMeter, including JMeter command line execution and running JMeter tests in non-GUI mode.

3 Modes to Launch the Apache JMeter

Apache JMeter can be launched in three different modes, depending on your testing needs and environment:

• GUI Mode: This is the default mode, where JMeter opens with a graphical user interface. It is useful for creating, editing, and debugging test plans. However, due to the overhead of the graphical interface, it is not recommended for running large-scale or resource-intensive tests.

• Command Line Mode (Non-GUI Mode): In this mode, JMeter runs from the terminal or command prompt without a graphical interface. It is more efficient for running tests, especially for performance testing or automated testing with large loads, as it reduces system resource consumption.

• Server Mode (Non-GUI Mode): Server mode is used for distributed testing. Here, one machine acts as the master (client) and others act as slaves (remote servers) to simulate a higher number of virtual users. It helps scale tests across multiple machines, allowing for more extensive load testing.

Why Use JMeter in Command Line (Non-GUI) Mode?

Running JMeter in non-GUI mode offers several benefits that make it ideal for performance testing in real-world environments:

• Improved Performance: Non-GUI mode consumes fewer system resources than GUI mode, allowing for more efficient execution of large or complex test plans while conserving system resources.

• Accurate Test Results: JMeter command line execution ensures more accurate and reliable test results, especially under high load, by eliminating the graphical interface overhead.
• Automation Friendly: Non-GUI mode integrates easily into CI/CD pipelines or test scripts, enabling continuous testing and streamlining the testing workflow.

• Suitable for Remote Execution: JMeter tests can be run on remote servers or headless environments where the GUI is unavailable. This is useful for distributed testing and executing tests on server-based setups.

• Scalability: Command-line mode supports distributed testing, enabling multiple machines to contribute to test execution. This is essential for simulating a large number of users and expanding test setups as needed.

How to Invoke a JMeter Test from the Command Line

Running a JMeter test from the command line is a quick and efficient way to execute test plans without launching the graphical user interface. This is especially useful for automation, headless environments, or running tests as part of a CI/CD pipeline.

Here are the steps for JMeter command line execution:

1. Ensure Apache JMeter and Java are installed on your system.
2. Ensure that the environment variable PATH is set for both JMeter and Java.
3. Open CMD (on Windows) or Terminal (on Mac) and enter the following command:

For Windows:

jmeter -n -t "C:\path\to\testplan.jmx" -l "C:\path\to\results.jtl" -e -o "C:\path\to\output-folder"

For Mac:

jmeter -n -t /Users/yourname/path/to/testplan.jmx -l /Users/yourname/path/to/results.jtl -e -o /Users/yourname/path/to/output-folder

This command runs the test plan and saves the raw results, which can later be used to generate reports or analyze performance metrics. An HTML report is also generated automatically in the specified output folder.

Output:

This output confirms that the test was executed successfully and shows performance metrics such as average response time, error rate, and requests per second. The results can be reviewed in the .jtl file or through the generated HTML report.

Explanation of command-line flags :

• -n (Non-GUI mode): This flag runs JMeter without opening the graphical interface. It is mandatory for command-line execution and helps save system resources.
• -t (Test Plan): Specifies the path to the .jmx test plan file that you want to execute. Make sure the file exists and is correctly configured.
• -l (Log file): Defines the path where test results should be saved in .jtl format. This file contains raw data that can be used for later analysis or report generation.
• -e (Generate report): Instructs JMeter to automatically create an HTML report after the test run is complete. It processes the .jtl file and summarizes the results.
• -o (Output folder): Sets the directory where the HTML report will be stored. The folder must be empty or not already exist before the test starts.

Advanced Methods for JMeter Command Line Execution

Server (Non-GUI) mode in Apache JMeter enables performance testing at scale by distributing test execution across multiple machines. This allows you to simulate high loads efficiently. Below are three advanced methods for JMeter command line execution that work well in non-GUI mode and are suitable for CI/CD and large-scale testing environments.

1. Execute JMeter Tests with Apache Ant

Apache Ant is a Java-based build tool for automating tasks such as compiling code, packaging files, and running test scripts. It can also trigger JMeter test plans in a structured and repeatable way.

Here are step-by-step instructions to use Apache Ant to execute JMeter tests:

1. Install Apache Ant on your System

Download Ant from the official site. Unzip the package and set the environment variables:

• For Windows:

set ANT_HOME=C:\path\to\apache-ant

set PATH=%ANT_HOME%\bin;%PATH%

• For Mac:

export ANT_HOME=/path/to/apache-ant

export PATH=$ANT_HOME/bin:$PATH

• Verify the installation by running:

ant -version

This will return the Ant version number.

2. Create a JMeter Test Plan

Save your .jmx test plan (e.g., testplan.jmx) in the working directory. If you’re new to JMeter test plans, they can be created using the JMeter GUI or manually by writing the XML configuration.

3. Set Up Ant Build File

Create a file named build.xml in the same directory with the following content:

<project name="JMeterTest" default="run" basedir=".">

    <property name="jmeter.home" location="/path/to/jmeter" />

    <property name="test.plan" location="testplan.jmx" />

    <property name="result.file" location="results.jtl" />



    <target name="run">

        <exec executable="${jmeter.home}/bin/jmeter">

            <arg value="-n"/>

            <arg value="-t"/>

            <arg value="${test.plan}"/>

            <arg value="-l"/>

            <arg value="${result.file}"/>

        </exec>

    </target>

</project>

Replace /path/to/jmeter with your actual JMeter installation path.

Explanation of the Ant Build File:

• <property name=”jmeter.home” location=”/path/to/jmeter” />: Defines the path to your JMeter installation. This is a placeholder to keep paths organized.
• <property name=”test.plan” location=”testplan.jmx” />: Points to the .jmx test plan file to be executed.
• <property name=”result.file” location=”results.jtl” />: Specifies the location where the results will be stored in a .jtl file.
• <exec executable=”${jmeter.home}/bin/jmeter”>: Executes the JMeter command. The command inside <exec> will run JMeter in non-GUI mode.
• <arg value=”-n”/>: Runs JMeter in Non-GUI mode.
• <arg value=”-t”/>: Specifies the path to the .jmx file to be executed.
• <arg value=”-l”/>: Tells JMeter to save the results in a file.

4. Run the Test Using Ant

In the terminal or command prompt, run:

ant

This will execute the test in non-GUI mode using the .jmx file and generate results in a .jtl file.

5. Expected Output

Terminal output will show something like:

6. Common Issues

Here are common issues you might encounter while executing the test, along with tips for troubleshooting:

• Java or Ant Not Found: If Ant or Java is not found, double-check that the environment variables (ANT_HOME and JAVA_HOME) are set correctly and that their paths are included in your PATH.
• File Path Issues: Make sure the paths to the JMeter binary and .jmx test plan are correct in the build.xml file. If your test plan file is in a different directory, adjust the <property name=”test.plan” location=”testplan.jmx” /> line to point to the correct path.
• Out-of-Memory Issues: JMeter tests can consume a lot of memory, especially when simulating many users. If you encounter out-of-memory errors, you can increase the heap size by editing the jmeter.bat (Windows) or jmeter.sh (Mac/Linux) file in the bin/ folder and adjusting the HEAP variable.

2. Use Apache Maven to Execute JMeter Tests

Apache Maven is a powerful build automation tool used primarily for Java projects. With the help of the JMeter Maven Plugin, you can easily run JMeter tests as part of your build lifecycle, which makes it useful for automation and integration in CI/CD pipelines.

Here are step-by-step instructions to use Apache Maven to execute JMeter tests:

1. Install Apache Maven

Download Maven from the official site. Unzip the archive and set up the environment variables.

• For Windows:

set MAVEN_HOME=C:\path\to\apache-maven

Set PATH=%MAVEN_HOME%\bin;%PATH%

• For Mac:

export MAVEN_HOME=/path/to/apache-maven

export PATH=$MAVEN_HOME/bin:$PATH

Verify the installation by running:

mvn -version

This will return the version number.

2. Create a Maven Project Folder Structure with JMeter Plugin

Create a folder for your Maven project (e.g., jmeter-maven-test), and navigate to it. This folder will hold the necessary project structure.

The structure should look like this:

• pom.xml: Maven configuration file.
• src/test/jmeter/testplan.jmx: JMeter test plan file.

Place your .jmx test plan (e.g., testplan.jmx) under the src/test/jmeter/ directory. For this tutorial, the .jmx file name is testplan.jmx

3. Configure the Maven pom.xml File

Create and edit the pom.xml file and paste the following code:

<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>com.example</groupId>

    <artifactId>jmeter-test</artifactId>

    <version>1.0-SNAPSHOT</version>



    <build>

        <plugins>

            <plugin>

                <groupId>com.lazerycode.jmeter</groupId>

                <artifactId>jmeter-maven-plugin</artifactId>

                <version>3.4.0</version>

                <executions>

                    <!-- Step 1: Configure JMeter plugin -->

                    <execution>

                        <id>configuration</id>

                        <goals>

                            <goal>configure</goal>

                        </goals>

                    </execution>



                    <!-- Step 2: Run JMeter tests -->

                    <execution>

                        <id>jmeter-tests</id>

                        <goals>

                            <goal>jmeter</goal>

                        </goals>

                    </execution>

                </executions>

            </plugin>

        </plugins>

    </build>

</project>

This configuration ensures that Maven uses the JMeter Maven Plugin to run the JMeter tests.

• The <goal>configure</goal> goal prepares the environment.
• The <goal>jmeter</goal> goal executes the JMeter test plan.

4. Run the Test Using Maven

In your terminal, navigate to the project directory and execute the following command:

mvn verify

This command compiles the project and runs your JMeter test plan using the plugin.

After the command runs, Maven generates test results and saves them in the target/jmeter/ directory. This will include the result files in formats such as .jtl and the generated reports.

The reports and results, including information such as throughput, response time, and errors, will be in the target/jmeter/directory. Here’s how the output will look.

3. Run a JMeter Test from Java Code

You can also run JMeter test plans programmatically using Java code. This is useful if you want to integrate performance tests into a custom framework, run dynamic test plans, or trigger tests from within other applications.

Here are the steps to run a JMeter test from Java code:

1. Create Folder Structure

To begin running a JMeter test from Java code, you first need to set up a proper project structure. This ensures that JMeter dependencies and your test plans are neatly organized, making it easier to maintain and run tests programmatically.

Here’s how the folder structure should look:

2. Create and Save the pom.xml File:

Create a file named pom.xml in the root directory (jmeter-java-test/). Open it in a text editor and paste the following Maven configuration:

<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>com.example</groupId>

    <artifactId>jmeter-java-test</artifactId>

    <version>1.0-SNAPSHOT</version>



    <dependencies>

        <dependency>

            <groupId>org.apache.jmeter</groupId>

            <artifactId>ApacheJMeter_core</artifactId>

            <version>5.6.3</version>

        </dependency>

        <dependency>

            <groupId>org.apache.jmeter</groupId>

            <artifactId>ApacheJMeter_components</artifactId>

            <version>5.6.3</version>

        </dependency>

        <dependency>

            <groupId>org.apache.jmeter</groupId>

            <artifactId>ApacheJMeter_functions</artifactId>

            <version>5.6.3</version>

        </dependency>

    </dependencies>



    <build>

        <plugins>

            <plugin>

                <groupId>org.codehaus.mojo</groupId>

                <artifactId>exec-maven-plugin</artifactId>

                <version>3.1.0</version>

                <configuration>

                    <mainClass>com.example.JMeterRunner</mainClass>

                </configuration>

            </plugin>

        </plugins>

    </build>

</project>

This configuration defines the necessary JMeter dependencies and sets up the exec-maven-plugin to run the JMeterRunner Java class.

3. Create the Java Code (JMeterRunner.java):

Inside the src/main/java/com/example/ folder, create the file JMeterRunner.java and add the following code to run the JMeter test:

package com.example;



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.File;



public class JMeterRunner {

    public static void main(String[] args) {

        // Set JMeter home

        String jmeterHome = "<JMeter Path Here>";  // Update this path



        // Set JMeter properties and initialize

        JMeterUtils.setJMeterHome(jmeterHome);

        JMeterUtils.loadJMeterProperties(jmeterHome + "/bin/jmeter.properties");

        JMeterUtils.initLocale();



        // Load the JMeter test plan (JMX file)

        File jmxFile = new File("test/jmeter/testplan.jmx");  // Update path if needed

        try {

            HashTree testPlanTree = SaveService.loadTree(jmxFile);



            // Set up the engine to run the test plan

            StandardJMeterEngine jmeter = new StandardJMeterEngine();

            jmeter.configure(testPlanTree);

            jmeter.run();

        } catch (Exception e) {

            e.printStackTrace();

        }

    }

}

Update the jmeterHome path and testplan.jmx path according to your system.

4. Build and Run the Test Using Maven:

After creating the folder structure, pom.xml, and Java code, you can compile and run the test using Maven.

• Open a terminal or command prompt.
• Navigate to the root directory of your project (jmeter-java-test/).
• Run the following command to compile the project:

mvn compile

• Once the project is compiled, run the Java code with:

mvn exec:java

Maven will automatically download the dependencies (like JMeter libraries) and execute the JMeterRunner.java class to run the JMeter test plan (testplan.jmx).

After a successful run, the output in the terminal will indicate the success of the test execution. You should also see generated result files, such as .jtl files or any logs based on your test plan.

Why Perform Load Tests on Real Devices with BrowserStack Performance Testing?

While JMeter is a popular tool for load testing, it primarily focuses on protocol-level testing and doesn’t fully replicate the actual user experience on real devices and browsers. This can result in missing critical performance insights on how an application performs on actual devices or under browser-specific conditions.

BrowserStack Performance Testing bridges this gap by providing access to real devices and browsers to conduct load tests that simulate genuine user interactions.

Here are a few reasons to use BrowserStack Performance Testing.

• Real Device Cloud: Run load tests on real desktop and mobile devices across multiple OS-browser combinations to accurately simulate real-world usage.
• Global Infrastructure for Geo-Distributed Load: Generate load from multiple global locations to test your application’s performance under distributed traffic patterns.
• Hybrid Load Testing (Protocol + Browser Level): Integrate protocol-level tools like JMeter, K6, or Artillery with browser-level tools such as Selenium or Playwright to gain comprehensive performance insights for both the backend and front end.
• CI/CD Integration: Integrate with popular CI tools like Jenkins, GitHub Actions, CircleCI, and others to automate load and performance testing in your deployment pipeline.
• Advanced Debugging and Analytics: Access network logs, console logs, screenshots, and video recordings that help you analyze failures or performance bottlenecks effectively.

Talk to an Expert

Conclusion

Apache JMeter offers multiple ways to run tests beyond the GUI, including direct command-line execution, integration with build tools like Ant and Maven, and programmatic execution through Java code. These options provide the flexibility needed to automate and scale testing, making  JMeter a valuable tool for both development and QA teams.

Using JMeter in command-line mode is essential for efficient and scalable performance testing. It enables you to execute tests without the overhead of a graphical interface, making it ideal for large test plans, continuous integration pipelines, and headless environments. It also ensures better use of system resources and delivers more accurate results under load.

Try BrowserStack for Free