Running jmeter in Non-GUI mode

For load testing, you must run JMeter in this mode (Without the GUI) to get the optimal results from it. This post will show you how to do it, what is the command to run your Test Plan in Non-GUI mode and the meaning of each option in the command.

1. Non-GUI Mode

We will use the following command options to run JMeter in Non-GUI mode

-n

This specifies JMeter is to run in non-gui mode

-t

[name of JMX file that contains the Test Plan].

-l

[name of JTL file to log sample results to].

-j

[name of JMeter run log file].

-r

Run the test in the servers specified by the JMeter property “remote_hosts“

-R

[list of remote servers] Run the test in the specified remote servers

-g

[path to CSV file] generate report dashboard only

-e

generate report dashboard after load test

-o

output folder where to generate the report dashboard after load test. Folder must not exist or be empty

The script also lets you specify the optional firewall/proxy server information:

-H

[proxy server hostname or ip address]

-P

[proxy server port]

-N

[nonproxy hosts] (e.g. *.apache.org|localhost)

-u

[username for proxy authentication – if required]

-a

[password for proxy authentication – if required]

Example: Go to $JMETER_HOME/bin folder and run the command like below

Windows:

jmeter -n -t C:\jmeter\my-test-plan.jmx -l C:\jmeter\my-test-plan-result.jtl -j C:\jmeter\my-test-plan-result.log

Unix (MacOS, Linux, etc.):

./jmeter.sh -n -t /Users/user/jmeter/my-test-plan.jmx -l /Users/user/jmeter/my-test-plan-result.jtl -j /Users/user/jmeter/my-test-plan-result.log

2. Overriding Properties Via The Command Line

2.1 Context

Let consider this example. You’ve done the Test Plan for your project. Currently, you set up the Thread Group with Number of Threads (users) = 100, Ramp-Up Period = 60, and Duration = 180. It will be OK, you can use the command line in section 1 and run this test normally. But if you want to change the Duration to 300 instead of 180, how to do that? Okay, I think you will open the Test Plan by GUI Mode, and edit manually. Again, in another test, you don’t want to run 100 threads, it must be 500 threads. Oops, it’s really annoying if every time we must edit the information by opening GUI.

Then using Properties and pass it to the test via command line is the good way to achieve it. Let see how to do.

First, I will use the function __P to call the JMeter Properties, as the following

${__P(THREADS,100)} – means it will call the value of the property THREADS, if the  property is not exist, it will return the value 100 as default.

Second, we will override the Properties via the command line

Just use -D or -J flag with the property name. Syntax:

-DPROPERTY_NAME=PROPERTY_VALUE

Note: The flag -D and the property name has NO space.

Windows:

jmeter -n -t C:\jmeter\my-test-plan.jmx -l C:\jmeter\my-test-plan-result.jtl -j C:\jmeter\my-test-plan-result.log -DTHREADS=500 -DRAMP_UP=60 -DDURATION=300

Unix (MacOS, Linux, etc.):

./jmeter.sh -n -t /Users/user/jmeter/my-test-plan.jmx -l /Users/user/jmeter/my-test-plan-result.jtl -j /Users/user/jmeter/my-test-plan-result.log -DTHREADS=500 -DRAMP_UP=60 -DDURATION=300

And now you can easily modify these values just by changing it via the command line.

2.2 Options for JMeter Properties

Java system properties, JMeter properties, and logging properties can be overridden directly on the command line (instead of modifying jmeter.properties). To do so, use the following options:

-D[prop_name]=[value]

defines a java system property value.

-J[prop_name]=[value]

defines a local JMeter property.

-G[prop_name]=[value]

defines a JMeter property to be sent to all remote servers.

-G[propertyfile]

defines a file containing JMeter properties to be sent to all remote servers.

-L[category]=[priority]

overrides a logging setting, setting a particular category to the given priority level.

The -L flag can also be used without the category name to set the root logging level.

3. Reformat the command line

I think it’s not a mandatory thing must do with JMeter or Performance Test. It’s just some kinds of help for working effectively a bit.

Now, look back the command line above, it’s so long and hard to see it fully, clearly, isn’t it? Yes, you have to agree with me. And I will show you to format the command so we can view it easier.

Copy the command into any Text Editor. Let break the line into multiple lines

Windows:

jmeter -n -t C:\jmeter\my-test-plan.jmx ^
-l C:\jmeter\my-test-plan-result.jtl ^
-j C:\jmeter\my-test-plan-result.log ^
-DTHREADS=500 ^
-DRAMP_UP=60 ^
-DDURATION=300

Using ^ sign when you want to break down the line on Windows. Be careful, please don’t have any redundant space, if in the first line we have space at the end and ^, then in next line, it should be NO space anymore (in case the command has no extra space).

Unix (MacOS, Linux, etc.):

./jmeter.sh -n -t /Users/user/jmeter/my-test-plan.jmx \
   -l /Users/user/jmeter/my-test-plan-result.jtl \
   -j /Users/user/jmeter/my-test-plan-result.log \
   -DTHREADS=500 \
   -DRAMP_UP=60 \
   -DDURATION=300

With Unix, the character before breaking down the line is \. And in the next line, we can have the indent for more clear.

Note: Every time we need to break the line, use the character ^ (Wins) and \ (Unix). And please don’t use any special thing in the last line

4. Useful commands

4.1 Full list of command-line

Invoking JMeter as jmeter -h (Wins) or ./jmeter.sh -h (Unix) will print a list of all the command-line. These are shown below.

To list all command line options, open a command prompt and type:

jmeter.bat(Windows)/jmeter.sh(Linux) -?

--------------------------------------------------

To run Apache JMeter in GUI mode, open a command prompt and type:

jmeter.bat(Windows)/jmeter.sh(Linux) [-p property-file]

--------------------------------------------------

To run Apache JMeter in NON_GUI mode:
Open a command prompt (or Unix shell) and type:

jmeter.bat(Windows)/jmeter.sh(Linux) -n -t test-file [-p property-file] [-l results-file] [-j log-file]

--------------------------------------------------

To run Apache JMeter in NON_GUI mode and generate a report at end :
Open a command prompt (or Unix shell) and type:

jmeter.bat(Windows)/jmeter.sh(Linux) -n -t test-file [-p property-file] [-l results-file] [-j log-file] -e -o [Path to output folder]

--------------------------------------------------
To generate a Report from existing CSV file:
Open a command prompt (or Unix shell) and type:

jmeter.bat(Windows)/jmeter.sh(Linux) -g [csv results file] -o [path to output folder (empty or not existing)]

--------------------------------------------------

To tell Apache JMeter to use a proxy server:
Open a command prompt and type:

jmeter.bat(Windows)/jmeter.sh(Linux) -H [your.proxy.server] -P [your proxy server port]

---------------------------------------------------

To run Apache JMeter in server mode:
Open a command prompt and type:

jmeter-server.bat(Windows)/jmeter-server(Linux)

---------------------------------------------------

4.2 Full list of command-line options

Invoking JMeter as jmeter -? (Wins) or ./jmeter.sh -? (Unix) will print a list of all the command-line options. These are shown below.

Copyright (c) 1999-2016 The Apache Software Foundation

   --?
      print command line options and exit
   -h, --help
      print usage information and exit
   -v, --version
      print the version information and exit
   -p, --propfile 
      the jmeter property file to use
   -q, --addprop 
      additional JMeter property file(s)
   -t, --testfile 
      the jmeter test(.jmx) file to run
   -l, --logfile 
      the file to log samples to
   -j, --jmeterlogfile 
      jmeter run log file (jmeter.log)
   -n, --nongui
      run JMeter in nongui mode
   -s, --server
      run the JMeter server
   -H, --proxyHost 
      Set a proxy server for JMeter to use
   -P, --proxyPort 
      Set proxy server port for JMeter to use
   -N, --nonProxyHosts 
      Set nonproxy host list (e.g. *.apache.org|localhost)
   -u, --username 
      Set username for proxy server that JMeter is to use
   -a, --password 
      Set password for proxy server that JMeter is to use
   -J, --jmeterproperty =
      Define additional JMeter properties
   -G, --globalproperty =
      Define Global properties (sent to servers)
      e.g. -Gport=123
      or -Gglobal.properties
   -D, --systemproperty =
      Define additional system properties
   -S, --systemPropertyFile 
      additional system property file(s)
   -L, --loglevel =
      [category=]level e.g. jorphan=INFO or jmeter.util=DEBUG
   -r, --runremote
      Start remote servers (as defined in remote_hosts)
   -R, --remotestart 
      Start these remote servers (overrides remote_hosts)
   -d, --homedir 
      the jmeter home directory to use
   -X, --remoteexit
      Exit the remote servers at end of test (non-GUI)
   -g, --reportonly 
      generate report dashboard only, from a test results file
   -e, --reportatendofloadtests
      generate report dashboard after load test
   -o, --reportoutputfolder 
      output folder for report dashboard

4.3 Show JMeter version

Invoking JMeter as jmeter -v (Wins) or ./jmeter.sh -v (Unix) will print the version of JMeter. It is shown below.

5. Alternative command

In some case, the command cannot be run as expected above. It’s caused by:

• The java was not installed correctly or basically was not installed.
• Missing the System Variable Path.
• You don’t have the right to run the .bat file (Windows).
• etc.

And you should fix those issues above one by one. Once all issues are fixed, if you’re still facing with the command to run. So it’s time to try alternative command

java -jar ApacheJmeter.jar -n -t test-plan.jmx 

It just replaces the jmeter command on Windows and ./jmeter.sh on Unix by the java -jar ApacheJmeter.jar. And this command will work for all OS.