doc: Gatling JS

Motivation:

Changes in Gatling JS 3.10.3

src/docs/content/reference/install/oss/index.md

@@ -1,118 +1,148 @@
 ---
 menutitle: Gatling
 title: Gatling installation
-seotitle: Gatling installation with the bundle or a build tool
-description: "How to install Gatling: prerequisites, different available distributions including the bundle, Maven, Gradle and sbt, and IDE integration for IntelliJ idea and Visual Studio Code (VSCode)."
-lead: "Learn about the Java, Kotlin and Scala requirements, install Gatling with the Bundle or build tool: Maven, sbt, Gradle."
+seotitle: Gatling installation with the bundle, build tool, or package manager
+description: "How to install Gatling: prerequisites, different available distributions including the bundle, Maven, Gradle, sbt, and npm. Also IDE integration for IntelliJ idea and Visual Studio Code (VSCode)."
+lead: "Learn how to install Gatling for Java, Kotlin, Scala, JavaScript, or TypeScript. Install Gatling with the Maven, sbt, or Gradle build tool or a JavaScript package manager."
 date: 2021-04-20T18:58:06+02:00
 lastmod: 2022-12-14T21:30:56+02:00
 ---
 
-## Prerequisites
+## Introduction
 
-### Java Version
+Gatling runs on a Java Virtual Machine (JVM). You can write tests in Java, Scala, Kotlin, JavaScript, or TypeScript. We strongly recommend downloading the project `ZIP` file from this page and following the subsequent installation instructions for all languages. 
 
-Gatling supports 64bits OpenJDK LTS (Long Term Support) versions: 11, 17 and 21.
-Other JVMs such as 32bits systems or OpenJ9 are not supported.
+The installation requirements and procedures for JavaScript and TypeScript differ from the native JVM languages. To use Gatling with JavaScript or TypeScript, skip to the [Use a JavaScript package manager]({{< ref "#use-a-javascript-package-manager" >}}) section. 
 
-### Supported Languages
+Gatling also provides a [standalone bundled version]({{< ref "#use-the-standalone-bundle" >}}) that is intended for users behind a corporate firewall who might have restricted access to Maven (for example). 
 
-Since 3.7, Gatling supports writing tests in Java, Kotlin and Scala.
-Older Gatling versions only support Scala.
+## Prerequisites for Java, Scala, and Kotlin
+
+### Java version
+
+Gatling supports 64-bit OpenJDK LTS (Long Term Support) versions: 11, 17, and 21.
+Other JVMs such as, 32-bit systems or OpenJ9, are not supported. We recommend the [Azul JDK](https://www.azul.com/downloads/?package=jdk#zulu).
+
+### Supported languages
+
+Since 3.7, Gatling supports writing tests in Java, Scala, and Kotlin.
+Older Gatling versions only support Scala. 
+
+{{< alert info >}}
+We recommend selecting Java unless you are an experienced Scala or experienced Kotlin developer. 
+{{< /alert >}} 
 
 ### Gatling version
 
 {{< alert info >}}
 Make sure to use the latest version of Gatling: `{{< var gatlingVersion >}}`.
 {{< /alert >}}
 
-In particular, don't use milestones (M versions) you could find on maven central,
-those are not documented and released only for internal use or [Gatling Enterprise](https://gatling.io/products/) customers.
+In particular, don't use milestones (M versions) you could find on Maven Central;
+those are not documented and are released only for internal use or [Gatling Enterprise](https://gatling.io/products/) customers.
 
-## Using the Bundle
 
-You can use Gatling as a standalone bundle.
-Then, you'll just need a text editor, possibly with Java or Scala syntactic coloration, to edit your simulations, and you'll be able to launch Gatling from the command line. From Gatling 3.11 the bundle is based on a Maven wrapper, and we recommend using it with and IDE such as IntelliJ. 
+## Install Gatling using a `ZIP` file for build tools
 
-To install the bundle, download and extract the following `ZIP` file:
+Build tools are the preferred way for Gatling users to launch and run their scripts. From Gatling 3.11, the build tool plugins have similar functionality and commands while respecting each tool's conventions. Additionally, the Maven and Gradle tools have wrappers that allow you to run Gatling without installing Maven or Gradle on your computer. The following download buttons provide links for Maven-Java and Gradle-Java projects. Installation instructions for Kotlin and Scala are located in the [Maven]({{< ref "../integrations/build-tools/maven-plugin" >}}), [Gradle]({{< ref "../integrations/build-tools/gradle-plugin" >}}), and [sbt]({{< ref "../integrations/build-tools/sbt-plugin" >}}) plugin documentation. 
 
-{{< button title="Download Gatling" >}}
-https://repo1.maven.org/maven2/io/gatling/highcharts/gatling-charts-highcharts-bundle/{{< var gatlingVersion >}}/gatling-charts-highcharts-bundle-{{< var gatlingVersion >}}.zip
-{{< /button >}}
+If you are unsure which version to select, Java-Maven is recommended.
 
-{{< alert warning >}}
-The bundle only supports Java and Scala, not Kotlin. To use Kotlin, you'll need a [Maven]({{< ref "#maven" >}}) or [Gradle]({{< ref "#gradle" >}}) project.
-{{</ alert >}}
+To install Gatling:
+1. Download your preferred configuration.
+2. Unzip the folder. 
+3. Open the folder in your IDE.
 
 
-{{< alert warning >}}
-Windows users: we recommend that you do not place Gatling in the *Programs* folder as there may be permission and path issues.
-{{< /alert >}}
 
-In order to run Gatling, you need to have a JDK installed.
-Gatling requires at least **JDK11**. Then, we recommend that you use an up-to-date version.
+{{< button title="Download Gatling for Maven-Java" >}}
+https://github.com/gatling/gatling-maven-plugin-demo-java/archive/refs/heads/main.zip{{< /button >}}  
 
-For all details regarding the installation and the tuning of the operating system (OS), please refer to the [operations]({{< ref "../script/core/operations" >}}) section.
+{{< button title="Download Gatling for Gradle-Java" >}}
+https://github.com/gatling/gatling-gradle-plugin-demo-java/archive/refs/heads/main.zip
+{{< /button >}}  
 
-{{< alert warning >}}
-Gatling launch scripts and Gatling Maven plugin honor `JAVA_HOME` env var if it's set.
-Depending on your setup, you might end up running a different version than the one displayed with `java -version`.
-If you get strange errors such as `Unsupported major.minor version` and you were expecting to run a JDK11 or newer, you might want to explicitly set the `JAVA_HOME` env variable.
+## Manually install and configure Gatling with a build tool 
+
+You can install and configure Gatling manually by following instructions in the build tool plugin documentation:
+
+- [Maven]({{< ref "../integrations/build-tools/maven-plugin" >}})
+- [Gradle]({{< ref "../integrations/build-tools/gradle-plugin" >}})
+- [sbt]({{< ref "../integrations/build-tools/sbt-plugin" >}}) 
+
+
+## Use a JavaScript package manager
+
+{{< alert info >}} 
+- The JavaScript SDK currently only covers the `HTTP` protocol. 
+- Gatling supports installation using npm. If you use another package manager such as Yarn, you need to modify the commands accordingly.
 {{< /alert >}}
 
-The bundle structure is as follows:
+To install Gatling for JavaScript and TypeScript, you must have:
 
-* `src/test/java`: where to place your Simulations code. You must respect the package folder hierarchy.
-* `src/test/resources`: non source code files such as feeder files and templates for request bodies and configuration files for Gatling, Akka and Logback.
-* `pom.xml`: Maven informations about the project.
-* `target`: where test results are generated.
+- [Node.js](https://nodejs.org/en/download) v18 or later (LTS versions only)
+- npm v8 or later (included in the NodeJS installation)
 
-### Run a Gatling simulation
+Then, use the following procedure to install Gatling:
 
-Use the following command to starts Gatling in interactive mode:
+1. Download the Gatling JS demo project zip file using the following download button:
+{{< button title="Download Gatling for JavaScript" >}}
+https://github.com/gatling/gatling-js-demo/archive/refs/heads/main.zip{{< /button >}}  
 
-{{< code-toggle console >}}
-Linux/MacOS: ./mvnw gatling:test
-Windows: mvnw.cmd gatling:test
-{{</ code-toggle >}}
+2. Unzip and open the project in your IDE or terminal.
+3. navigate to the `/javascript` folder for JavaScript projects or the `/typescript` folder for TypeScript projects in your terminal. 
+4. Run `npm install` to install the packages and dependencies. 
 
-### Start the Gatling Recorder
+You can run the pre-configured demo simulation from the `src/` folder with the following command:
 
-The [Gatling Recorder]({{< ref "/reference/script/protocols/http/recorder/" >}}) allows you to capture browser-based actions and convert them into a script. Use the following command to launch the Recorder:
 
 {{< code-toggle console >}}
-Linux/MacOS: ./mvnw gatling:recorder
-Windows: mvnw.cmd gatling:recorder
+JavaScript: npx gatling run --simulation computerdatabase
+TypeScript: npx gatling run --typescript --simulation computerdatabase
 {{</ code-toggle >}}
 
 
-## Using a Build Tool
-
-### Maven
+{{< alert info >}}
+To learn more about developing Gatling tests in JavaScript/TypeScript, follow the [Intro to scripting]({{< ref "/tutorials/scripting-intro/" >}}) tutorial.
+{{< /alert >}}
 
-Maven can be used for Gatling projects with Java, Kotlin and Scala.
+## Use the standalone bundle
 
-Gatling provides an official maven plugin named `gatling-maven-plugin`. This plugin lets you compile your code and launch Gatling simulations.
+The Gatling bundle is primarily intended for users who don't have internet access (e.g., behind a corporate firewall). Otherwise, we strongly recommend using the Maven plugin, which is lighter and easier to push to Git. Pay attention to the subsequent warnings to understand the limitations of the standalone bundle. 
 
-Check the [Maven plugin documentation]({{< ref "../integrations/build-tools/maven-plugin" >}}) for more information.
+From Gatling 3.11, the bundle is based on a Maven wrapper, and we recommend using it with an IDE such as IntelliJ. 
 
-### Gradle
+{{< button title="Download for Gatling bundle" >}}
+https://repo1.maven.org/maven2/io/gatling/highcharts/gatling-charts-highcharts-bundle/{{< var gatlingVersion >}}/gatling-charts-highcharts-bundle-{{< var gatlingVersion >}}.zip
+{{< /button >}}
 
-Gradle can be used for Gatling projects with Java, Kotlin and Scala.
 
-Gatling provides an official gradle plugin named `io.gatling.gradle`. This plugin lets you launch your Gatling simulations.
+{{< alert warning >}}
+The bundle only supports Java and Scala, not Kotlin. To use Kotlin, you'll need [Maven or Gradle]({{< ref "#install-gatling-using-a-zip-file-for-build-tools" >}}) project.
+{{</ alert >}}
 
-Check the [Gradle plugin documentation]({{< ref "../integrations/build-tools/gradle-plugin" >}}) for more information.
+{{< alert warning >}}
+Windows users: 
+- we recommend that you do not place Gatling in the *Programs* folder as there may be permission and path issues. 
+- The standard Windows zip tool will not work to extract the bundle. We recommend using [7-zip](https://www.7-zip.org/) instead.
+{{< /alert >}}
 
-### sbt
+For all details regarding the installation and the tuning of the operating system (OS), please refer to the [operations]({{< ref "../script/core/operations" >}}) section.
 
-sbt can be used for Gatling projects with Scala only.
+{{< alert warning >}}
+Gatling launch scripts and Gatling Maven plugin honor `JAVA_HOME` env var if it's set.
+Depending on your setup, you might end up running a different version than the one displayed with `java -version`.
+If you get strange errors such as `Unsupported major.minor version` and you were expecting to run a JDK11 or newer, you might want to explicitly set the `JAVA_HOME` env variable.
+{{< /alert >}}
 
-Gatling provides an official sbt plugin named `gatling-sbt`. This plugin lets you launch your Gatling simulations.
+The bundle structure is as follows:
 
-Check the [sbt plugin documentation]({{< ref "../integrations/build-tools/sbt-plugin" >}}) for more information.
+* `src/test/java`: where to place your Simulations code. You must respect the package folder hierarchy.
+* `src/test/resources`: non source code files such as feeder files and templates for request bodies and configuration files for Gatling, Akka and Logback.
+* `pom.xml`: Maven informations about the project.
+* `target`: where test results are generated.
 
-## Using an IDE
+## Use Gatling with an IDE
 
 You can edit your Simulation classes with any text editor, maybe with some syntactic coloration for your chosen language.
 But if you are a developer, you'll most likely want to use your favorite IDE with Gatling.
@@ -122,7 +152,7 @@ But if you are a developer, you'll most likely want to use your favorite IDE wit
 IntelliJ IDEA Community Edition comes with Java, Kotlin, maven and gradle support enabled by default.
 
 If you want to use Scala and possibly sbt, you'll have to install the Scala plugin, which is available in the Community Edition.
-You'll most likely have to increase the stack size for the scala compiler, so you don't suffer from StackOverflowErrors.
+You'll most likely have to increase the stack size for the Scala compiler so you don't suffer from StackOverflowErrors.
 We recommend setting `Xss` to `100M`.
 
 {{< img src="intellij-scalac-xss.png" alt="intellij-scalac-xss.png" >}}
@@ -134,12 +164,32 @@ We recommend that you have a look at the official documentation for setting up V
 * [with Kotlin](https://kotlinlang.org/docs/jvm-get-started.html)
 * [with Scala](https://scalameta.org/metals/)
 
-### Launching Gatling and the Recorder from the IDE
 
-All Maven, Gradle and sbt demo projects contain some helper classes you can use to trigger some Gatling tasks.
+## Run a demo load test
+
+If you installed Gatling using a `ZIP` file download it comes pre-loaded with a fully functioning load test. You can run this test locally to instantly experience Gatling's functionality and reports feature. The following sections help you to run your first test. The provided commands work for Maven, JavaScript/TypeScript, and the bundle. Refer to the plugin documentation for [Gradle]({{< ref "../integrations/build-tools/gradle-plugin" >}}) or [sbt]({{< ref "../integrations/build-tools/sbt-plugin" >}}) users. 
+
+### Run a Gatling simulation
+
+Use the following command to start Gatling in interactive mode:
+
+{{< code-toggle console >}}
+Linux/MacOS: ./mvnw gatling:test
+Windows: mvnw.cmd gatling:test
+
+{{</ code-toggle >}}
+
+### Start the Gatling Recorder
+
+The [Gatling Recorder]({{< ref "/reference/script/protocols/http/recorder/" >}}) allows you to capture browser-based actions and convert them into a script. Use the following command to launch the Recorder:
+
+{{< code-toggle console >}}
+Linux/MacOS: ./mvnw gatling:recorder
+Windows: mvnw.cmd gatling:recorder
+{{</ code-toggle >}}
 
-You can right-click on the `Engine` class in your IDE and launch the Gatling load test engine.
-Simulation reports will be written in your `target` directory.
+For the JavaScript SDK:
 
-You can right-click on the `Recorder` class in your IDE and launch the Recorder.
-Simulations will be generated in you `src/test/sources` directory.
+```console
+npx gatling recorder
+```

src/docs/content/reference/script/core/simulation/code/SimulationSampleJS.js

@@ -27,11 +27,13 @@ const httpProtocol1 = http;
 const httpProtocol2 = http;
 
 //#setUp
-const scn = scenario("scn"); // etc...
+export default simulation((setUp) => {
+  const scn = scenario("scn"); // etc...
 
-setUp(
-  scn.injectOpen(atOnceUsers(1))
-);
+  setUp(
+    scn.injectOpen(atOnceUsers(1))
+  );
+});
 //#setUp
 
 //#setUp-multiple

src/docs/content/reference/script/core/simulation/index.md

@@ -2,16 +2,16 @@
 title: Simulation
 seotitle: Gatling Simulation scripting reference
 description: Learn about the structure of the Gatling simulation, including required imports, protocol configuration and setUp.
-lead: "Learn about the main parts of a Gatling simulation: DSL imports, scenario definitions, simulation definitions, hooks."
+lead: "Learn about the main parts of a Gatling simulation: DSL imports, scenario definitions, simulation definitions, and hooks."
 date: 2021-04-20T18:30:56+02:00
 lastmod: 2022-12-14T21:30:56+02:00
 ---
 
-`Simulation` is the parent class your tests must extend so Gatling can launch them.
+`Simulation` is the parent class (function in JavaScript|TypeScript) your tests must extend so Gatling can launch them.
 
 {{< alert warning >}}
 We recommend that your Simulation's name does not start with `Test`.
-Some tools such as maven surefire aggressively consider that all classes with such naming patterns are for them to handle, and they will try to launch them.
+Some tools such as Maven Surefire aggressively consider that all classes with such naming patterns are for them to handle, and they will try to launch them.
 {{< /alert >}}
 
 ## DSL imports
@@ -31,7 +31,7 @@ Beware that any class that doesn't belong to those packages is considered privat
 
 ## setUp
 
-Most pieces of your tests can possibly be extracted into other helper classes so you can bring your own test libraries: scenarios, protocols, headers, injection profiles, etc.
+Most pieces of your tests can possibly be extracted into other helper classes (helper functions in JavaScript|TypeScript) so you can bring your own test libraries: scenarios, protocols, headers, injection profiles, etc.
 
 The only mandatory piece in your Simulations is that they must call the `setUp` method exactly once in their constructor to register the test components.
 
@@ -126,7 +126,7 @@ Gatling provides two hooks:
 The lifecycle is as follows:
 
 1. Gatling starts
-2. Simulation constructor is called and all the code in the class body not delayed in `before` and `after` hooks is executed
+2. Simulation constructor is called, and all the code in the class body that is not delayed in the `before` and `after` hooks is executed.
 3. `before` hook is executed
 4. Simulation runs
 5. Simulation terminates

src/docs/content/reference/script/protocols/http/recorder/index.md

@@ -10,7 +10,23 @@ lastmod: 2022-12-14T21:30:56+02:00
 The Gatling Recorder helps you to quickly generate scenarios, by either acting as a HTTP proxy between the browser and the HTTP server or converting HAR (Http ARchive) files.
 Either way, the Recorder generates a simple simulation that mimics your recorded navigation.
 
-If you're using the bundle, you can launch it with the following script `$GATLING_HOME/bin/recorder.sh`.
+If you're using the bundle or the Maven plugin, you can launch the Recorder with the following command:
+
+{{< code-toggle console >}}
+Linux/MacOS: ./mvnw gatling:recorder
+Windows: mvnw.cmd gatling:recorder
+{{</ code-toggle >}}
+
+For the JavaScript SDK:
+
+```console
+npx gatling recorder
+```
+{{< alert tip >}}
+The Recorder is also available for the [sbt]({{< ref="../integrations/build-tools/sbt-plugin/" >}}) and [Gradle]({{< ref="../integrations/build-tools/gradle-plugin/" >}}) build tool plugins. See their respective documentation for more information.
+{{< /alert >}}
+
+
 You will get a window that looks like this one:
 
 {{< img src="recorder.png" alt="recorder.png" >}}