Apache JMeter is an open source application tool designed to load test functional behavior and measure performance on static pages, dynamic resources, and web applications. It can be used to simulate a heavy load on a server or group of servers, database, or network to test its strength, or to analyze overall performance under different load types.

In this post, I'll provide an introduction to JMeter with the goal to get you up and running (and testing!), more quickly and easily. Much of what is below is taken directly from the JMeter documentation with additional caveats.

Getting Started, Requirements, Installation

Official Documentation - Getting Started

JMeter can be used for test plan building, load test running, and load test analysis. It has a GUI mode that allows you to create test plans manually, choose from a variety of templates, or record the application from a browser session. GUI mode also allows for debugging and viewing results.

Once your test plan is ready, you can use the non-GUI mode to run a load test from the command line. You can generate a CSV or XML file containing results and have JMeter generate an HTML report from that data.

JMeter is a 100% Java application and should run correctly on any system that has Java installed correctly. It does require Java version 8. For JDBC testing, you will need to add your database vendor's JDBC driver to the classpath, or include the jar file in the jmeterlib folder. Make sure the file is a jar file, not a zip. To install Java, get the latest version 8 of the JRE or JDK from Oracle's Java download site.

For Windows, download the exe file and run it. On CentOS 7.x, download the latest rpm and run yum localinstall jdk-8u152-linux-x64.rpm. On Ubuntu 16.x, run sudo apt-get install oracle-java8-installer.

Java will be installed in the lib or lib64 directory. To verify that it is installed you can run java -version to see what version is being used.

To install JMeter, it is recommended to download the latest release. Unzip the zip/tar file into the directory where you want JMeter to be installed. If you have a JRE/JDK correctly installed and the JAVA_HOME environment variable set, there is nothing more to do.

Here is the basic directory structure. Along with I have added the tests, results, and reports directories to help with organization:

The bin directory will be where you run JMeter from. The lib directory is where you can add additional jar files, for example, JDBC drivers for database testing.

Store your test scripts (JMX files) in the tests directory. Direct output results to the results directory. CSV is recommended, but JTL files are also an option. HTML Dashboard Reports can be generated to the reports directory.

Building a Test Plan Overview

Official Documentation - Building a Test Plan

A test plan describes the steps that JMeter will execute when run. It will consist of one or more Thread Groups, logic controllers, sample generating controllers, listeners, timers, assertions, and configuration elements.

Adding elements to a test plan can be done by right-clicking on an element in the tree and choosing a new element from the add list. Changes to the Test Plan are automatically saved when you move between tree elements, but you should save to a file before running it. To save the Test Plan, select "Save" or "Save Test Plan As ..." from the File menu.

The workbench is not automatically saved with the test plan, but it can be saved by checking "Save Workbench" option on Workbench element.

To run your test plan, choose Start from the Run menu. Stop stops the threads immediately if possible. Many samplers can be terminated early. Shutdown requests the threads to stop at the end of any current work. Will not interrupt any active samples.

Elements of a Test Plan

Official Documentation - Test Plan

The Test Plan object is the top element of the tree.

Configuration Elements

• HTTP Request Defaults - set defaults that are used for all HTTP requests. For example, server name or IP, port number, etc.
• HTTP Cookie Manager - will manage cookies during the tests
• User Defined Variables - used to store data that you don't want to hardcode in the test. For example, username and password.

Thread Group

Thread Group elements are the beginning points of any test plan. All controllers and samplers must be under a thread group. The thread group element controls the number of threads (users) JMeter will use to execute your test. The controls for a thread group allow you to:

• Set the number of threads (users)
• Set the ramp-up period (in seconds)
• Set the number of times to execute the test

Each thread will execute the test plan in its entirety and completely independently of other test threads.

Multiple threads are used to simulate concurrent connections to your server application.

The ramp-up period tells JMeter how long to take to "ramp-up" to the full number of threads chosen. If 10 threads are used, and the ramp-up period is 100 seconds, then JMeter will take 100 seconds to get all 10 threads up and running. Each thread will start 10 (100/10) seconds after the previous thread was begun. If there are 30 threads and a ramp-up period of 120 seconds, then each successive thread will be delayed by 4 seconds.

Ramp-up needs to be long enough to avoid too large a workload at the start of a test, and short enough that the last threads start running before the first ones finish (unless one wants that to happen).
Start with Ramp-up = number of threads and adjust up or down as needed.

Controllers

JMeter has two types of Controllers: Samplers and Logical Controllers. These drive the processing of a test.
Samplers tell JMeter to send requests to a server and wait for a response. They are processed in the order they appear in the tree. JMeter samplers included in our tests are:

Each sampler has several properties you can set. Logical Controllers let you customize the logic that JMeter uses to decide when to send requests. For example, you can add a Recording Controller to capture HTTP requests as you record them and use for your testing script.

Listeners

Listeners provide access to the information JMeter gathers about the test cases while JMeter runs.

• The Graph Results listener plots the response times on a graph.
• The View Results Tree Listener shows details of sampler requests and responses, and can display basic HTML and XML representations of the response.
• The Summary Report creates a table row for each differently named request in your test.
• The Response Time Graph draws a line chart showing the evolution of response time during the test, for each labeled request.

Additionally, listeners can direct the data to a file for later use. Every listener in JMeter provides a field to indicate the file to store data to. There is also a Configuration button which can be used to choose which fields to save, and whether to use CSV or XML format.

Timers

By default, a JMeter thread executes samplers in sequence without pausing. We recommend that you specify a delay by adding one of the available Timers to your Thread Group.

Post-Processors

A Post-Processor executes some action after a Sampler Request has been made. If a Post-Processor is attached to a Sampler element, then it will execute just after that sampler element runs. We will user a Regular Expression Extractor to get the CSRF Token needed to maintain the login.

Building a Web Test Plan

Official Documentation - Building a Web Test Plan

Add a Thread Group (Users) by: Add > Thread Group.
Key fields are Number of Threads (users), Ramp-Up Period (seconds), and Loop Count.

Add User Defined Variables by: Add > Config Element > User Defined Variables.
This is a good place to put Username, Password, and any other variables that may need to reused throughout the test.

Add HTTP Request Defaults by: Add > Config Element > HTTP Request Defaults.
The key field is Server Name (IP).

Add Cookie Support by: Add > Config Element > HTTP Cookie Manager.

Add a Timer by: Add > Timer > if you want a specific delay versus the default (that does not pause).

Add Tests Manually by: Add > Sampler > HTTP Request (See Recording a Test Script below to automate this). Leave Server Name blank to use from HTTP Request Defaults. Set Path to pages or to an API call, for example: /login, /stores, /terminals, etc. Set the Method: GET or POST.

Add Send Parameters as needed, including hidden required fields in some cases. Here is how to use the variables defined in User Defined Variables:

Add an Extractor by: Add > Post Processor > Regular Expression Extractor to get the CSRF (Cross Site Request Forgery) Token to be used with login. Select where the field is: Body, Headers, Response. Set a Reference Name that can be used later as a variable. Set the Regular Expression and Template.

Add various Graphs and Reports by: Add > Listener >
Some good options are: Graph Results, View Results Tree, Summary Report, Response Time Graph.

Recording a Test Script

Official Documentation - JMeter Proxy Step By Step

To record and build your test script using a web browser, there are some additional steps to what is listed above. Add a recording controller: Add > Logic Controller > Recording Controller and give it a name.

Select "Workbench." Right-click on WorkBench and add the recorder: Add > Non-Test Elements > HTTP(S) Test Script Recorder. Set the Global port to the port number you will record on, for example 8888. Set the Target Controller to the recorder added above.

-On HTTP(S) Test Script Recorder, click the "Add" button in "URL Patterns to Include". This will create a blank entry; enter .*.html, or whatever you want to include. Same with exclude if you want to ignore images, CSS, etc. or you can Add suggested Excludes. When you are ready, click the "Start" button at the bottom.

Next, you will configure your Firefox Browser to use the JMeter proxy, in this case, 8888. See the "Configure your browser to use the JMeter Proxy" section in the pdf for detailed instructions.

Record your navigation, which saves everything to the Recording Controller. Now you can review the saved requests, add any extractors for variables, and modify as needed.

When done, you will need to set your Browser proxy back to "Use system proxy settings," or whatever it was before.

Recorders and changes to the Workbench do not get saved with the Test Plan. You may want to save a separate workbench JMX file that can be merged with your test plan when needed by: right-clicking the "Script Recorder" and select "Save Selection As..."

How to Run JMeter in GUI Mode on Windows

Official Documentation - Running JMeter

To run JMeter for initial setup, testing your plan, and debugging, run the jmeter.bat (for Windows) or jmeter (for Unix) file. These files are found in the bin directory. Here are the options:

GUI Mode (for generating tests, debugging, and simple load testing)

• jmeter.bat - run JMeter (in GUI mode by default)
• jmeterw.cmd - run JMeter without the windows shell console (in GUI mode by default)
• jmeter-t.cmd - drop a JMX file on this to load it in GUI mode

Non-GUI mode (for Load Testing)

• jmeter -n.cmd - drop a JMX file on this to run a non-GUI test
• jmeter -n -r.cmd - drop a JMX file on this to run a non-GUI test remotely
• jmeter-server.bat - start JMeter in server mode
• mirror-server.cmd - runs the JMeter Mirror Server in non-GUI mode
• shutdown.cmd - Run the Shutdown client to stop a non-GUI instance gracefully
• stoptest.cmd - Run the Shutdown client to stop a non-GUI instance abruptly

Examples:

jmeter -n -t  -l

jmeter -n -t ..testsgrokola-com-basic.jmx -l ..resultsgrokola-com-basic-results.csv

jmeter -n -t ..testsgrokola-com-basic.jmx -l ..resultsgrokola-com-basic-results-20171201.csv

You can also add a date to the filename on the command line. To do this, add: %date:~-4,4%%date:~-7,2%%date:~-10,2%.

This will add the date in YYYYMMDD format. For example: grokola-com-basic-results-%date:~-4,4%%date:~-7,2%%date:~-10,2%.csv would turn into grokola-com-basic-results-20171201.csv. This may vary depending on the OS that you are using.

How to Run JMeter in Non-GUI Mode on Linux

A JRE or JDK is required to run JMeter. You can check to see what version of Java is installed by running java -version on the command line.

cd </path/to/dir>/apache-jmeter/bin/
./jmeter -n -t ../tests/grokola-com-basic.jmx -l ../results/grokola-com-basic-results.csv

Command Line Options

Official Documentation - 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 CSV or JTL file to log sample results to] (CSV is preferred).
• -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 a load test. The folder must not exist or be empty.

JMX File Variables

A JMX file is an XML file where the test is stored. Here are some important variables within a JMX that can be changed to vary tests:

• < stringProp name="ThreadGroup.num_threads">5< /stringProp > - Number of Users simulated in the test.
• < stringProp name="ThreadGroup.ramp_time">60< /stringProp>- Number of seconds to start all the users. For example, if you 60 users and the ramp time is 60 seconds, it will add 1 user per minute to the test.
• < stringProp name="LoopController.loops">10 stringProp> - Number of iterations each user will run in the test

The section below contains User Defined Variables that can be changed as needed:

<Arguments guiclass="ArgumentsPanel" testclass="Arguments" testname="User Defined Variables - beta.grokola.com" enabled="true">
<collectionProp name="Arguments.arguments">
<elementProp name="USERNAME" elementType="Argument">
<stringProp name="Argument.name">USERNAME</stringProp>
<stringProp name="Argument.value">testme123@keyholesoftare.com</stringProp>
<stringProp name="Argument.metadata">=</stringProp>
</elementProp>
<elementProp name="PASSWORD" elementType="Argument">
<stringProp name="Argument.name">PASSWORD</stringProp>
<stringProp name="Argument.value">mYp@$$w0rd12#</stringProp>
<stringProp name="Argument.metadata">=</stringProp>
</elementProp>
</collectionProp>
</Arguments>

< stringProp name="ConstantTimer.delay">5000 stringProp> - Number milliseconds between each user request (5000 would be 5 seconds).

Generating an HTML Reporting Dashboard

JMeter supports dashboard report generation to get graphs and statistics from a test plan. Go to http://jmeter.apache.org/usermanual/generating-dashboard.html for a detailed overview and configuration settings.

NOTE: the folder that you create the dashboard report in must be empty. You will need to delete the contents of this folder.

To create an HTML dashboard report from an existing CSV output file, run the following on command line:

jmeter -g <path to log results(csv)> -o <Path to output folder>
jmeter -g ..\results\grokola-com-basic-results.csv -o ..\reports\grokola-com-basic-20171201

To create a dashboard report at the end of a load test, add the -e and -o options on the command line:

jmeter -n -t <path to testplan(jmx)> -l <path to log results(csv)> -e -o <Path to output folder>
jmeter -n -t ..\tests\grokola-com-basic.jmx -o ..\reports\grokola-com-basic-20171201

Final Thoughts

I hope that you have found this JMeter introduction helpful! Please let me know if you have any questions.