A Beginner’s Guide to Performance Testing With Gatling
Gatling, Maven, and IntelliJ are all keywords we’ve seen on LinkedIn and various job descriptions and there are good tutorials out there which outline the prerequisites and how to install Gatling. I thought I would document what I have learned from online resources during my investigation into performance testing.
In this post, I will go through the steps required to set up a performance test suite using the tools Gatling, Apache Maven, and IntelliJ+Scala Plugin, along with how to install the required software.
A bit about my system setup - OS: Windows 10, system type: x64, RAM: 16GB.
STEP 1: Install Java 8 JDK
Why: because Gatling uses JAVA to run.
Download the Java 8 JDK (64 bit) package from Oracle and run the program to kick off the installation process. Take note of where your JDK is being installed as we will need this later (usually C:\Program Files\ Java).
Once completed edit your environment variables by: Start > type in environment variables > click ‘Edit the system environment variables’
Here you will need to add JAVA_HOME and add java bin to the PATH variable.
Click new to add variable name as JAVA_HOME and variable value as the path where you installed Java (for me it was C:\Program Files\Java\jdk1.8.0_261).
Find PATH in the list of system variables and edit PATH via Path > Edit. Add a new environment variable to path which directs to your Java bin folder (mine was C:\Program Files\Java\jdk1.8.0_261\bin).
You can verify Java was installed properly by opening cmd terminal and entering java -version . If it is installed incorrectly you will get an error.
STEP 2: Install Apache Maven
Why: because we need a build tool to compile our simulations and Maven has an official Gatling plugin for this.
Download the Maven binary zip file from: https://maven.apache.org/download.cgi.
Unzip this file in your C:\ drive or another suitable location.
Do our favourite thing and set the environment variables for MAVEN_HOME and the Maven bin path in PATH using the same procedure as the JAVA step.
You can verify Maven has been installed correctly by opening cmd terminal and entering: mvn -v.
STEP 3: Install Gatling
Download the Gatling community version from https://gatling.io/open-source/.
Unzip the file to C drive, this matters greatly when using windows as if it is unzipped to program files there tends to be permission and path issues (warning from Gatling themselves https://gatling.io/docs/current/installation/).
Once unzipped, edit the environment variables one last and final time to add GATLING_HOME and PATH.
STEP 4: Install IntelliJ with Scala Plugin
Why: IntelliJ is an IDE that can be used to view a Gatling project, it has an in built terminal where for test execution.
Download IntelliJ Community and follow the setup process: https://www.jetbrains.com/idea/download/#section=windows.
When IntelliJ is first opened after install, the user is prompted to set display settings and given the opportunity to disable default plugins. After this the user is prompted to install any featured plugins, from the list choose to install Scala as this will be the language used to write Gatling tests.
IntelliJ Community is then ready for use.
STEP 5: Create a performance test project
Create a base project using maven gatling archetype. This will download the gatling dependencies required and create a project template. Using cmd terminal navigate to the folder you would like your project to be created in and use the following command.
mvn archetype:generate -DarchetypeGroupId=io.gatling.highcharts -DarchetypeArtifactId=gatling-highcharts-maven-archetypeFollowing this you will be asked to define group id, artifact id, version, these variables will allow you to set your project name, source folder name, and version. This will create a project folder which you can open in IntelliJ. In my example I set group id as postcodes-performance-tests, artifact id as test, and left the version blank.
The src folder that is created should be set to sources root so IntelliJ knows to compile this code.
The src folder is spilt into two directories, resources and scala. Resources will contain your request bodies (in bodies folder) and any test data you may need (in data folder). There is also a Gatling.conf file, it is possible to edit Gatling.conf to customise your settings, but leaving it commented out means we will use the gatling-defaults.conf which is not editable. The scala folder is where the simulation information will be stored, you can set this up in a way that is suitable for you but I found it useful to follow this tutorial for a concise framework setup: https://devqa.io/gatling-maven-performance-test-framework/.
POM.xml will be used to set up your compile configuration.
STEP 6: Writing the first test
For this tutorial I will be using the open source Postcodes API: https://postcodes.io/ and get postcodes as my test endpoint: api.postcodes.io/postcodes which uses a post method.
First step is to create the test request, for this I created a JSON file within my test/resources/bodies directory.
Next, we need to set up our config, requests, test scenarios, and simulations.
Config: within the test/scala/config folder create a Configuration scala class here you can set the base URL and the variables for users and ramp up (default to 1 but can be specified during execution using the users or ramp up flag) for your tests. You can also include other configuration parameters such as throughput.
Requests: Within the test/scala/requests folder create individual request Scala classes for your endpoints under test, for example here I used the GetPostcodes endpoint and I set the application type, request body type and I specified where the JSON request is kept within my project. I also verify that a 200 response is return to ensure the happy path is tested. These requests will be called upon within our scenario classes.
Scenarios: Within the test/scala/scenarios folder create individual scenario Scala classes for your endpoints under test, for example here I set the scenario for the GetPostcodes endpoint and I executed the GetPostcodes request stored within test/scala/requests folder.
Simulations: Within the test/scala/simulations folder create individual simulation Scala scripts which is where you define your simulation parameters. In this case, I executed the scenario for GetPostcodes using the ramp up and users I have defined in my configuration file.
The final item to define is the POM.xml, here we will specify which simulations to run using the <configuration> tag.
STEP 7: Test execution
The tests can be run using the IntelliJ in built terminal or cmd line using the command: mvn clean gatling:test
The project will build and any simulations specified in POM.xml will be executed with the default settings with a report file output.
If the test was not successful due to build errors, you will get a build error failure with error messages — google group and stack overflow are good places to search for resolution to any errors you may encounter.
If the test was not successful due to test failure, a report will still be generated with failure reason.
If you would like to specify users or ramp up time use the flags -Dusers=<numberofusers> and -Drampup=<rampuptimeinsecs>.
mvn clean gatling:test -Dusers=100 -Drampup=10Hopefully, you have found this tutorial helpful. Please leave a comment if you have any questions or requests for follow up information. Also, please check out the following links which I found useful during my research.
Gatling docs: https://gatling.io/docs/current/quickstart/
Maven docs: https://maven.apache.org/guides/index.html
How to install Gatling on windows: https://www.blazemeter.com/blog/how-to-install-gatling-on-windows
How to set up a Gatling test framework: https://devqa.io/gatling-maven-performance-test-framework/
