Gatling installation

Learn how to install Gatling for Java, Kotlin, Scala, JavaScript, or TypeScript. Install Gatling with the Maven, sbt, or Gradle build tool or a JavaScript package manager.

Introduction#

Gatling runs on a Java Virtual Machine (JVM). You can write tests in Java, Scala, Kotlin, JavaScript, or TypeScript. We strongly recommend downloading the project ZIP file from this page and following the subsequent installation instructions for all languages.

The installation requirements and procedures for JavaScript and TypeScript differ from the native JVM languages. To use Gatling with JavaScript or TypeScript, skip to the Use a JavaScript package manager section.

Gatling also provides a standalone bundled version that is intended for users behind a corporate firewall who might have restricted access to Maven (for example).

Prerequisites for Java, Scala, and Kotlin#

Java version#

Gatling supports 64-bit OpenJDK LTS (Long Term Support) versions: 11, 17, and 21. Other JVMs such as, 32-bit systems or OpenJ9, are not supported. We recommend the Azul JDK.

Supported languages#

Since 3.7, Gatling supports writing tests in Java, Scala, and Kotlin. Older Gatling versions only support Scala.

Gatling version#

In particular, don’t use milestones (M versions) you could find on Maven Central; those are not documented and are released only for internal use or Gatling Enterprise customers.

Install Gatling using a ZIP file for build tools#

Build tools are the preferred way for Gatling users to launch and run their scripts. From Gatling 3.11, the build tool plugins have similar functionality and commands while respecting each tool’s conventions. Additionally, the Maven and Gradle tools have wrappers that allow you to run Gatling without installing Maven or Gradle on your computer. The following download buttons provide links for Maven-Java and Gradle-Java projects. Installation instructions for Kotlin and Scala are located in the Maven, Gradle, and sbt plugin documentation.

If you are unsure which version to select, Java-Maven is recommended.

To install Gatling:

1. Download your preferred configuration.
2. Unzip the folder.
3. Open the folder in your IDE.

Download Gatling for Maven-Java

Download Gatling for Gradle-Java

Manually install and configure Gatling with a build tool#

You can install and configure Gatling manually by following instructions in the build tool plugin documentation:

• Maven
• Gradle
• sbt

Use a JavaScript package manager#

To install Gatling for JavaScript and TypeScript, you must have:

• Node.js v18 or later (LTS versions only)
• npm v8 or later (included in the NodeJS installation)

Then, use the following procedure to install Gatling:

1. Download the Gatling JS demo project zip file using the following download button:

   Download Gatling for JavaScript

2. Unzip and open the project in your IDE or terminal.

3. navigate to the /javascript folder for JavaScript projects or the /typescript folder for TypeScript projects in your terminal.

4. Run npm install to install the packages and dependencies.

You can run the pre-configured demo simulation from the src/ folder with the following command:

npx gatling run --simulation computerdatabase

npx gatling run --typescript --simulation computerdatabase

Use the standalone bundle#

The Gatling bundle is primarily intended for users who don’t have internet access (e.g., behind a corporate firewall). Otherwise, we strongly recommend using the Maven plugin, which is lighter and easier to push to Git. Pay attention to the subsequent warnings to understand the limitations of the standalone bundle.

From Gatling 3.11, the bundle is based on a Maven wrapper, and we recommend using it with an IDE such as IntelliJ.

Download for Gatling bundle

For all details regarding the installation and the tuning of the operating system (OS), please refer to the operations section.

The bundle structure is as follows:

• src/test/java: where to place your Simulations code. You must respect the package folder hierarchy.
• src/test/resources: non source code files such as feeder files and templates for request bodies and configuration files for Gatling, Akka and Logback.
• pom.xml: Maven informations about the project.
• target: where test results are generated.

Use Gatling with an IDE#

You can edit your Simulation classes with any text editor, maybe with some syntactic coloration for your chosen language. But if you are a developer, you’ll most likely want to use your favorite IDE with Gatling.

IntelliJ IDEA#

IntelliJ IDEA Community Edition comes with Java, Kotlin, maven and gradle support enabled by default.

If you want to use Scala and possibly sbt, you’ll have to install the Scala plugin, which is available in the Community Edition. You’ll most likely have to increase the stack size for the Scala compiler so you don’t suffer from StackOverflowErrors. We recommend setting Xss to 100M.

VS Code#

We recommend that you have a look at the official documentation for setting up VS Code:

• with Java
• with Kotlin
• with Scala

Run a demo load test#

If you installed Gatling using a ZIP file download it comes pre-loaded with a fully functioning load test. You can run this test locally to instantly experience Gatling’s functionality and reports feature. The following sections help you to run your first test. The provided commands work for Maven, JavaScript/TypeScript, and the bundle. Refer to the plugin documentation for Gradle or sbt users.

Run a Gatling simulation#

Use the following command to start Gatling in interactive mode:

./mvnw gatling:test

mvnw.cmd gatling:test

Start the Gatling Recorder#

The Gatling Recorder allows you to capture browser-based actions and convert them into a script. Use the following command to launch the Recorder:

./mvnw gatling:recorder

mvnw.cmd gatling:recorder

For the JavaScript SDK:

npx gatling recorder

Edit this page on GitHub