Getting started with Gatling Enterprise
Learn how to run your first test from scratch
In this tutorial, we’ll describe every step to help you run your first test with Gatling Enterprise.
- A valid GitHub account
- A Java Development Kit (JDK) installed in version 8 or 11
- The Gatling bundle is beginner friendly and is the best choice if you’re just getting started.
- For long term projects, consider using a Gradle, Maven or SBT Gatling project. You can download some Gatling Enterprise ready sample projects from the Cloud dashboard directly!
Gatling is a code based load testing tool. It is based on the Scala programming language and is an Open-Source project that is free to use! Gatling is used to power Gatling Enterprise in order to make it a full-fledged load testing tool with even more features, such as live reports, advanced metrics and large scale clustered tests. The tests you code with Gatling are compatible with Gatling Enterprise without any changes.
Gatling requires a Java installation so make sure that you have a JDK 8 or 11 installed on your computer. Adoptium provides good packages that contain everything you need.
While there are a lot of ways to create your first test, if you are new to load testing or not a developer, we recommend using the Gatling bundle as it is beginner friendly. It is self sufficient and doesn’t require knowledge of the usual Java/Scala build tools, i.e. Gradle, Maven or SBT.
If you already have experience with these tools, they are the better options long-term as they will allow integrating Gatling into an already existing tool chain:
- Code editors, such as IntelliJ and Visual Studio Code
- Continuous integration tools, such as Jenkins
Step 1 - Sign up and log in
Gatling Enterprise handles users by putting them in organizations. This will allow you to work with multiple people on the same test projects, so they can either run new tests or view the results of previous ones.
A user can be part of either a team within an organization or have access to the organization as a whole. In all cases, a user must be part of an organization. Hence, once signed up and connected, you’ll need to create one:
If you are the first person in your organization to join Gatling, sign up and create an account. In this case, you will need to create an organization:
If you have been added to an organization by a System Administrator already.
Press “Continue with GitHub”, where you will be asked to authorize the application. The GitHub authorization page opens in a new tab. If no tab opens, make sure it is not being blocked by your browser.
One last thing, new organizations are given free credits to launch their first test.
Step 2 - Preparing the project
If you already know about Gatling and/or you are using a Gradle, Maven or SBT project, you’ll need to update the configuration to make it compatible with Gatling Enterprise first:
Or, you can download preconfigured sample projects from Gatling Enterprise by clicking on the “Sample simulations” button on the top right in the Simulations page.
Now, you can directly skip to the generate a package section.
Click here to download the latest version of the Gatling bundle and extract the archive.
Taken from the bundle structure documentation, we learn that the important parts of the bundle are as such:
bincontains launch scripts for Gatling and more, this is where you execute Gatling and package the tests for Gatling Enterprise, which we’ll see later on
user-files/simulationscontains your scala test files, this is where you describe what you want your virtual users to do, and what you want to do with them
resultscontains log files of each tests and reports generated in sub directories if launched with Gatling
Running the test locally
You can test your installation by running your test locally. If Java is properly installed, you can enter the following command in your terminal, or open the
gatling.sh (if Linux/MacOS) or
gatling.bat (if Windows) in any file explorer:
If working properly, you should see something like this:
GATLING_HOME is set to xxx/gatling-charts-highcharts-bundle-3.6.1 Choose a simulation number:  computerdatabase.BasicSimulation  computerdatabase.advanced.AdvancedSimulationStep01  computerdatabase.advanced.AdvancedSimulationStep02  computerdatabase.advanced.AdvancedSimulationStep03  computerdatabase.advanced.AdvancedSimulationStep04  computerdatabase.advanced.AdvancedSimulationStep05
So far we didn’t create any test of our own but the Gatling bundle provides some example for you to start with. Here, the bundle is prompting you to choose one of the sample tests so it can run it. You can, for example, type
0, after which the Gatling bundle will prompt you for an optional description of the test being run:
Select run description (optional)
Finally, if everything is properly setup, you’ll see that the test has started:
Simulation computerdatabase.BasicSimulation started...
By default, Gatling works in console mode, outputting where the test is that every 5 seconds. After Gatling is done, you should see something like this:
Simulation computerdatabase.BasicSimulation completed in 23 seconds Parsing log file(s)... Parsing log file(s) done Generating reports... ================================================================================ ---- Global Information -------------------------------------------------------- > request count 13 (OK=13 KO=0 ) > min response time 84 (OK=84 KO=- ) > max response time 168 (OK=168 KO=- ) > mean response time 93 (OK=93 KO=- ) > std deviation 22 (OK=22 KO=- ) > response time 50th percentile 87 (OK=87 KO=- ) > response time 75th percentile 87 (OK=87 KO=- ) > response time 95th percentile 121 (OK=121 KO=- ) > response time 99th percentile 159 (OK=159 KO=- ) > mean requests/sec 0.542 (OK=0.542 KO=- ) ---- Response Time Distribution ------------------------------------------------ > t < 800 ms 13 (100%) > 800 ms < t < 1200 ms 0 ( 0%) > t > 1200 ms 0 ( 0%) > failed 0 ( 0%) ================================================================================ Reports generated in 0s. Please open the following file: .../gatling-charts-highcharts-bundle-3.6.1/results/basicsimulation-20210826135452662/index.html
You can open the url at the end of the output, which will show a report of the test that was just run:
Step 3 - Generate a package
Gatling Enterprise requires a package built from a Gatling project in order to run a test.
To create a package, run the
artifact.bat (if Windows) or
artifact.sh (if Linux/MacOS) file, Gatling will start creating your first package:
$ ./bin/artifact.sh GATLING_HOME is set to .../gatling-charts-highcharts-bundle-3.6.1 GATLING_VERSION is set to '3.6.1' Creating jar...done
This script can also be clicked or double clicked from any file explorer. You’ll see the result in the folder
target, which should now have a file named
When using other tools, the command to type and the name of the package will differ:
mvn clean package -DskipTests
The name of the package being:
Step 4 - Upload the package
On Gatling Enterprise, click on the packages icon and on create. Give a name to your package, you can choose to make it available to all teams or to limit access to a specific one, then hit save.
Next, upload the package you generated earlier by clicking on the cloud icon. The package you generated earlier is located here:
Upload it to Gatling Enterprise, either by drag-and-dropping it to the modal, or by clicking on the modal to open the file manager.
When using other tools, the name of the package will differ:
Step 5 - Create a simulation
To get a grasp of how to run a simulation with Gatling, you will find a ready to use script in the bundle. So let’s get started with your first simulation!
In the Simulation section, click on “Add” if there are no other simulations or on “Create” if other simulations have already been created before.
Choose a name for your simulation and define the team that will have access to this simulation (if none has been created yet, just click on “Default”).
Under Class name, it is important you enter the name of the script that was uploaded in the package, otherwise the run of your simulation will fail in the next step. In this case, the ready-made script called
BasicSimulation.scala is located in the bundle: user-files > simulations > computer database. Therefore, you need to enter
computerdatabase.BasicSimulation as the class name. Once you’ve entered the script name click on the “Next” button.
Next, you’ll need to select your package name. It is important to select the package that contains the simulation you’d like to run. When you’ve selected your package, click on the “Next” button.
In the final step, you can choose where you want the injection to take place. Select a location, eg: “US East - N. Virginia (AWS)” and click on the “Save” button. The traffic in your simulation will be coming from the region you’ve selected. The three next steps are optional and you can learn more about them here, but for now, let’s just simply click “save”.
That’s it, you have created your first simulation on Gatling Enterprise!
Step 6 - Start load testing!
You are now ready to start load testing. To start the simulation you have just created, click on the Start icon. As soon as the simulation is running (“injecting” but not during the building and deploying statuses), you will be able to access the report, even while it is building.
Now that you know how to create and run a simulation on Gatling, we suggest you jump on to the tutorials Interface tour and get the most out of the reports.
Learn about load testing concepts
Load testing is hard but the test you write doesn’t need to be. In this article you’ll learn what matters the most when creating your first load testing campaign.
Make your own tests
If you’ve read the article cited in the previous section, you’ve learned you don’t need much to make a load testing that can provide meaningful results. At some point though, you might need to add complexity into the test, such as real user behavior, specific injection profiles, etc.. This is where learning how to craft tests will come handy. Good resources are:
- The Quickstart tutorial to learn about the Recorder and how to quickly bootstrap a complex scenario and go from there
- The Advanced tutorial for more advanced crafting
- For a exhaustive of all you can do with Gatling, the Cheat-Sheet is your best friend
- The Gatling Academy, where you can follow our own training program!
You have successfully started load testing, you can read our documentation if you need more information about our product:
- Gatling documentation
- Gatling Enterprise documentation
- Documentation about the creation of a package
- Documentation about how to use the reports