skip to content

JavaScript and TypeScript Packages

2 roadmaps5 questions

The npm face of the same DSL: three packages, a default-exported simulation function in place of a subclass, and the file names the CLI discovers a simulation by. Most candidates miss it exists.

on this pageshow

explore

questions

5

Which npm packages does a Gatling HTTP simulation written in JavaScript or TypeScript depend on, and which of them provides the gatling command-line tool?

level: juniorimportance: must knowfreq 45%

answer

  1. Three packages, not one
  2. One scoped npm family, @gatling.io
  3. DSL package plus protocol package
  4. The CLI one is a dev dependency

basics

~10 s

Three: @gatling.io/core for the DSL and the simulation function, @gatling.io/http for the HTTP protocol builder, and @gatling.io/cli, a dev dependency that supplies the gatling command you invoke as npx gatling.

solid answer

~40 s

You install `@gatling.io/core` and `@gatling.io/http` as normal dependencies and `@gatling.io/cli` as a dev dependency. Core exports the pieces every simulation uses — `simulation`, `scenario`, `exec`, injection steps such as `atOnceUsers` and `constantUsersPerSec` — while `http` exports the `http` protocol builder and HTTP check helpers such as `status`. The CLI package is never imported by your code; it just puts a `gatling` executable in the project so `npx gatling` works without a global install. Protocol packages such as `@gatling.io/grpc`, `@gatling.io/mqtt` and `@gatling.io/postman` are added the same way. They all share one release line — on the 3.15 generation Gatling's own documentation project pins every `@gatling.io` package at 3.15.105 — and the documented upgrade procedure bumps them together.

code

bash · 4 lines
bash
npm install --save-dev "@gatling.io/cli"
npm install --save "@gatling.io/core"
npm install --save "@gatling.io/http"
npx gatling --help

go deeper

for a junior

Be ready to name the three packages and say which install flag each one takes. Knowing that npx gatling comes from a dev dependency is the detail interviewers actually probe.

for a middle

Explain why the CLI package is never imported, and why every @gatling.io package has to sit on one version. Mention the transitive jvm-types package if you want to show you have read the lockfile.

for a senior

Own the upgrade procedure: read the upgrade guides for breaking changes first, then bump core, http and cli together in package.json and reinstall — those two edits are the documented procedure itself. Say what you check when a bump changes DSL behaviour.

for a principal

Decide how the SDK version is governed across many repositories — a shared starter project, a renovation bot, or a pinned internal template — and who is accountable when an SDK bump breaks a suite.

Gatling's JavaScript/TypeScript SDK is published on npm as a family of scoped packages under `@gatling.io`. Gatling's documentation treats it as **one SDK serving both languages** — it is called *the JavaScript/TypeScript SDK*, and as often simply *the JavaScript SDK*, but never a TypeScript SDK of its own — so there is no JavaScript package family and separate TypeScript package family to choose between. A working HTTP test normally pulls in three packages. ## The three packages ```shell npm install --save-dev "@gatling.io/cli" npm install --save "@gatling.io/core" npm install --save "@gatling.io/http" ``` | package | installed as | what it gives you | |---|---|---| | `@gatling.io/core` | runtime dependency | `simulation`, `scenario`, `exec`, injection steps (`atOnceUsers`, `rampUsers`, `constantUsersPerSec`), assertion entry points such as `global`, and helpers such as `getParameter` and `getEnvironmentVariable` | | `@gatling.io/http` | runtime dependency | the `http` protocol builder and the HTTP check helpers, e.g. `status` | | `@gatling.io/cli` | **dev** dependency | the `gatling` command itself, run as `npx gatling` | ## Why the CLI package is the odd one out - `core` and `http` are **imported by your simulation source**, so they belong in `dependencies` — they are part of the thing being run. - `@gatling.io/cli` is imported by nothing. It exists so that a `gatling` executable lands in the project's `node_modules`, which is what lets `npx gatling` find it **without a global install and without touching your shell's `PATH`**. - Because it is an ordinary local binary, Gatling's docs suggest aliasing the invocations you use most in the `scripts` block of `package.json`. - You can explore the surface with `npx gatling --help`, and a single command's options with `npx gatling <command> --help`. ## Beyond HTTP The same family carries protocol packages you add only if you need them: `@gatling.io/grpc`, `@gatling.io/mqtt` and `@gatling.io/postman`. They are installed exactly like `http`, and each declares `@gatling.io/core` as its own dependency, so they must sit at the version core sits at. ## Keeping the versions in step Every `@gatling.io` package moves on one release line, and mixing versions is the failure the documented upgrade procedure is designed to prevent. The documentation prefaces that procedure with the advice to read Gatling's upgrade guides for breaking changes, and then gives exactly two steps: 1. Edit `package.json`, setting your project `version` and the versions of `@gatling.io/core`, `@gatling.io/http` and `@gatling.io/cli` to the release you want, and save the file. 2. Run `npm install`. The upgrade-guides check is documented as advice preceding the procedure rather than as a step of it, but it is the half people skip: an SDK bump can carry breaking DSL changes, so read the notes for the target release before you trust the suite again. The npm packages have their own patch numbering rather than reusing Gatling's: at the **3.15** generation, Gatling's own documentation project pins `@gatling.io/core`, `@gatling.io/http`, `@gatling.io/grpc`, `@gatling.io/mqtt` and `@gatling.io/postman` all at **3.15.105**, and `core` and `http` each pull one shared transitive package, `@gatling.io/jvm-types`, at that same version. Treat the `@gatling.io` version as a single number for the whole project. ## What the environment has to provide - **Node.js 24 or later** (Gatling supports LTS releases) and **npm 11 or later**, which ships with Node. - Another package manager such as Yarn *should* work, but you adapt the equivalent commands and configuration yourself. - Extra npm libraries are allowed with two limits: they must not rely on **native, non-JavaScript binaries**, and they must not use **JavaScript APIs specific to Node.js**. - Dev dependencies for your own toolchain are unconstrained, because they only ever run over your source — Gatling's demo projects ship a Prettier configuration for exactly that reason. ## One SDK, two languages Nothing in this package list distinguishes JavaScript from TypeScript, and that is deliberate rather than an omission: - **The imports are identical.** A JavaScript file and a TypeScript file import the same names from the same specifiers; there is no `@gatling.io/core-ts`. - **The types ship with the packages.** TypeScript declarations come from the same install, so a type such as `Session` is imported from `@gatling.io/core` alongside the functions. Gatling's entire documentation sample set is written as TypeScript files and type-checked in strict mode against these packages. - **Even the recorder does not distinguish them.** Gatling's recorder can generate a starting simulation in each supported format, and its JavaScript and TypeScript formats emit the *same* body — the same imports, the same `export default simulation(...)` — differing only in the file extension they are saved under. So "should we use JavaScript or TypeScript" is a question about your own project's toolchain, not about which Gatling packages to install. ## How this differs from the JVM setup On the JVM you declare Gatling as a build-tool dependency and a build plugin gives you a task to launch it. Here, **npm is both the dependency manager and the route to the launcher**: the dependencies come from `package.json` and the launcher comes from a dev dependency you invoke through `npx`. There is no plugin to configure and no compile step of your own to wire up. If you would rather not assemble this by hand, Gatling publishes a `gatling-js-demo` repository containing a ready-made JavaScript project and a ready-made TypeScript project, both already wired to these packages.

  • Why is @gatling.io/cli installed with --save-dev while core and http are not?
    Your simulation source imports `core` and `http`, so they are part of what runs. Nothing imports the CLI package — it only places a `gatling` executable in `node_modules`, which is what `npx gatling` resolves. That makes it tooling, and tooling belongs in `devDependencies`.
  • Which other @gatling.io packages exist beyond core, http and cli?
    Protocol packages: `@gatling.io/grpc`, `@gatling.io/mqtt` and `@gatling.io/postman`. Each depends on `@gatling.io/core`, so they are installed like `http` and pinned to the same version as the rest of the family. Add one only when you actually drive that protocol.
  • How does a JavaScript simulation read a value supplied on the command line?
    Pass it as `key=value` on the run command, then read it with `getParameter` from `@gatling.io/core`, which takes the key and an optional default: `parseInt(getParameter("users", "1"))`. The same package exports `getEnvironmentVariable` for values that arrive through the environment instead.

saying these in an interview costs you the question

  • Believing one gatling npm package holds the whole SDK
  • Installing the CLI globally instead of as a dev dependency
  • Letting core, http and cli drift onto different versions
  • Thinking JavaScript and TypeScript need different Gatling packages
open as a page

In a Gatling simulation file written in JavaScript or TypeScript, what must the module export, and where does the setUp function it calls come from?

level: middleimportance: must knowfreq 40%

basics

~20 s

The module's default export must be the value returned by simulation(...), imported from @gatling.io/core. That call takes one callback, and Gatling hands setUp into it as an argument — there is no class to extend and nothing to construct.

open as a page

Running npx gatling run does not offer a TypeScript simulation you just added, so which folder and file-name pattern does the Gatling JavaScript CLI search, and how do you point it at a different folder?

level: middleimportance: should knowfreq 35%

basics

~10 s

By default the gatling CLI searches the src folder for files ending in .gatling.js or .gatling.ts, at that folder's root, each default-exporting a simulation. Point it elsewhere with the --sources-folder option.

open as a page

When the Gatling JavaScript CLI runs a TypeScript simulation, what is it executing the simulation on, and what does that rule out when you add an npm library to the project?

level: seniorimportance: should knowfreq 25%

basics

~20 s

Not your local Node process. The gatling CLI downloads a Gatling runtime bundle and caches it under a .gatling home directory, and runs your simulation there — so added libraries must avoid native binaries and Node-specific JavaScript APIs.

open as a page

A Gatling suite is written in Java and maintained by a platform team while the product engineers write TypeScript, so how would you decide whether to move it onto Gatling's JavaScript and TypeScript SDK?

level: principalimportance: nice to knowfreq 18%

basics

~20 s

Decide on ownership, not syntax. The DSL vocabulary and the engine are the same, so the move buys maintainability by the product engineers and costs a rewrite, an npm toolchain, and an audit for constructs the JavaScript SDK does not have.

open as a page