Java Reference Guide

Your First JMeter Test

Last updated Jul 14, 2006.

Start JMeter by launching the jmeter.bat file on Windows or jmeter file on Unix/Linux from the JMeter bin directory. This presents the screen shown in Figure 1: a JMeter project consists of a test plan and a workbench.

Figure 1. JMeter project screen

We'll start by creating a test plan and look at the workbench later. The first thing that you need to do is to add a Thread Group to your Test Plan by right-clicking on the Test Plan node and choosing "Add" and then "Thread Group." A Thread Group controls the behavior of your users as they are running your test scripts. Figure 2 shows the configuration of a Thread Group.

Figure 2. JMeter Thread Group Configuration Screen

The Thread Properties section of the Thread Group configuration page allows you to control the following user behaviors:

• Number of threads: this controls how many virtual users JMeter will use to execute your test scripts
• Ramp-up Period: the controls how quickly JMeter will ramp up from zero users to the number of users defined. The ramp-up time is defined in seconds, so if you define 60 users and a 60 second ramp-up time then JMeter will add one user per second
• Loop Count: this controls how many times each user will execute the test script; choose the "forever" checkbox to cause the scripts to run indefinitely, or until manually stopped
• Scheduler: if you select this checkbox then choose the start and end time (and day) of the test

For this test let's configure 5 users with a 10 second ramp-up period (one user added every 2 seconds) and execute the test 5 times (loop count).

Before defining an HTTP request, it is always a good idea to define a set of default arguments, the reason being that you can configure the server you are testing in one place and then quickly switch between environments. For example, you can build the test on your own development machine and then change the script to point to your QA machine in one place rather than having to rebuild all of the test scenarios by hand. You can add an "HTTP Request Defaults" by right-clicking on the "Test Plan" node and choosing "Add," "Config Element," and then "HTTP Request Defaults." The HTTP Request Defaults page is shown in Figure 3.

Figure 3. JMeter HTTP Request Defaults page

In this case I have configured all of my requests to execute against my local machine (localhost) on port 8080 (this is the default Tomcat and JBoss listening port, which you can change for your application server if you are using something else.) Later if we change the server name and/or port here, all subsequent requests will be executed against a different server.

Now we need to add an HTTP request sampler to our project, as that represents a request that you will make to your application. Right-click on your Test Plan and choose "Add," "Sampler," and then "HTTP Request." The HTTP Request samples page is shown in Figure 4.

Figure 4. JMeter HTTP Request sampler page

In this scenario I defined the test to perform an HTTP GET on the path "/stats/stats," which is a monitoring servlet that I have written to run in JBoss. I renamed the HTTP Request to "Stats Request" because in the future I will add additional requests and it would be nice to be able to differentiate between them. Beyond simply playing the load against our application, we want to ensure that it is actually responding correctly. For the purposes of this test, let's just test the response code to be sure that we are receiving an HTTP response code 200. Right-click on the "Stats Request" node (or whatever you named your node) and choose "Add," "Assertions," and then "Response Assertion." Figure 5 shows the Response Assertion page.

Figure 5. JMeter Response Assertion page

I changed the name of the response assertion to "Response Code 200" because we would probably want to add more detailed assertions later. From the "Response Field to Test" choose "Response Code," and then from the "Pattern Matching Results" choose "Matches." Add a new pattern to test and type "200." When a request is executed, if its response code is not "200," it will be logged as an error. To view detailed results of the assertion, you can add an assertion results listener to the request by right-clicking on the "Stats Request" and choosing "Add," "Listener," and then "Assertion Results." You will find that with everything in JMeter, the position of where you add elements determines its scope. For example, if you add an Assertion Results listener to the Thread Group then you will see the results of all requests that have assertions defined, but if you add it to an individual request then it will only see the assertion results for that request. Figure 6 shows the Assertion Results page, which is not very interesting until we run our test, but the configuration option that I usually enable is the "Log Errors Only" checkbox. Otherwise it will fill up with successful messages.

Figure 6. JMeter Assertion Results page

Finally, we need some way of visualizing the results of our tests. There are two primary visualizations that I add to a project:

1. Graph Results
2. Summary Report

The Graph Results displays a graph of the response time and throughput of the tests. The summary report displays a table of the results in an easy to read format. You can add these to your test plan by right-clicking on the Thread Group and choosing "Add," "Listener," and then "Graph Results" and "Summary Report."

Let's run the test and then look at the results. Choose "Start" from the "Run" menu to start the test. Figure 7 shows the summary report my sample run.

Figure 7. JMeter Sample Report page

In this test the "Stats Request" was executed 25 times, averaging 44ms per request with a minimum response time of 15ms and a maximum response time of 78ms. There were not any errors (as defined by failed assertions), and my throughput was 3 requests per second. The graph results in not very interesting for such a small test, so I changed my Thread Group properties to create 50 users and repeat the test 20 times, which gives us 1000 requests. The results of this test are shown in Figure 8.

Figure 8. JMeter Graph Results page

During this test, the average response time as a little under 6 seconds (5848ms) with a median result of 2875ms. The deviation however, was greater than the average (6942ms), meaning that some users received dramatically greater response times than others. The throughput for our test was about 90 requests per minute, or about 1.5 requests per second. The observed behavior of the request was that it took a little while to stabilize and then started to become more predictable.

If you want to run more tests and want to start with new graphs and report summaries, you can choose "Clear" or "Clear All" from the "Run" menu before restarting.

Summary

Thus far in this series we reviewed the background and motivation behind load testing and then briefly surveyed the market to see who the major players are with load testing software. Because of its zero cost, prevalence in the market, and high degree of functionality, this series will standardize on Apache JMeter as the load tester of choice.

We downloaded and installed JMeter and then built our first test plan by hand. We added a single request and configured an assertion to test the response code of that request. Finally we added a graph and summary report of the results.

Next week we will configure an HTTP proxy to record our actions as we perform them, so tune back in.