> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/resilience-testing/chaos-engineering/integrations/performance-testing-tools/gatling.md).

# Load Testing with Gatling

Gatling is an open-source load testing framework designed for high-performance testing of web applications, APIs, and microservices. It helps you evaluate your system's performance and resilience under various load conditions by simulating thousands of concurrent users and generating detailed performance reports.

In the context of chaos engineering, Gatling-based load testing experiments help you:

* **Identify Performance Bottlenecks**: Discover where your system slows down under load
* **Test Scalability**: Understand how your system scales with increased demand
* **Validate SLA Compliance**: Ensure your system meets performance requirements
* **Improve Resilience**: Build confidence in your system's ability to handle traffic spikes
* **Generate Detailed Reports**: Get comprehensive performance analytics and visualizations

### Prerequisites <a href="#prerequisites" id="prerequisites"></a>

Before setting up your Gatling load test, ensure you have:

* Access to a Gatling Enterprise instance
* A configured Gatling simulation ready to run
* Appropriate permissions to create and execute pipelines in Harness

### Required Variables <a href="#required-variables" id="required-variables"></a>

The following table outlines the essential variables required to configure your Gatling load test:

| Variable        | Description                                                                                                  | Type   | Required |
| --------------- | ------------------------------------------------------------------------------------------------------------ | ------ | -------- |
| `simulation_id` | Unique identifier for your Gatling simulation (found in your Gatling Enterprise dashboard under Simulations) | String | Yes      |
| `token`         | Authentication token for Gatling Enterprise API access (generated in your Gatling Enterprise user settings)  | String | Yes      |
| `gatling_url`   | Base URL of your Gatling Enterprise instance (e.g., <https://your-gatling-instance.com>)                     | String | Yes      |

#### Interactive Setup Guide <a href="#interactive-setup-guide" id="interactive-setup-guide"></a>

Follow along with this interactive guide to learn how to set up Gatling load testing with chaos experiments:

{% embed url="<https://app.tango.us/app/embed/add05677-5274-4f26-b342-b1331298d059?skipCover=false&defaultListView=false&skipBranding=false&makeViewOnly=false&hideAuthorAndDetails=true>" %}
Run Chaos Experiment in Harness
{% endembed %}

### Setting up a Chaos Experiment with Gatling Load Test <a href="#setting-up-a-chaos-experiment-with-gatling-load-test" id="setting-up-a-chaos-experiment-with-gatling-load-test"></a>

This integration allows you to run chaos experiments while your system is under load, providing realistic testing conditions to validate your system's resilience.

#### 1. Set up your pipeline <a href="#id-1-set-up-your-pipeline" id="id-1-set-up-your-pipeline"></a>

Create a new pipeline or select an existing pipeline in your project.

#### 2. Create a new stage and add Gatling step <a href="#id-2-create-a-new-stage-and-add-gatling-step" id="id-2-create-a-new-stage-and-add-gatling-step"></a>

Add a new stage to your pipeline. For this example, we've chosen a custom stage.

Then click **Add Step** and choose **Use Template**.

Select the Gatling step template from the Harness template library.

Name your step template and click **Apply Changes**.

#### 3. Run the pipeline to test your Gatling load setup <a href="#id-3-run-the-pipeline-to-test-your-gatling-load-setup" id="id-3-run-the-pipeline-to-test-your-gatling-load-setup"></a>

After saving your changes in the pipeline, run the pipeline to execute the Gatling load test and verify that everything is set up correctly. Then, click **Run**.

Add your Gatling credentials in the next step and click **Run the Pipeline**.

If the build is successful, your Gatling load test setup is complete.

#### 4. Add chaos experiment to run in parallel <a href="#id-4-add-chaos-experiment-to-run-in-parallel" id="id-4-add-chaos-experiment-to-run-in-parallel"></a>

Go back to your pipeline and add a step parallel to your Gatling load test. This allows the chaos experiment to run simultaneously while your system is under load, creating realistic testing conditions.

Click **Add Step** parallel to the Gatling step.

Search for **Chaos** to add a new chaos experiment.

Name your experiment and choose a chaos experiment. You can select an existing experiment or create a new one.

Click **Apply Changes**.

Now, run the pipeline again to execute the Gatling load test and the chaos experiment in parallel. This simulates real-world conditions where your system faces both traffic load and infrastructure failures.

### How It Works <a href="#how-it-works" id="how-it-works"></a>

The Gatling integration in Harness Chaos Engineering follows this workflow:

#### 1. Prerequisites Validation <a href="#id-1-prerequisites-validation" id="id-1-prerequisites-validation"></a>

* Ensures `jq` is installed (installs automatically if missing)
* Validates that all required variables are provided

#### 2. Start Simulation <a href="#id-2-start-simulation" id="id-2-start-simulation"></a>

* Makes an API call to start your configured Gatling simulation
* Receives a unique run ID for tracking the execution

#### 3. Monitor Execution <a href="#id-3-monitor-execution" id="id-3-monitor-execution"></a>

* Continuously monitors the simulation status through these phases:
  * **Building**: Preparing the simulation environment
  * **Deploying**: Setting up load generators
  * **Deployed**: Ready to start traffic generation
  * **Injecting**: Actively running the load test
  * **Completed**: Load test finished

#### 4. Parallel Chaos Execution <a href="#id-4-parallel-chaos-execution" id="id-4-parallel-chaos-execution"></a>

* While the load test runs, chaos experiments execute simultaneously
* This combination tests your system's behavior under both normal load and failure conditions
* Results from both tests help validate your system's overall resilience

#### 5. Completion <a href="#id-5-completion" id="id-5-completion"></a>

* Both the load test and chaos experiment complete
* Combined results provide insights into system performance under realistic stress conditions