Explore the JavaScript SDK — From Template to Production-Ready Simulations

Why this guide exists#

Build on the quick-start information from the Installation Guide and learn how to assemble production-ready scripts. This page collects the core building blocks—scenarios, feeders, checks, workload models, and operational tips—without forcing you through every editor action. If you need a slower pace, fall back to Create your first JavaScript-based simulation.

What you will cover#

• Anatomy of a maintainable simulation module.
• Feeding data and correlating dynamic responses.
• Choosing injection profiles that mimic real traffic.
• Running, troubleshooting, and governing JavaScript-based load tests.

When we skip implementation details, we link to the relevant reference material so you can dive deeper on demand.

Prerequisites#

• Node.js 18 or newer (LTS releases recommended) with npm 8+.
• A TypeScript-friendly editor (VS Code, WebStorm, etc.).
• A non-production system you are allowed to exercise with load tests.
• Optional: a Gatling Enterprise account for distributed execution.

Setup recap#

Clone the se-ecommerce-demo-gatling-tests repository, install dependencies, and confirm that Gatling runs locally:

git clone https://github.com/gatling/se-ecommerce-demo-gatling-tests.git cd se-ecommerce-demo-gatling-tests/javascript npm install npm run gatling:test -- --simulation src/basicSimulation.gatling 

Need help with IDE configuration or project layout? Revisit the Installation Guide before continuing.

Understand the core concepts#

Mental model: translate your business journey into scenarios, feed them contextual data, drive them with an injection profile, and guard the outcome with assertions.

Assemble a baseline simulation#

Start from a single module, then break logic into helpers as the script grows.

Baseline example#

import { constantUsersPerSec, scenario, simulation } from "@gatling.io/core"; import { http, status } from "@gatling.io/http";  export default simulation((setUp) => {  const httpProtocol = http  .baseUrl("https://api-ecomm.gatling.io")  .acceptHeader("application/json");   const scn = scenario("JS Browse")  .exec(  http("GET session")  .get("/session")  .check(status().is(200))  )  .pause(1)  .exec(  http("GET catalog")  .get("/catalog")  .check(status().in(200, 304))  );   const usersPerSec = 2;  const durationSeconds = 60;   setUp(  scn.injectOpen(constantUsersPerSec(usersPerSec).during(durationSeconds))  ).protocols(httpProtocol); });

Key points:

• Keep protocol builders immutable and share them across scenarios with .protocols().
• Use environment variables (or typed configuration helpers) for quick parameterisation.
• Export the simulation as the module default so the Gatling CLI can pick it up automatically.

Enrich scenarios with data and behavior#

Feeders: avoid hot-cache artifacts#

import { exec, scenario } from "@gatling.io/core"; import { http, status } from "@gatling.io/http"; import products from "./resources/products.json" assert { type: "json" };  const productFeeder = () =>  products[Math.floor(Math.random() * products.length)];  const browse = scenario("Browse with data").exec(  (session) => session.set("product", productFeeder()),  http("View product")  .get((session) => `/items/${session.get<string>("product").sku}`)  .check(status().is(200)) ); 

• Store CSV/JSON under src/resources so they are bundled.
• Pick a strategy (random, queue, circular) that balances uniqueness and repeatability. See the Feeders reference for additional helpers.

Correlation: capture dynamic values#

import { scenario } from "@gatling.io/core"; import { css, http, status } from "@gatling.io/http";  const addWithCsrf = scenario("Add with CSRF")  .exec(  http("Get account")  .get("/account")  .check(css("input[name='csrfToken']", "value").saveAs("csrf"))  )  .pause(1)  .exec(  http("Submit form")  .post("/account")  .formParam("csrfToken", (session) => session.get<string>("csrf"))  .check(status().in(200, 302))  ); 

• Pair extractors with a status/content check so failures surface immediately.
• Choose the extractor that matches the response format (jsonPath, css, regex, etc.). The check reference lists every option.

Compose journeys#

Break long user journeys into reusable chains:

import { exec, scenario } from "@gatling.io/core"; import { http, status } from "@gatling.io/http";  const search = exec(  http("Search")  .get("/search")  .queryParam("q", (session) => session.get<string>("term"))  .check(status().is(200)) );  const view = exec(  http("View item")  .get((session) => `/items/${session.get<string>("sku")}`)  .check(status().in(200, 304)) );  const browse = scenario("Browse").repeat(3).on(search, view); 

Extract common chains or helpers into separate modules (e.g., src/utils/protocols.ts) and import them where needed.

Model realistic workloads#

Use injection profiles to express how traffic arrives. Combine warm-up, steady state, and cool-down phases to mimic production.

setUp(  browse.injectOpen(  nothingFor(5),  rampUsers(50).during(30),  constantUsersPerSec(10).during(60)  ),  addWithCsrf.injectOpen(constantUsersPerSec(2).during(90)) ).assertions(  global().successfulRequests().percent().gt(99),  details("Browse", "Search").responseTime().percentile3().lt(1500) );  // Import nothingFor, rampUsers, constantUsersPerSec, global, and details from "@gatling.io/core". 

Need a refresher on each injection helper? Review the injection reference and the workload modelling guide.

Run and inspect results#

• Run locally with npm run gatling:test -- --simulation <path> or in interactive mode with --interactive.
• After each run, open target/gatling/<simulation>-<timestamp>/index.html to review percentiles, throughput, and errors.
• Automate the same commands in CI, or evaluate Gatling Enterprise for distributed load and real-time dashboards.

Operational hygiene#

• Commit simulations alongside application code and review them like any other change.
• Externalize secrets via environment variables or Gatling Enterprise configuration-as-code.
• Encode SLOs with assertions so builds fail fast when thresholds are breached.
• Document scenario intent, metrics, and known caveats in README files or ADRs.

Where to go next#

• Want a slower, instructional pace? Follow Create your first JavaScript-based simulation.
• Need setup or packaging reminders? Revisit the Installation Guide.
• Expand beyond HTTP with the protocol guides and the HTTP scripting reference.
• Ready for team-wide load infrastructure? Scale out and automate with Gatling Enterprise.

Edit this page on GitHub