Up and running with JMeter

Now, let's get up and running with JMeter, beginning with its installation.

Installation

JMeter comes as a bundled archive, so it is super easy to get started with it. Those working in corporate environments behind a firewall or machines with non-admin privileges appreciate this more. To get started, grab the latest binary release by pointing your browser to http://jmeter.apache.org/download_jmeter.cgi. At the time of writing this, the current release version is 3.1. The download site offers the bundle as both a .zip file and a .tgz file. In this book, we go with the .zip file option, but feel free to download the .tgz file if that's your preferred way of grabbing archives.

Once downloaded, extract the archive to a location of your choice. Throughout this book, the location you extracted the archive to will be referred to as JMETER_HOME.

Provided you have a JDK/JRE correctly installed and a JAVA_HOME environment variable set, you are all set and ready to run!

The following screenshot shows a trimmed down directory structure of a vanilla JMeter install:

JMETER_HOME folder structure

The following are some of the folders in Apache-JMeter-3.2, as shown in the preceding screenshot:

• bin: This folder contains executable scripts to run and perform other operations in JMeter
• docs: This folder contains a well-documented user guide
• extras: This folder contains miscellaneous items, including
  samples illustrating the usage of the Apache Ant build tool
  (http://ant.apache.org/) with JMeter, and bean shell scripting
• lib: This folder contains utility JAR files needed by JMeter (you may add additional JARs here to use from within JMeter; we will cover this in detail later)
• printable_docs: This is the printable documentation

Installing Java JDK

Follow these steps to install Java JDK:

1. Go to http://www.oracle.com/technetwork/java/javase/downloads/index.html.
2. Download Java JDK (not JRE) compatible with the system that you will use to test. At the time of writing, JDK 1.8 (update 131) was the latest, and that's what we use throughout this book.
3. Double-click on the executable and follow the onscreen instructions.

On Windows systems, the default location for the JDK is under Program Files. While there is nothing wrong with this, the issue is that the folder name contains a space, which can sometimes be problematic when attempting to set PATH and run programs, such as JMeter, depending on the JDK from the command line. With this in mind, it is advisable to change the default location to something like C:\tools\jdk.

Setting up JAVA_HOME

Here are the steps to set up the JAVA_HOME environment variable on Windows and Unix operating systems.

On Windows

For illustrative purposes, assume that you have installed Java JDK at C:\tools\jdk:

1. Go to Control Panel.
2. Click on System.
3. Click on Advance System settings.
4. Add Environment to the following variables:
   • Value: JAVA_HOME
   • Path: C:\tools\jdk
5. Locate Path (under system variables, bottom half of the screen).
6. Click on Edit.
7. Append %JAVA_HOME%/bin to the end of the existing path value (if any).

On Unix

For illustrative purposes, assume that you have installed Java JDK at /opt/tools/jdk:

1. Open up a Terminal window.
2. Export JAVA_HOME=/opt/tools/jdk.
3. Export PATH=$PATH:$JAVA_HOME.

It is advisable to set this in your shell profile settings, such as .bash_profile
(for bash users) or .zshrc (for zsh users), so that you won't have to set it for each
new Terminal window you open.

Running JMeter

Once installed, the bin folder under the JMETER_HOME folder contains all the executable scripts that can be run. Based on the operating system that you installed JMeter on, you either execute the shell scripts (.sh file) for operating systems that are Unix/Linux flavored, or their batch (.bat file) counterparts on operating systems that are Windows flavored.

JMeter files are saved as XML files with a .jmx extension. We refer to them as test scripts or JMX files in this book.

These scripts include the following:

• jmeter.sh: This script launches JMeter GUI (the default)
• jmeter-n.sh: This script launches JMeter in non-GUI mode (takes a JMX file as input)
• jmeter-n-r.sh: This script launches JMeter in non-GUI mode remotely
• jmeter-t.sh: This opens a JMX file in the GUI
• jmeter-server.sh: This script starts JMeter in server mode (this will be kicked off on the master node when testing with multiple machines remotely; more on this in Chapter 6, Distributed Testing)
• mirror-server.sh: This script runs the mirror server for JMeter
• shutdown.sh: This script gracefully shuts down a running non-GUI instance
• stoptest.sh: This script abruptly shuts down a running non-GUI instance

To start JMeter, open a Terminal shell, change to the JMETER_HOME/bin folder, and run the following command on Unix/Linux:

./jmeter.sh

Alternatively, run the following command on Windows:

jmeter.bat

A short moment later, you will see the JMeter GUI displayed in the configuring proxy server section. Take a moment to explore the GUI. Hover over each icon to see a short description of what it does. The Apache JMeter team has done an excellent job with the GUI. Most icons are very similar to what you are used to, which helps ease the learning curve for new adapters. Some of the icons, for example, stop and shutdown, are disabled for now till a scenario/test is being conducted. In the next chapter, we will explore the GUI in more detail as we record our first test script.

The JVM_ARGS environment variable can be used to override JVM settings in the jmeter.bat or jmeter.sh script. Consider the following example:
export JVM_ARGS="-Xms1024m -Xmx1024m -Dpropname=propvalue".

Command-line options

To see all the options available to start JMeter, run the JMeter executable with the -? command. The options provided are as follows:

    ./jmeter.sh -?
    
    -?
        print command line options and exit
    -h, --help
        print usage information and exit
    -v, --version
        print the version information and exit
    -p, --propfile <argument>
        the jmeter property file to use
    -q, --addprop <argument>
        additional JMeter property file(s)
    -t, --testfile <argument>
        the jmeter test(.jmx) file to run
    -l, --logfile <argument>
        the file to log samples to
    -j, --jmeterlogfile <argument>
        jmeter run log file (jmeter.log)
    -n, --nongui
        run JMeter in nongui mode
    ...
    -J, --jmeterproperty <argument>=<value>
        Define additional JMeter properties
    -G, --globalproperty <argument>=<value>
        Define Global properties (sent to servers)
        e.g. -Gport=123
             or -Gglobal.properties
    -D, --systemproperty <argument>=<value>
        Define additional system properties
    -S, --systemPropertyFile <argument>
        additional system property file(s)
  

This is a snippet (non-exhaustive list) of what you might see if you did the same.
We will explore some, but not all, of these options as we go through the book.

JMeter's classpath

Since JMeter is 100 percent pure Java, it comes packed with functionalities to get most of the test cases scripted. However, there might come a time when you need to pull in a functionality provided by a third-party library, or one developed by yourself, which is not present by default. As such, JMeter provides two directories where such third-party libraries can be placed to be auto discovered on its classpath:

• JMETER_HOME/lib: This is used for utility JARs.
• JMETER_HOME/lib/ext: This is used for JMeter components and add-ons. All custom-developed JMeter components should be placed in the lib/ext folder, while third-party libraries (JAR files) should reside in the lib folder.

Configuring a proxy server

If you are working from behind a corporate firewall, you may need to configure JMeter to work with it, providing it with the proxy server host and port number.
To do so, supply additional command-line parameters to JMeter when starting
it up. Some of them are as follows:

• -H: This command-line parameter specifies the proxy server hostname or
  IP address
• -P: This specifies the proxy server port
• -u: This specifies the proxy server username if it is secure
• -a: This specifies the proxy server password if it is secure; consider the following example:

    ./jmeter.sh -H proxy.server -P 7567 -u username -a password

On Windows, run the jmeter.bat file instead.

Do not confuse the proxy server mentioned here with JMeter's built-in HTTP(S) Test Script Recorder, which is used to record HTTP or HTTPS browser sessions. We will be exploring this in the next chapter when we record our first test scenario.

The screen is displayed as follows:

JMeter GUI

Running in non-GUI mode

As described earlier, JMeter can run in non-GUI mode. This is needed when you run remotely, or want to optimize your testing system by not taking the extra overhead cost of running the GUI. Normally, you will run the default (GUI) when preparing your test scripts and running light load, but run the non-GUI mode for higher loads.

To do so, use the following command-line options:

• -n: This command-line option indicates running in non-GUI mode
• -t: This command-line option specifies the name of the JMX test file
• -l: This command-line option specifies the name of the JTL file to
  log results to
• -j: This command-line option specifies the name of the JMeter run log file
• -r: This command-line option runs the test servers specified by the
  remote_hosts JMeter property
• -R: This command-line option runs the test in the specified remote servers (for example, -Rserver1,server2)

In addition, you can also use the -H and -P options to specify proxy server host and post, as we saw earlier:

./jmeter.sh -n -t test_plan_01.jmx -l log.jtl

Running in server mode

This is used when performing distributed testing, that is, using more testing servers to generate additional load on your system. JMeter will be kicked off in server mode on each remote server (slave), and then a GUI on the master server will be used to control the slave nodes. We will discuss this in detail when we dive into distributed testing in Chapter 4, Managing Sessions:

./jmeter-server.sh

Specify the server.exitaftertest=true JMeter property if you want the server to exit after a single test is completed. It is set as off by default.

Overriding properties

JMeter provides two ways to override Java, JMeter, and logging properties. One way is to directly edit jmeter.properties, which resides in the JMETER_HOME/bin folder. I suggest that you take a peek into this file and see the vast number of properties you can override. This is one of the things that makes JMeter so powerful and flexible. On most occasions, you will not need to override the defaults, as they have sensible default values.

The other way to override these values is directly from the command line when starting JMeter.

The options available to you include the following ones:

• Defining a Java system property value:

    -D<property name>=<value>

• Defining a local JMeter property:

    -J<property name>=<value>

• Defining a JMeter property to be sent to all remote servers:

    -G<property name>=<value>

• Defining a file containing JMeter properties to be sent to all remote servers:

    -G<property file>

• Overriding a logging setting, setting a category to a given priority level:

    -L<category>=<priority>
    ./jmeter.sh -Duser.dir=/home/bobbyflare/jmeter_stuff 
    -Jremote_hosts=127.0.0.1 -Ljmeter.engine=DEBUG

Since command-line options are processed after the logging system has been set up, any attempt to use the -J flag to update the log_level or log_file properties will have no effect.