Credentials overview

This article will examine some common patterns for handling user credentials in your Gatling scripts. When creating performance or stress tests that simulate users logging into an application, it’s important to use multiple different credentials and user accounts.

We’re going to explore some common credentials patterns that might be relevant to the application that you’re testing, and discuss strategies you might adopt for handling those patterns in your Gatling scripts. Let’s get started!

Different Types of HTTP Authentication

There are multiple different mechanisms of HTTP authentication that could be present in any web application. You can read more about the different mechanisms and how they work in this article on HTTP Authentication.

Two of the most common methods to authenticate with a server are:

  • Username and password
  • Token-based authentication (e.g. OAuth)

In this article, we’ll focus on common patterns for handling credentials in our Gatling script that are relevant to the above two methods of authentication.


Common patterns to authenticate virtual users

Common Patterns to Authenticate Virtual Users

The credentials pattern you’ll need to follow for your application when writing Gatling test scripts will likely fall under one of the following scenarios:



Login/Password with Free Registration

In this scenario your web application provides access to a resource or endpoint whereby you can create new users by simply submitting a HTTP POST request to the server to register with a desired login and password. After you submit the request, the new user is immediately created and can log into the application immediately.

A common pattern to handle credentials in your Gatling script in this scenario would be to randomly generate a login and password that gets submitted in the HTTP request to register the user. To learn more about how to randomly generate data that can be used as credentials in a Gatling script, refer to the Gatling Feeder documentation.

Note that when executing performance tests that can easily register new users, it’s highly desirable to have the ability to clear down the database of created users between test executions. This will prevent the database from becoming overwhelmed with existing user accounts.


Verification link

Login/Password with Verification Link

In this pattern, after the user submits a HTTP request to register with their username and password, they’re emailed a verification link that needs to be accessed to login.

How you handle this in your Gatling script will depend on the setup of your application, and whether you can capture the verification link from the browser. If you have the means to access the link on a webpage or through a HTTP call, then you can use a Gatling check to capture and save the link as a parameter. You can then use this parameter in a subsequent HTTP call to access the link and complete the registration or login process.

Refer to the Gatling check and saveAs documentation for details on how to capture and save text or links returned from a HTTP request.

If you want to test the generation of emailed verification links in a test environment, you might want to try the tool MailHog. Refer to this guide for setting up and configuring MailHog for testing in your environment.

Already Registered Users by Login/Password

If you want to test multiple different users logging into your application and you already have a list of login/password credentials, the best way to handle this pattern is typically using a pre-existing test data file and a Gatling feeder.

You can put a list of logins and passwords into a CSV file, then create a Gatling CSV Feeder  to read an entry from the file each time you execute a user login transaction. 

There are several different feeder strategies that you can adopt for using the credentials in your test data file, such as:

  • Random – select a random login/password entry from the test data
  • Queue – select entries from the file in order
  • Shuffle – shuffle the entries first, then behave like  queue
  • Circular – select entries in order, then go back to the start once the end is reached

When using the Queue or Shuffle strategies, make sure you have enough test data in your file. If the feeder runs out of entries, then the Gatling test will shut down.

Once the user has completed the login transaction, the system will often return a sessionId in the form of a cookie.That sessionId may need to be passed in all subsequent requests (typically in a HTTP header) that the virtual user makes.

With Gatling, you can use a check and saveAs() to capture this sessionId into a parameter, then send that parameter back in subsequent HTTP calls in the header or by whatever means the application expects.



Common OAuth Patterns

OAuth is an open-standard authorisation protocol that apps can use to provide client applications with secure delegated access. OAuth works over HTTPS and authorises devices, APIs, servers, and applications with access tokens rather than credentials. You can learn more in this article on OAuth.

If your web application is using OAuth, there are two different scenarios that you’ll likely want to cater for in your Gatling script:

  1. Get the OAuth access token (or refresh existing access tokens)
  2. Use the OAuth access token in requests

Depending on your use case and the scenario you want to test, you might find it appropriate to create and execute a separate Gatling script that creates multiple access tokens up front. If required you could also write these tokens to a file, and then use the tokens in that file as parameters for test data with a Gatling feeder to authenticate as different users

Alternatively, you might want to have the creation of the OAuth token and subsequent use of that OAuth token (i.e. to complete other regular transactions), as part of the same script. It ultimately depends on your individual use case, and the behaviour you want to test and simulate.

Refer to this article for an example of generating OAuth access tokens with Gatling and then using the tokens in subsequent HTTP requests.



In this article we’ve explored a few of the common credentials patterns you might encounter in web applications and seen how to handle those in our Gatling scripts.

To learn more about Gatling, we have comprehensive quickstart and advanced tutorials in the Gatling Documentation.

For a more interactive approach to learning, the Gatling Academy has a series of video courses that will guide you in writing Gatling load testing scripts against different types of applications.

Related resources

You might also be interested in…