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-js-demo project. The JavaScript SDK is currently available for the HTTP protocol only.

Sign up for Gatling Enterprise Cloud#

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

Install Gatling#

Then, use the following procedure to install Gatling:

1. Download the JavaScript SDK 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 in your terminal.

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://computer-database.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.

Setup the file#

To set up the test file use the following procedure:

1. In your IDE create the myfirstsimulation.gatling.js file in the javascript/src/ folder.
2. Copy the following import statements and past them in the myfirstsimulation.gatling.js file.

import {
  scenario,
  simulation,
  constantUsersPerSec
} 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 computer database test site, and the acceptHeader and contentTypeHeader properties are set to application/json. Add the HTTP protocol:

export default simulation((setUp) => {

  // Add the HttpProtocolBuilder:
  const httpProtocol =
    http.baseUrl("https://computer-database.gatling.io")
      // set the "accept" header to a value suited for the expected response
      .acceptHeader("text/html");
});

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 mocks a user arriving on the home page of the Gatling sample application. Add the scenario:

export default simulation((setUp) => {

  const httpProtocol =
    http.baseUrl("https://computer-database.gatling.io")
      // set the "accept" header to a value suited for the expected response
      .acceptHeader("text/html");

  // Add the ScenarioBuilder:
  const myScenario = scenario("My Scenario")
    .exec(http("Request 1").get("/computers/"));
});

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) => {

  const httpProtocol =
    http.baseUrl("https://computer-database.gatling.io")
      // set the "accept" header to a value suited for the expected response
      .acceptHeader("text/html");

  const myScenario = scenario("My Scenario")
    .exec(
      http("Request 1").get("/computers/"));

  // Add the setUp block:
  setUp(
    myScenario.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) => {

  const httpProtocol =
    http.baseUrl("https://computer-database.gatling.io")
      .acceptHeader("application/json")
      .contentTypeHeader("application/json");

  const myScenario = scenario("My Scenario")
    .exec(http("Request 1")
      .get("/computers/"));

  setUp(
    myScenario.injectOpen(constantUsersPerSec(2).during(60))
  ).protocols(httpProtocol);
});

Package and upload your simulation to Gatling Enterprise#

To run your simulation on Gatling Enterprise, you need to package the script with all of the required files. The output of this step is a file named package.zip in the target folder. To upload your simulation to Gatling Enterprise:

1. Run the following command in your terminal:

npx gatling enterprise-package

2. Log in to your Gatling Enterprise account.
3. Click on Packages in the left-side menu.
4. Click the Create button.
5. Name the package and choose a team (default is typical for trial accounts)
6. Upload the package.zip file you created in step 1.
7. Click Save to save your package to Gatling Enterprise.

Create and run a new test on Gatling Enterprise#

An executable test on Gatling Enterprise is called a Simulation. To run your first simulation, you need to select some minimum settings.

1. Click Simulations in the left-side menu.
2. Click Create a simulation.
3. Click Create a simulation with a package
4. Fill in the General section including selecting the package you created in the Package and upload your simulation to Gatling Enterprise section.
5. Choose a location for generating virtual users from (load). The sample application provided by Gatling is hoasted near Paris, so this location will usually yield the fastest response times.
6. Click Save and launch to start your test!

(optional) Test the simulation locally#

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 myfirstsimulation

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