Create your first JavaScript-based simulation

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

This guide is intended for the Gatling JavaScript SDK version 3.14.703 and later.

New to Gatling and the JavaScript SDK? This tutorial walks through every edit required to produce, run, and package your first simulation. If you already know the basics and just need configuration reminders, jump to the Installation Guide. For a broader tour of feeders, checks, and workload modelling, continue with Full SDK Capabilities.

Prefer Java or a JVM language? Follow the Create your first Java-based simulation instead.

Before you begin

Install Node.js v18 or later (LTS versions recommended) with npm v8 or later.
Install Git and a code editor. We use VS Code in the instructions, but any editor works.
(Optional) Create a Gatling Enterprise trial account if you plan to run the script in the cloud.

Confirm your environment in a terminal:

node -v
npm -v

If either command fails, fix it before you continue. Visit nodejs.org to download Node.js, which includes npm.

Step 1: Clone the tutorial project

Open a terminal and run:

git clone https://github.com/gatling/se-ecommerce-demo-gatling-tests.git
cd se-ecommerce-demo-gatling-tests/javascript

Prefer ZIP downloads? Grab the archive from GitHub, extract it, and open the javascript directory in your editor.
Install the project dependencies:
```
npm install
```

The sample project targets the demo backend at https://ecomm.gatling.io. It is safe to use for practice.

Step 2: Inspect the project layout

se-ecommerce-demo-gatling-tests/
└── javascript
    ├── src/
    │   └── basicSimulation.gatling.js
    ├── package.json
    └── node_modules/

basicSimulation.gatling.js is the file you will edit.
package.json already includes the Gatling JavaScript SDK—no additional setup needed.
The .gatling.js extension tells Gatling this file contains a simulation.

Step 3: Build the simulation incrementally

Each subsection adds one concept. Keep your editor open with basicSimulation.gatling.js selected.

3.1 Clean up the starter file

Delete everything below line 2 (after import { http } from "@gatling.io/http";) so only the imports remain. The file should match:

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

3.2 Define the simulation function

Gatling JavaScript simulations use the simulation function to define tests. Add the function with setUp as its parameter:

export default simulation((setUp) => {

});

3.3 Define the HTTP protocol

Configure the target base URL and headers so Gatling knows how to talk to your application:

export default simulation((setUp) => {
  // Define HTTP configuration
  // Reference: https://docs.gatling.io/reference/script/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"
    );
});

Key callouts:

baseUrl: "https://api-ecomm.gatling.io" sets the server you will exercise.
Custom headers (accept) mimic a real browser. Adjust them when testing your own system.

3.4 Describe a scenario

Scenarios encode user journeys. Start with a single request:

export default simulation((setUp) => {
  // Define HTTP configuration
  // Reference: https://docs.gatling.io/reference/script/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/concepts/scenario/
  const scn = scenario("Scenario").exec(http("Session").get("/session"));
});

Here you:

Name the scenario ("Scenario").
Issue a GET request against /session.
Leave room to add checks or additional steps later.

3.5 Choose an injection profile

Configure the arrival rate and duration for virtual users:

export default simulation((setUp) => {
  // Define HTTP configuration
  // Reference: https://docs.gatling.io/reference/script/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/concepts/scenario/
  const scn = scenario("Scenario").exec(http("Session").get("/session"));
  
  // Define injection profile and execute the test
  // Reference: https://docs.gatling.io/concepts/injection/
  setUp(scn.injectOpen(constantUsersPerSec(2).during(60)))
    .protocols(httpProtocol);
});

This configuration launches two users per second for one minute. Tweak the numbers once the script works.

You now have a complete simulation. The finished file should match:

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/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/concepts/scenario/
  const scn = scenario("Scenario").exec(http("Session").get("/session"));
  
  // Define injection profile and execute the test
  // Reference: https://docs.gatling.io/concepts/injection/
  setUp(scn.injectOpen(constantUsersPerSec(2).during(60)))
    .protocols(httpProtocol);
});

Need a refresher on what each SDK call does? Keep the Installation Guide and the JavaScript HTTP reference handy.

Step 4: Run the simulation locally

From the javascript directory, run:
```
npx gatling run
```
When prompted, choose [2] basicSimulation.
After the run completes, open the HTML report printed in the terminal (target/gatling/basicsimulation-<timestamp>/index.html).

Troubleshooting tips:

Module not found: ensure you ran npm install in the javascript directory.
Simulation not listed: verify your file ends with .gatling.js and is in the src/ directory.
Network errors: verify you can open https://api-ecomm.gatling.io/session in a browser.

Step 5: Package and run on Gatling Enterprise

Upload your script manually or drive automated deployments.

Manual packaging

From the same directory, run:
```
npx gatling enterprise-package
```
The command produces a .zip under target/. Upload it under Packages in the Gatling Enterprise console.
Create a simulation, choose the uploaded package, select a managed location, and launch.

Automated deployment (configuration as code)

Generate an API token with the Configure permission.

Export it in your terminal session:

export GATLING_ENTERPRISE_API_TOKEN=<your-API-token>

set GATLING_ENTERPRISE_API_TOKEN=<your-API-token>

Run one of the following commands:

Deploy and start immediately:

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

Deploy only:
```
npx gatling enterprise-deploy
```

Follow the run in the Enterprise UI for live metrics and historical reporting.

Step 6: Keep learning

Repeat the tutorial against your own API—replace the base URL and adjust requests.
Enrich the scenario with checks (.check(status().is(200))) and pauses (.pause(1)), then re-run locally.
Graduate to Full SDK Capabilities for feeders, correlation, and workload modelling.
Revisit the Installation Guide when you need npm configuration or project structure advice.
Explore the Recorder tutorial to capture traffic and generate simulations automatically.

You have now installed Gatling, authored a JavaScript simulation, and executed it locally and (optionally) on Gatling Enterprise. Keep iterating!

Edit this page on GitHub

Create your first JavaScript-based simulation

Before you begin#

Step 1: Clone the tutorial project#

Step 2: Inspect the project layout#

Step 3: Build the simulation incrementally#

3.1 Clean up the starter file#

3.2 Define the simulation function#

3.3 Define the HTTP protocol#

3.4 Describe a scenario#

3.5 Choose an injection profile#

Step 4: Run the simulation locally#

Step 5: Package and run on Gatling Enterprise#

Manual packaging#

Automated deployment (configuration as code)#

Step 6: Keep learning#