Gatling Maven Plugin – Everything you need to know

Recently, while working with the Gatling Maven Plugin, I was in search of documentation to understand the possible configurations available in Gatling Maven plugin. To my surprise, I could not find anything official on Gatling’s website.

Therefore, I decided to compile this information in this post.

In this blog I will be focusing on different parameters available for configuration in Gatling Maven Plugin.

Gatling Maven Plugin – Introduction

Gatling is a powerful tool for performance testing, with Gatling Maven plugin, users can leverage Maven commands to execute Gatling tests and generate HTML reports. This integration allows users to plug in Gatling tests in CI/CD pipelines as this brings support for command line execution of Gatling simulation files.

How to use this plugin

If you are setting up Gatling Java code for the very first time and are unsure how to integrate Gatling-related tasks into Maven lifecycle, you need to add the following piece of code in your pom.xml.

<build>
    <plugins>
        <plugin>
            <groupId>io.gatling</groupId>
            <artifactId>gatling-maven-plugin</artifactId>
            <version>${gatling.maven-plugin-version}</version>
        </plugin>
    </plugins>
</build>

Version availability for Gatling Maven Plugin

In order to know the latest version available for Maven Plugin, you can browse Maven Central Repo.

Gatling Maven Plugin Configurations

Once the plugin is successfully installed in your IDE, you can verify the installation, as shown in the screenshot below. In the Maven window of your IntelliJ, you should see the gatling option present in the plugins section.

You should be able to run gatling:help task to see help documentation available. Or, you can run below command to know the test related configurations available in this plugin.

mvn gatling:help -Ddetail=true -Dgoal=test

Parameters in Gatling Maven Plugin

1. configFolder

• Description: Use this folder as the configuration directory.
• Default: ${project.basedir}/src/test/resources
• User Property: gatling.configFolder

2. continueOnAssertionFailure

• Description: Continue execution of simulations despite assertion failure. Useful for collecting results from all simulations, even if some assertions fail in previous ones.
• Default: false
• User Property: gatling.continueOnAssertionFailure

3. excludes

• Description: List of exclude patterns to use for scanning. Excludes none by default.
• User Property: gatling.excludes

4. failOnError

• Description: If set to true, the project build will look successful even in the presence of Gatling test failures. Useful for continuous integration where collecting output files is crucial.
• Default: true
• User Property: gatling.failOnError

5. includes

• Description: List of include patterns to use for scanning. Includes all simulations by default.
• User Property: gatling.includes

6. jvmArgs

• Description: Extra JVM arguments to pass when running Gatling.
• User Property: gatling.jvmArgs

7. noReports

• Description: Run simulation but does not generate reports.
• Default: false
• User Property: gatling.noReports

8. overrideJvmArgs

• Description: Override Gatling’s default JVM args, instead of replacing them.
• Default: false
• User Property: gatling.overrideJvmArgs

9. propagateSystemProperties

• Description: Propagate System properties to forked processes.
• Default: true
• User Property: gatling.propagateSystemProperties

10. reportsOnly

• Description: Generate the reports for the simulation in this folder.
• User Property: gatling.reportsOnly

11. resourcesFolder

• Description: Use this folder as the folder where feeders are stored.
• Default: ${project.basedir}/src/test/resources
• User Property: gatling.resourcesFolder

12. resultsFolder

• Description: Use this folder as the folder where results are stored.
• Default: ${project.build.directory}/gatling
• User Property: gatling.resultsFolder

13. runDescription

• Description: A short description of the run to include in the report.
• User Property: gatling.runDescription

14. runMultipleSimulations

• Description: Iterate over multiple simulations if more than one simulation file is found. If set to false and multiple simulations are found, the execution will fail.
• Default: false
• User Property: gatling.runMultipleSimulations

15. simulationClass

• Description: The name of a Simulation class to run.
• User Property: gatling.simulationClass

16. skip

• Description: Disable the plugin.
• Default: false
• User Property: gatling.skip

17. useOldJenkinsJUnitSupport

• Description: Use old Jenkins JUnit support.
• Default: false
• User Property: gatling.useOldJenkinsJUnitSupport

18. workingDirectory

• Description: Specify a different working directory.
• User Property: gatling.workingDirectory

Example

<build>
    <plugins>
        <plugin>
            <groupId>io.gatling</groupId>
            <artifactId>gatling-maven-plugin</artifactId>
            <version>4.8.2</version>
            <executions>
                <execution>
                    <phase>test</phase>
                    <goals>
                        <goal>test</goal>
                    </goals>
                    <configuration>
                        <simulationClass>com.example.MySimulation</simulationClass>
                        <configFolder>${project.basedir}/src/test/resources</configFolder>
                        <resultsFolder>${project.build.directory}/gatling-results</resultsFolder>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

To receive insightful articles directly in your inbox, subscribe to our newsletter.

Thank you for reading this post, don't forget to subscribe!