JavaScript load testing with Gatling:
The complete guide

Gatling now speaks JavaScript and TypeScript. You write tests in JS. Gatling runs them on its proven engine.

Developers write simulations in JS/TS. Gatling compiles them to the JVM using GraalVM. You keep familiar syntax, npm packages, and modern tooling.

The result: JavaScript teams get enterprise‑grade load tests without switching stacks.

This guide explains why the JavaScript SDK matters, how it works, and how to start. It also covers Enterprise features, best practices, and current limits.

Why JavaScript?

JavaScript isn’t just a front-end language anymore—it’s the most widely used language across the stack. From React apps to Node.js APIs, full-stack JavaScript is the default for modern web development. So it only makes sense for performance testing to live in that same world.

Here’s why scripting load tests in JavaScript is a game-changer:

• Fewer context switches: Developers no longer need to bounce between Scala, XML, or DSLs. They can write, debug, and maintain tests in the same language they use to build the product.
  
  
• Faster onboarding: Junior developers, QA testers, or engineers new to performance testing can ramp up quickly. No extra language to learn. No legacy syntax to decipher.
  
  
• npm ecosystem: Want to generate fake users with Faker? Validate data with Lodash? Hash tokens with crypto? It’s all one import away. Gatling’s JavaScript SDK lets you bring your existing tools and workflows into your tests.
  
  
• Modern language features: With TypeScript, you get autocomplete, type checking, and IDE support. That means fewer bugs, easier maintenance, and faster iteration.
  
  
• Closer collaboration across teams: QA, Dev, and SRE teams can all work from the same scripts. JavaScript is a shared language across roles, helping break silos between developers and testers.
  ‍

{{cta}}

How the Gatling JavaScript SDK works

• Written in TypeScript for strong typing, safety, and IDE help
  
• Runs on GraalVM to map JS calls to Gatling’s Java API
  
• Uses the same high‑performance engine as Java, Kotlin, and Scala
  
• Ships core packages: @gatling.io/core, @gatling.io/http, @gatling.io/cli

Quick example

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

export default simulation((setUp) => {
  const httpProtocol = http
    .baseUrl("https://api.example.com")
    .acceptHeader("application/json")
    .contentTypeHeader("application/json");

  const scn = scenario("Get users").exec(
    http("List users")
      .get("/users")
      .check(status().is(200))
  );

  setUp(scn.injectOpen(constantUsersPerSec(20).during(120))).protocols(httpProtocol);
});

Why JavaScript developers will feel at home

• Code and test in the same language: No context switching between JS and JVM languages
  
• Use npm packages: Data generation, crypto, date utils, and more
  
• TypeScript first: Autocomplete, type defs, and clear errors
  
• Recorder included: Capture browser flows, export clean JS/TS scripts

Gatling Enterprise for JavaScript tests

Gatling Enterprise lets teams scale and collaborate.

• Managed load generators and regional locations
  
• Real‑time dashboards, percentiles, and error views
  
• Runtime JS parameters and environment variables
  
• RBAC, teams, packages, and CI integrations
  
• Configuration‑as‑code and CLI automation
  

Typical workflow

1. Develop locally with npx gatling run
   
2. Package with npx gatling enterprise-package
   
3. Upload the package and create a simulation
   
4. Launch, monitor live, and enforce SLAs
   

Best practices with the JS SDK

Model real user journeys

• Chain login, browse, and checkout steps
  
• Pass tokens between steps
• Add think time to mimic users

const scn = scenario("Auth flow")
  .exec(
    http("Login")
      .post("/auth/login")
      .body(StringBody('{"email":"#{email}","password":"#{password}"}'))
      .check(jsonPath("$.token").saveAs("token"))
  )
  .pause(2, 5)
  .exec(
    http("Me")
      .get("/me")
      .header("Authorization", "Bearer #{token}")
      .check(status().is(200))
  );

Use realistic injection profiles

• Ramp up, hold steady, then ramp down
• Test steady load, spikes, and stress to failure

setUp(
  scn.injectOpen(
    rampUsersPerSec(1).to(50).during(300),
    constantUsersPerSec(50).during(600),
    rampUsersPerSec(50).to(0).during(300)
  )
).protocols(httpProtocol);

Treat tests like production code

• Keep tests in version control
  
• Review changes with pull requests
  
• Run in CI and gate on SLAs
  

Focus on the right metrics

• p95 and p99 latency, not only averages
  
• Error rate under load
  
• Throughput at target concurrency
  
  

SPA, API, and real‑time notes

• SPAs: test API calls that power screens, not page loads alone
  
• APIs: vary data to avoid cache bias, validate responses with checks
  
• Real‑time: use WebSocket support in JVM SDK today; JS SDK focuses on HTTP for now

Current limits and roadmap

• The JS/TS SDK currently targets HTTP scenarios
  
• Use JVM SDKs for WebSocket, gRPC, or JMS today
• Browser execution is out of scope; pair with front‑end tooling if needed
  

Get started in minutes

Prereqs: Node.js 18+ (LTS) and npm 8+

# clone demo and install
git clone https://github.com/gatling/gatling.git
cd gatling/javascript
npm install

# run locally
npx gatling run

# package for Enterprise
npx gatling enterprise-package

Create a simulation in Enterprise, pick locations, set SLAs, and launch.

CI/CD example (GitHub Actions)

name: Performance tests
on:
  push: { branches: [ main ] }
  pull_request: { branches: [ main ] }

jobs:
  perf:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with: { node-version: '18' }
      - run: |
          cd javascript
          npm install
          npx gatling run
      - uses: actions/upload-artifact@v3
        with:
          name: gatling-results
          path: javascript/results/

Gatling for JavaScript

Gatling’s JavaScript SDK brings a modern scripting experience to one of the most powerful load testing engines available. It gives developers the tools they need to test backend performance in a way that’s fast, scalable, and deeply integrated into the JavaScript ecosystem.

What makes it different

Unlike most protocol-level tools that require specialized scripting languages or legacy UIs, Gatling for JavaScript offers:

• Code-first testing: Write real tests with variables, logic, conditions, and flows—just like you would in application code. No YAML, no GUI wizard.
  
  
• Compiled performance: JavaScript simulations are compiled to Java and run on Gatling’s engine using GraalVM, combining JS ergonomics with JVM-grade performance.
  
  
• Production-grade scenarios: Support for realistic flows, think times, session management, authentication headers, and response validation—perfect for simulating user behavior and edge cases.
  
  
• Integration with Gatling Enterprise: Scale from local tests to globally distributed simulations. Define SLAs, monitor test runs in real-time, and collaborate across teams using Gatling Enterprise.
  
  
• Native TypeScript support: Built in TypeScript with full type definitions, IDE integration, and autocomplete, reducing the learning curve and preventing errors.
  
  

Who it’s for

• Developers using Node.js, Express, Next.js, or GraphQL
  
• QA testers comfortable with JavaScript, Cypress, or Playwright
  
• Platform and SRE teams who want to automate and scale testing without changing stacks
  
• Organizations standardizing on JS/TS across front-end and back-end systems

Try it today

• Write in JS/TS, run at scale
  
• Bring npm, keep type safety
  
• Use Enterprise for teams, regions, and SLAs

{{card}}