Create your first JavaScript-based simulation

Learn how to get started with Gatling and create a Gatling simulation with JavaScript.

Gatling is a highly flexible load-testing platform. You can write load tests in Java, Kotlin, Scala, JavaScript, and TypeScript, or use our no-code feature with Gatling Enterprise.

In this guide, we cover a “Hello world”-style example for JavaScript of how to:

• install and setup your local dev environment,
• write your first simulation,
• Package and upload your simulation to Gatling Enterprise,
• Create and run a new test on Gatling Enterprise
• test your simulation locally.

Setup#

This section guides you through installation and setting up your developer environment. This guide uses JavaScript and the gatling demo project. The JavaScript SDK is currently available for the HTTP protocol only.

Sign up for Gatling Enterprise#

Gatling Enterprise is a fully managed SaaS solution for load testing. Sign up for a trial account to run your first test on Gatling Enterprise. The Gatling website has a full list of Enterprise features.

Clone Gatling demo repository#

Then, use the following procedure to install Gatling:

1. Clone the following repository.

2. Open the project in your IDE or terminal.

3. Navigate to the /javascript folder.

4. Run npm install to install the packages and dependencies including the gatling command.

Simulation construction#

This guide introduces the basic Gatling HTTP features. Gatling provides a cloud-hosted web application https://ecomm.gatling.io for running sample simulations. You’ll learn how to construct simulations using the JavaScript SDK.

Learn the simulation components#

A Gatling simulation consists of the following:

• Importing Gatling functions.
• Configuring the protocol (commonly HTTP).
• Describing a scenario.
• Setting up the injection profile (virtual users profile).

The following procedure teaches you to develop the simulation from each constituent component. If you want to skip ahead and copy the final simulation, jump to Test execution. Learn more about simulations in the Documentation.

Set up the file#

To set up the test file use the following procedure:

1. Navigate to and open javascript/src/basicSimulation.gatling.js.
2. Modify the simulation by deleting everything below line 2 import { http } from "@gatling.io/http";.
3. The simulation should now look like the following:

import { simulation, atOnceUsers, global, scenario, getParameter } from "@gatling.io/core";
import { http } from "@gatling.io/http";

Define the Simulation function#

The simulation function takes the setUp function as an argument, which is used to write a script. To add the simulation function, after the import statements, add:

export default simulation((setUp) => {

});

Define an HTTP protocol#

Inside the simulation function, define an HTTP protocol. Learn about all of the HttpProtocolBuilder options in the Documentation. For this example, the baseUrl property is hardcoded as the Gatling e-commerce test site, and the acceptHeader is set to application/json. Add the HTTP protocol:

export default simulation((setUp) => {
  // Define HTTP configuration
  // Reference: https://docs.gatling.io/reference/script/protocols/http/protocol/
  const httpProtocol = http
    .baseUrl("https://api-ecomm.gatling.io")
    .acceptHeader("application/json")
    .userAgentHeader(
      "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/134.0.0.0 Safari/537.36"
    );
});

Write the scenario#

The next step is to describe the user journey. For a web application, this usually consists of a user arriving at the application and then a series of interactions with the application. The following scenario performs a get request to https://api-ecomm.gatling.io/session to retrieve the current user session. Add the scenario:

export default simulation((setUp) => {
  // Define HTTP configuration
  // Reference: https://docs.gatling.io/reference/script/protocols/http/protocol/
  const httpProtocol = http
    .baseUrl("https://api-ecomm.gatling.io")
    .acceptHeader("application/json")
    .userAgentHeader(
      "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/134.0.0.0 Safari/537.36"
    );

  // Define scenario
  // Reference: https://docs.gatling.io/reference/script/core/scenario/
  const scn = scenario("Scenario").exec(http("Session").get("/session"));
});

See the Documentation for the available scenario components.

Define the injection profile#

The final component of a Gatling simulation is the injection profile. In your simulation you must call the setUp function exactly once to configure the injection profile. If you have several scenarios, each needs its own injection profile.

The following example adds 2 users per second for 60 seconds and each user executes the scenario we defined in Write the Scenario. See the Documentation for all of the injection profile options.

export default simulation((setUp) => {
  // Define HTTP configuration
  // Reference: https://docs.gatling.io/reference/script/protocols/http/protocol/
  const httpProtocol = http
    .baseUrl("https://api-ecomm.gatling.io")
    .acceptHeader("application/json")
    .userAgentHeader(
      "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/134.0.0.0 Safari/537.36"
    );

  // Define scenario
  // Reference: https://docs.gatling.io/reference/script/core/scenario/
  const scn = scenario("Scenario").exec(http("Session").get("/session"));
  
  // Define injection profile and execute the test
  // Reference: https://docs.gatling.io/reference/script/core/injection/
  setUp(scn.injectOpen(constantUsersPerSec(2).during(60)))
    .protocols(httpProtocol);
});

Congrats! You have written your first Gatling simulation. The next step is to learn how to run the simulation.

Test execution#

Now, you should have a completed simulation that looks like the following:

import { constantUsersPerSec, scenario, simulation } from "@gatling.io/core";
import { http } from "@gatling.io/http";

export default simulation((setUp) => {
  // Define HTTP configuration
  // Reference: https://docs.gatling.io/reference/script/protocols/http/protocol/
  const httpProtocol = http
    .baseUrl("https://api-ecomm.gatling.io")
    .acceptHeader("application/json")
    .userAgentHeader(
      "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/134.0.0.0 Safari/537.36"
    );

  // Define scenario
  // Reference: https://docs.gatling.io/reference/script/core/scenario/
  const scn = scenario("Scenario").exec(http("Session").get("/session"));
  
  // Define injection profile and execute the test
  // Reference: https://docs.gatling.io/reference/script/core/injection/
  setUp(scn.injectOpen(constantUsersPerSec(2).during(60)))
    .protocols(httpProtocol);
});

Package, upload and run your simulation to Gatling Enterprise#

You can package, deploy, and run your simulation using one of two approaches, depending on whether you prefer a manual or automated process.

Simple Manual Use Case#

1. Manually generate the package by executing the following command locally on your developer’s workstation:

   npx gatling enterprise-package
   

2. The above command will create a packaged jar file in your project’s target directory.

3. From your Gatling Enterprise console, go to Packages. Create a new package specifying its name, team that owns it, select your packaged jar file for upload then click Save.

4. Go to Simulations > Create a simulation > Test as code. Under Select a package, choose the newly created package, then click Create.

5. Configure your simulation parameters:

   • Simulation name.
   • Under Select your package and simulation > Simulation, select your simulation class.
   • Under Configure your locations, choose the Managed type and select a location based on your preference.
   • Click Save and launch.

Advanced Use Case with Automated Deployments (Configuration-as-Code)#

Gatling Enterprise is a feature-rich SaaS platform that is designed for teams and organizations to get the most out of load testing. With the trial account, you created in the Prerequisites section, you can upload and run your test with advanced configuration, reporting, and collaboration features.

From Gatling 3.11 packaging and running simulations on Gatling Enterprise is simplified by using configuration as code. In this tutorial, we only use the default configuration to demonstrate deploying your project. You can learn more about customizing your configuration with our configuration-as-code guide.

To deploy and run your simulation on Gatling Enterprise, use the following procedure:

1. Generate an API token with the Configure permission in your Gatling Enterprise account.

2. Add the API token to your current terminal session by replacing <your-API-token> with the API token generated in step 1 and running the following command:

   Linux/MacOS  Windows  

   export GATLING_ENTERPRISE_API_TOKEN=<your-API-token>
   

   set GATLING_ENTERPRISE_API_TOKEN=<your-API-token>
   

3. Run one of the following two commands according to your needs:

   • To deploy your package and start the simulation, run:

     npx gatling enterprise-start --enterprise-simulation="<simulation name>"
     

   • To deploy your package without starting a run:

     npx gatling enterprise-deploy
     

Watch the Simulation deploy automatically and generate real-time reports.

Test the simulation locally Optional#

The open-source version of Gatling allows you to run simulations locally, generating load from your computer. This is ideal for learning, crafting, and debugging simulations.

Using the terminal, you can launch your test with the following command in the javascript project directory:

npx gatling run --simulation basicSimulation

When the test has finished, there is an HTML link in the terminal that you can use to access the static report.

Edit this page on GitHub