diff --git a/content/tutorials/scripting-intro/code/ComputerDatabaseSimulation.java b/content/tutorials/scripting-intro/code/BasicSimulation.java similarity index 52% rename from content/tutorials/scripting-intro/code/ComputerDatabaseSimulation.java rename to content/tutorials/scripting-intro/code/BasicSimulation.java index e9848be..499dca3 100644 --- a/content/tutorials/scripting-intro/code/ComputerDatabaseSimulation.java +++ b/content/tutorials/scripting-intro/code/BasicSimulation.java @@ -15,7 +15,7 @@ */ //#full-example -package computerdatabase; +package example; import static io.gatling.javaapi.core.CoreDsl.*; import static io.gatling.javaapi.http.HttpDsl.*; @@ -23,21 +23,24 @@ import io.gatling.javaapi.core.*; import io.gatling.javaapi.http.*; -public class ComputerDatabaseSimulation extends Simulation { +public class BasicSimulation extends Simulation { + // Define HTTP configuration + // Reference: https://docs.gatling.io/reference/script/protocols/http/protocol/ HttpProtocolBuilder httpProtocol = - http.baseUrl("https://computer-database.gatling.io") - .acceptHeader("application/json") - .contentTypeHeader("application/json"); +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"); - ScenarioBuilder myFirstScenario = scenario("My First Scenario") - .exec(http("Request 1") - .get("/computers/")); + // Define scenario + // Reference: https://docs.gatling.io/reference/script/core/scenario/ + ScenarioBuilder scenario = + scenario("Scenario").exec(http("Session").get("/session")); + // Define injection profile and execute the test + // Reference: https://docs.gatling.io/reference/script/core/injection/ { - setUp( - myFirstScenario.injectOpen(constantUsersPerSec(2).during(60)) - ).protocols(httpProtocol); + setUp(scenario.injectOpen(constantUsersPerSec(2).during(60))).protocols(httpProtocol); } } //#full-example diff --git a/content/tutorials/scripting-intro/code/ScriptingIntro1SampleJava.java b/content/tutorials/scripting-intro/code/ScriptingIntro1SampleJava.java index 4f46bd9..6889955 100644 --- a/content/tutorials/scripting-intro/code/ScriptingIntro1SampleJava.java +++ b/content/tutorials/scripting-intro/code/ScriptingIntro1SampleJava.java @@ -15,7 +15,7 @@ */ //#setup-the-file -package computerdatabase; +package example; import static io.gatling.javaapi.core.CoreDsl.*; import static io.gatling.javaapi.http.HttpDsl.*; @@ -25,9 +25,9 @@ //#setup-the-file class ScriptingIntro1SampleJava { - //#extend-the-simulation-class - public class ComputerDatabaseSimulation extends Simulation { +//#extend-the-simulation-class +public class BasicSimulation extends Simulation { - } - //#extend-the-simulation-class +} +//#extend-the-simulation-class } diff --git a/content/tutorials/scripting-intro/code/ScriptingIntro2SampleJava.java b/content/tutorials/scripting-intro/code/ScriptingIntro2SampleJava.java index 4d1b8c6..55aa247 100644 --- a/content/tutorials/scripting-intro/code/ScriptingIntro2SampleJava.java +++ b/content/tutorials/scripting-intro/code/ScriptingIntro2SampleJava.java @@ -21,14 +21,16 @@ import io.gatling.javaapi.http.*; class ScriptingIntro2SampleJava { - //#define-the-protocol-class - public class ComputerDatabaseSimulation extends Simulation { +//#define-the-protocol-class +public class BasicSimulation extends Simulation { - // Add the HttpProtocolBuilder: - HttpProtocolBuilder httpProtocol = - http.baseUrl("https://computer-database.gatling.io") - // set the "accept" header to a value suited for the expected response - .acceptHeader("text/html"); - } - //#define-the-protocol-class + // Define HTTP configuration + // Reference: https://docs.gatling.io/reference/script/protocols/http/protocol/ + HttpProtocolBuilder 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-the-protocol-class } diff --git a/content/tutorials/scripting-intro/code/ScriptingIntro3SampleJava.java b/content/tutorials/scripting-intro/code/ScriptingIntro3SampleJava.java index 05faa00..23bb54d 100644 --- a/content/tutorials/scripting-intro/code/ScriptingIntro3SampleJava.java +++ b/content/tutorials/scripting-intro/code/ScriptingIntro3SampleJava.java @@ -21,17 +21,21 @@ import io.gatling.javaapi.http.*; class ScriptingIntro3SampleJava { - //#write-the-scenario - public class ComputerDatabaseSimulation extends Simulation { +//#write-the-scenario +public class BasicSimulation extends Simulation { - HttpProtocolBuilder httpProtocol = - http.baseUrl("https://computer-database.gatling.io") - // set the "accept" header to a value suited for the expected response - .acceptHeader("text/html"); + // Define HTTP configuration + // Reference: https://docs.gatling.io/reference/script/protocols/http/protocol/ + HttpProtocolBuilder 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"); - // Add the ScenarioBuilder: - ScenarioBuilder myScenario = scenario("My Scenario") - .exec(http("Request 1").get("/computers/")); + // Define scenario + // Reference: https://docs.gatling.io/reference/script/core/scenario/ + ScenarioBuilder scenario = + scenario("Scenario").exec(http("Session").get("/session")); } - //#write-the-scenario +//#write-the-scenario } diff --git a/content/tutorials/scripting-intro/code/ScriptingIntro4SampleJava.java b/content/tutorials/scripting-intro/code/ScriptingIntro4SampleJava.java index a523ae9..7356b48 100644 --- a/content/tutorials/scripting-intro/code/ScriptingIntro4SampleJava.java +++ b/content/tutorials/scripting-intro/code/ScriptingIntro4SampleJava.java @@ -21,25 +21,27 @@ import io.gatling.javaapi.http.*; class ScriptingIntro4SampleJava { - //#define-the-injection-profile - public class ComputerDatabaseSimulation extends Simulation { +//#define-the-injection-profile +public class BasicSimulation extends Simulation { - HttpProtocolBuilder httpProtocol = - http.baseUrl("https://computer-database.gatling.io") - // set the "accept" header to a value suited for the expected response - .acceptHeader("text/html"); + // Define HTTP configuration + // Reference: https://docs.gatling.io/reference/script/protocols/http/protocol/ + HttpProtocolBuilder 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"); - ScenarioBuilder myScenario = scenario("My Scenario") - .exec( - http("Request 1").get("/computers/") - ); + // Define scenario + // Reference: https://docs.gatling.io/reference/script/core/scenario/ + ScenarioBuilder scenario = + scenario("Scenario").exec(http("Session").get("/session")); - // Add the setUp block: - { - setUp( - myScenario.injectOpen(constantUsersPerSec(2).during(60)) - ).protocols(httpProtocol); - } + // Define injection profile and execute the test + // Reference: https://docs.gatling.io/reference/script/core/injection/ + { + setUp(scenario.injectOpen(constantUsersPerSec(2).during(60))).protocols(httpProtocol); } - //#define-the-injection-profile +} +//#define-the-injection-profile } diff --git a/content/tutorials/scripting-intro/index.md b/content/tutorials/scripting-intro/index.md index d62e2e9..2e92ac9 100644 --- a/content/tutorials/scripting-intro/index.md +++ b/content/tutorials/scripting-intro/index.md @@ -12,10 +12,10 @@ This guide is intended for Gatling versions `{{< var gatlingVersion >}}` and lat Gatling is a highly flexible load-testing platform. You can write load tests in Java, Kotlin, and Scala or use our [no-code feature](https://gatling.io/features/no-code-generator/) with Gatling Enterprise. In this guide, we cover a "Hello world"-style example of how to: - - [install and setup your local dev environment]({{< ref "#install-gatling" >}}), - - [write your first simulation]({{< ref "#simulation-construction" >}}), - - [run a simulation on Gatling Enterprise Cloud]({{< ref "#run-the-simulation-on-gatling-enterprise-cloud" >}}), - - [run the simulation locally for debugging]({{< ref "#run-the-simulation-locally-for-debugging" >}}). +- [install and setup your local dev environment]({{< ref "#install-gatling" >}}), +- [write your first simulation]({{< ref "#simulation-construction" >}}), +- [run a simulation on Gatling Enterprise Cloud]({{< ref "#run-the-simulation-on-gatling-enterprise-cloud" >}}), +- [run the simulation locally for debugging]({{< ref "#run-the-simulation-locally-for-debugging" >}}). {{< alert tip >}} Join the [Gatling Community Forum](https://community.gatling.io) to discuss load testing with other users. Please try to find answers in the documentation before asking for help. @@ -33,121 +33,154 @@ This section guides you through installation and setting up your developer envir - CI/CD integrations, - Java, Kotlin, and Scala SDKs -This guide uses the Java SDK with the Maven wrapper. Gatling recommends that developers use the Java SDK unless they are already experienced with Scala or Kotlin. Java is widely taught in CS courses, requires less CPU for compiling, and is easier to configure in Maven and Gradle. You can adapt the steps to your development environment using reference documentation links provided throughout the guide. +This guide uses the Java SDK with the Maven wrapper. Gatling recommends that developers use the Java SDK unless they are already experienced with Scala or Kotlin. Java is widely taught in CS courses, requires less CPU for compiling, and is easier to configure in Maven and Gradle. You can adapt the steps to your development environment using reference documentation links provided throughout the guide. ### Sign up for Gatling Enterprise Cloud Gatling Enterprise Cloud is a fully managed SaaS solution for load testing. Sign up for a [trial account](https://auth.gatling.io/auth/realms/gatling/protocol/openid-connect/registrations?client_id=gatling-enterprise-cloud-public&response_type=code&scope=openid&redirect_uri=https%3A%2F%2Fcloud.gatling.io%2Fr%2Fgatling) to run your first test on Gatling Enterprise Cloud. The [Gatling website](https://gatling.io/features) has a full list of Enterprise features. -### Install Gatling +### Clone Gatling demo repository { #install-gatling } {{< alert info >}} **Prerequisites** Java 11, 17, or 21 64-bit OpenJDK LTS (Long Term Support) version installed on your local machine. We recommend the [Azul JDK](https://www.azul.com/downloads/?package=jdk#zulu). {{< /alert >}} -This guide uses the Gatling Java SDK with Maven, which is accessed by downloading and extracting the following `zip`file: +This guide uses the Gatling Java SDK with Maven. Use the following procedure to install Gatling: -{{< button title="Download Gatling" >}} -https://github.com/gatling/gatling-maven-plugin-demo-java/archive/refs/heads/main.zip -{{< /button >}} +1. Clone the following [repository](https://github.com/gatling/se-ecommerce-demo-gatling-tests). -## Simulation construction +2. Open the project in your IDE or terminal. +3. Navigate to the `/java/maven` folder. + +## Simulation construction This guide introduces the basic Gatling HTTP features. Gatling provides a cloud-hosted web application -[https://computer-database.gatling.io](https://computer-database.gatling.io) for running sample simulations. You'll learn how to construct simulations +[https://ecomm.gatling.io](https://ecomm.gatling.io) for running sample simulations. You'll learn how to construct simulations using the Java SDK. Code examples for the Kotlin and Scala SDKs are available throughout the Documentation. ### Learn the simulation components A Gatling simulation consists of the following: -- importing Gatling classes, +- importing Gatling classes, - configuring the protocol (commonly HTTP), -- describing a scenario, +- describing a scenario, - setting up the injection profile (virtual user profile). The following procedure teaches you to develop the simulation from each constituent component. If you want to skip ahead and copy the final simulation, jump to [Test execution]({{< ref "#test-execution" >}}). Learn more about simulations in the -[Documentation]({{< ref "/reference/script/core/simulation" >}}). +[Documentation]({{< ref "/reference/script/core/simulation" >}}). -#### Setup the file +#### Setup the file -Once you have downloaded and extracted the Gatling `zip` file, open the project in your integrated development -environment (IDE). Gatling recommends the [IntelliJ community edition](https://www.jetbrains.com/idea/download/). +Once you have cloned the Gatling repo, open the project in your integrated development +environment (IDE). Gatling recommends the [IntelliJ community edition](https://www.jetbrains.com/idea/download/). -1. Navigate to and open `src/test/java/computerdatabase/ComputerDatabaseSimulation.java`. +1. Navigate to and open `java/maven/src/test/java/example/BasicSimulation.java`. 2. Modify the simulation by deleting everything below line 7 `import io.gatling.javaapi.http.*;`. 3. The simulation should now look like the following: {{< include-code "ScriptingIntro1Sample#setup-the-file" java >}} -#### Extend the `Simulation` class +#### Extend the `Simulation` class -You must extend Gatling's `Simulation` class to write a script. To extend the `Simulation` class, after the import statements, add: +You must extend Gatling's `Simulation` class to write a script. To extend the `Simulation` class, after the import statements, add: {{< include-code "ScriptingIntro1Sample#extend-the-simulation-class" java >}} #### Define the protocol class -Inside the `ComputerDatabaseSimulation` class, add an `HTTP protocol` class. Learn about all of the +Inside the `BasicSimulation` class, add an `HTTP protocol` class. Learn about all of the `HttpProtocolBuilder` options in the [Documentation]({{< ref "/reference/script/protocols/http/protocol" >}}). For -this example, the `baseUrl` property is hardcoded as the Gatling computer database test site, and the `acceptHeader` and -contentTypeHeader` properties are set to `application/json`. +this example, the `baseUrl` property is hardcoded as the Gatling e-commerce test site, and the `acceptHeader` is set to `application/json`. {{< include-code "ScriptingIntro2Sample#define-the-protocol-class" java >}} #### Write the scenario The next step is to describe the user journey. For a web application, this usually consists of a user arriving at the -application and then a series of interactions with the application. The following scenario mocks a user arriving on the -home page of the [Gatling sample application](https://computer-database.gatling.io). +application and then a series of interactions with the application. The following scenario performs a get request to `https://api-ecomm.gatling.io/session` to retrieve the current user session. {{< include-code "ScriptingIntro3Sample#write-the-scenario" java >}} See the [Documentation]({{< ref "/reference/script/core/scenario" >}}) for the available scenario -components. +components. #### Define the injection profile The final component of a Gatling simulation is the injection profile. The injection profile is contained in the `setUp` block. The following example adds 2 users per second for 60 seconds. See the -[Documentation]({{< ref "/reference/script/core/injection" >}}) for all of the injection profile options. +[Documentation]({{< ref "/reference/script/core/injection" >}}) for all of the injection profile options. {{< include-code "ScriptingIntro4Sample#define-the-injection-profile" java >}} Congrats! You have written your first Gatling simulation. The next step is to learn how to run the simulation locally -and on Gatling Enterprise Cloud. +and on Gatling Enterprise Cloud. ## Test execution -Now, you should have a completed simulation that looks like the following: +Now, you should have a completed simulation that looks like the following: -{{< include-code "ComputerDatabaseSimulation#full-example" java >}} +{{< include-code "BasicSimulation#full-example" java >}} ### Run the Simulation on Gatling Enterprise Cloud +You can package, deploy, and run your simulation using one of two approaches, depending on whether you prefer a manual or automated process. + +#### Simple Manual Use Case + +1. Manually generate the package by executing the following command locally on your developer’s workstation: + + {{< platform-toggle >}} + Linux/MacOS: ./mvnw gatling:enterprisePackage + Windows: mvnw.cmd gatling:enterprisePackage + {{}} + +2. The above command will create a packaged **jar** file in your project's **target** directory. + +3. From your Gatling Enterprise console, go to **Packages**. Create a new package specifying its name, team that owns it, select your packaged jar file for upload then click **Save**. + +4. Go to **Simulations** > **Create a simulation** > **Test as code**. Under **Select a package**, choose the newly created package, then click **Create**. + +5. Configure your simulation parameters: + - Simulation name. + - Under **Select your package and simulation** > **Simulation**, select your simulation class. + - Under **Configure your locations**, choose the _Managed_ type and select a location based on your preference. + - Click **Save and launch**. + +#### Advanced Use Case with Automated Deployments (Configuration-as-Code) + Gatling Enterprise Cloud is a feature-rich SaaS platform that is designed for teams and organizations to get the most -out of load testing. With the trial account, you created in the [Prerequisites section]({{< ref "#install-gatling" >}}), you can upload and run your test with advanced configuration, reporting, and collaboration features. +out of load testing. With the trial account, you created in the [Prerequisites section]({{< ref "#install-gatling" >}}), you can upload and run your test with advanced configuration, reporting, and collaboration features. From Gatling 3.11 packaging and running simulations on Gatling Enterprise Cloud is simplified by using [configuration as code]({{< ref "reference/execute/cloud/user/configuration-as-code" >}}). In this tutorial, we only use the default configuration to demonstrate deploying your project. You can learn more about customizing your configuration with our [configuration-as-code guide]({{< ref "guides/config-as-code" >}}). -To deploy and run your simulation on Gatling Enterprise Cloud, use the following procedure: +To deploy and run your simulation on Gatling Enterprise Cloud, use the following procedure: -1. Generate an [API token]({{< ref "/reference/execute/cloud/admin/api-tokens" >}}) with the `Configure` permission in your Gatling Enterprise Cloud account. +1. Generate an [API token]({{< ref "/reference/execute/cloud/admin/api-tokens" >}}) with the `Configure` permission in your Gatling Enterprise Cloud account. 2. Add the API token to your current terminal session by replacing `` with the API token generated in step 1 and running the following command: - {{< platform-toggle >}} - Linux/MacOS: export GATLING_ENTERPRISE_API_TOKEN= - Windows: set GATLING_ENTERPRISE_API_TOKEN= - {{}} + {{< platform-toggle >}} + Linux/MacOS: export GATLING_ENTERPRISE_API_TOKEN= + Windows: set GATLING_ENTERPRISE_API_TOKEN= + {{}} + +3. Run one of the following two commands according to your needs: -3. Run the following command in your terminal to deploy and start your simulation: + - To deploy your package **and** start the simulation, run: - {{< platform-toggle >}} - Linux/MacOS: ./mvnw gatling:enterpriseStart - Windows: mvnw.cmd gatling:enterpriseStart - {{}} + {{< platform-toggle >}} + Linux/MacOS: ./mvnw gatling:enterpriseStart -Dgatling.enterprise.simulationName="" + Windows: mvnw.cmd gatling:enterpriseStart -Dgatling.enterprise.simulationName="" + {{}} + + - To deploy your package without starting a run: + + {{< platform-toggle >}} + Linux/MacOS: ./mvnw gatling:enterpriseDeploy + Windows: mvnw.cmd gatling:enterpriseDeploy + {{}} Watch the Simulation deploy automatically and generate real-time reports. @@ -155,21 +188,22 @@ Watch the Simulation deploy automatically and generate real-time reports. The open-source version of Gatling allows you to run simulations locally, generating load from your computer. Running a new or modified simulation locally is often useful to ensure it works before launching it on Gatling Enterprise Cloud. -Using the Java SDK, you can launch your test with the following command in the project root directory: +Using the Java SDK, you can launch your test in interactive mode using the following approach: + +1. In the `java/maven` directory, run the following command: -{{< platform-toggle>}} -Linux/MacOS: ./mvnw gatling:test -Windows: mvnw.cmd gatling:test -{{}} + {{< platform-toggle>}} + Linux/MacOS: ./mvnw gatling:test + Windows: mvnw.cmd gatling:test + {{}} -Select `1 Run the Simulation locally` to start the test. +2. Choose `[1] example.BasicSimulation`. -When the test has finished, there is an HTML link in the terminal that you can use to access the static report. +When the test has finished, there is an HTML link in the terminal that you can use to access the static report. ## Keep learning You have successfully run your first test! To keep learning, we recommend the following resources: - - [Gatling Academy](https://gatling.io/academy) - - [Introduction to the Recorder]({{< ref "recorder" >}}) - - [Writing realistic tests]({{< ref "advanced" >}}) +- [Introduction to the Recorder]({{< ref "recorder" >}}) +- [Writing realistic tests]({{< ref "advanced" >}})