Session/Cookie Management in Apache JMeter

1. Introduction

In this tutorial, we’ll learn how JMeter manages sessions and cookies, set up a test plan that logs in to an application, accesses protected resources, and logs out. Along the way, we’ll use HTTP Cookie Manager, CSV Data Set Config, and response assertions to ensure our tests simulate real-world user behavior.

2. Session Management in Web Applications

In web applications, session and cookie management come in many forms and are critical in authentication and user experience.

Let’s consider an application using form login. This type of authentication allows us to send a single authentication request that returns a cookie with the JSESSIONID when successful, which we can include in future requests. This eliminates the need to include credentials in every request.

2.1. How JMeter Handles Sessions and Cookies

Unlike browsers, JMeter requires explicit configuration to maintain state across requests. The specific components we’ll need are the HTTP Cookie Manager and the HTTP Header Manager.

3. Configure the JMeter Test Plan

We’ll use these components to create a test plan to log in to an application, access a protected resource, and log out.

In the end, we’ll have this structure:

3.1. Create a Thread Group

To start, we’ll need a Thread Group, which controls how many users and iterations we’ll use in our test.

Let’s right-click on Test Plan, then Add > Threads (Users) > Thread Group and modify a few properties:

• Stop Thread: Since we need to log in to access the application, we also want the test to stop on the first error. This option helps generate fewer requests if the login fails for any reason.
• Number of Threads: 3. This parameter helps test whether the application handles more than a couple of sessions simultaneously. Since we need valid credentials for each user, we can’t exceed the number of users in our database, which we’ll configure later.
• Loop Count: 2. Using any number greater than one helps verify that our application handles returning users
• Same user on each iteration: This option controls whether each user maintains its identity across multiple iterations of the test plan. If unchecked, cookies aren’t retained at the start of the next iteration. Since our plan starts with a login and ends with a logout, the value of this option isn’t relevant.

We can leave the other options with default values since they’re unrelated to session management.

3.2. Use a CSV File to Load Users

Since we’re running tests with multiple users, the most effective and secure way to load them is by including them in a CSV file.

Let’s create a file named users.csv and include three users, using the first line as the header:

username,password
alex_foo,password123
jane_bar,password213
john_baz,password321

Then, we’ll right-click our Thread Group, select Add > Config Element > CSV Data Set Config:

In this component, the only property we won’t leave with default values is Filename, which we’ll use to select our CSV file. Other notable options are:

• Variable Names: This overrides the default behavior of using the column names in the first line of the file as variable names. In conjunction with “Ignore first line“, this is useful if we want different variable names.
• Recycle on EOF: Each new thread picks the next line in the file. If this option is false, the values will return “EOF” for the next user, when the lines are exhausted. Otherwise, it loops back to the beginning of the file.

The variables defined here become usable almost anywhere we can input a value for the request and assertion elements we’ll use later.

3.3. Add an HTTP Cookie Manager

Finally, we’ll add another Config Element, and then choose the HTTP Cookie Manager. This component enables session management in JMeter:

• Clear cookies each iteration: This has the same effect as the “Same user on each iteration” option and is thus unavailable when we check the next option.
• Use Thread Group configuration to control cookie clearing: As the name suggests, this considers the “Same user on each iteration” we defined earlier.

4. Create the Login Request

Our first request is for the login form. Let’s right-click our Thread Group, then select Add > Sampler > HTTP Request:

Let’s check out the most relevant configuration bits for our scenario:

• Protocol: We only need to change it if our application uses HTTPS
• Server Name or IP: Should point to our server address
• Method: Our application uses the HTTP POST method for the login page
• Path: /login. This path is our login endpoint
• Follow Redirects: We should only check this when the login redirects to a page where we want to make test assertions. Otherwise, we should leave it unchecked to boost performance

Finally, Body Data is a query string where we define the user credentials. Since we’re using the CSV file component, we can reference the variables for the current cursor here. Also, we’re using the default parameter names for a Spring Security login form:

username=${username}&password=${password}

4.1. Include an HTTP Header Manager

We need to define the Content-Type header as application/x-www-form-urlencoded for our login request. To do this, we’ll right-click our login request, then select Add > Config Element > HTTP Header Manager and include it as a name/value pair:

If we don’t include it, our login will fail, as the server won’t know how to handle the request.

4.2. Assert Request Redirected After Login

When a login request is successful, it returns a 302 code, redirecting to the landing page in the application. To assert this, we can right-click our login request, then select Add > Assertions > Response Assertion:

Here, we’re using a combination of the “Response Code” and “Equals” options, inputting the 302 code in the “Patterns to Test” field. We’ll leave other options with default values.

4.3. Assert There’s No Login Error

If login fails, the response contains a Location header pointing to the error page. Let’s add another Response Assertion:

• Response Headers: This defines that we want to check the value in one of the response headers. We don’t need to set the header name.
• Contains + Not: The header value shouldn’t contain the string specified in the Patterns to Test field.
• Patterns to Test: The Location header contains the word “error” and is matched here.
• Custom failure message: We can also reference the current username variable here, generating a more descriptive JMeter error message.

5. Accessing Protected Resources

With the cookie manager in place, all subsequent requests automatically include session cookies, granting access to protected resources:

Then, we’ll check if the response matches the expected value. In our case, the secured endpoint Path we specified returns the currently logged-in user’s name. We’ll leave other options with default values.

So, let’s include the username variable in a new Response Assertion, in the Patterns to Test field:

• Text Response: We’ll check the response as plain text
• Matches: We want an exact match

6. Create the Logout Request

At the end of the iteration, we’ll add a logout request pointing to the logout endpoint:

And an assertion to check that we logged out successfully, using a similar logic to the login assertion, where we check if one of the headers contains “logout“:

Now we have a complete test cycle of authenticated users interacting with the application concurrently.

7. Explore the Requests

To visualize what’s happening under the hood, we’ll right-click our Thread Group, then Add > Listener > View Results Tree. After running our tests and inspecting a login request, we can see the JSESSIONID when clicking Response data > Response headers:

We can also see that the cookie is sent back in our request to a protected resource when clicking Request > Request Body:

Lastly, we can verify the expected response under Response Data > Response Body:

8. Conclusion

In this article, we explored how JMeter handles session and cookie management, enabling us to simulate real-world authentication scenarios. We configured a test plan that logs in, accesses protected resources, and logs out, ensuring our application correctly maintains and invalidates user sessions.