Gatling tests are designed to be run as part of your CI/CD pipeline, and Jenkins is a popular choice for orchestrating these pipelines. Integrating Gatling into Jenkins allows you to automate performance testing, catch regressions early, and ensure your application scales under load.
Here’s how you can set up Gatling within a Jenkins pipeline, focusing on a declarative pipeline for clarity.
Setting Up Gatling in Jenkins
First, you need a Jenkins agent (or a master if you’re running directly on it, though not recommended for load generation) with Java installed, as Gatling is JVM-based. You’ll also need Git to pull your Gatling project.
1. Gatling Project Structure
Your Gatling project should be structured like a standard Scala project, typically using sbt or Maven for building.
your-gatling-project/
├── gatling-charts-highcharts-bundle/ <-- Gatling bundle if not using sbt/maven plugin
├── src/
│ └── main/
│ └── scala/
│ └── simulations/
│ └── YourSimulation.scala
├── build.sbt <-- If using sbt
├── pom.xml <-- If using Maven
└── Jenkinsfile
2. The Jenkinsfile
This Jenkinsfile will define your pipeline. We’ll use a declarative pipeline.
pipeline {
agent any // Or specify a label for an agent with Java and Git
stages {
stage('Checkout') {
steps {
// Checkout your Gatling project from your SCM
git 'https://github.com/your-username/your-gatling-project.git'
}
}
stage('Build & Test') {
steps {
script {
// Define the path to your Gatling simulation file
def gatlingSimulation = "user-files/simulations/com/example/MySimulation.scala" // Adjust this path
// --- Option 1: Using sbt ---
// If your Gatling project is configured with sbt
// Ensure sbt is available on your Jenkins agent
sh './sbt gatling:test' // 'gatling:test' is a common sbt task for Gatling
// --- Option 2: Using Maven ---
// If your Gatling project is configured with Maven
// Ensure Maven is available on your Jenkins agent
// sh 'mvn gatling:test' // 'gatling:test' is a common Maven plugin goal
// --- Option 3: Using Gatling Bundle (less common in pipelines) ---
// If you're not using sbt/Maven, you might use the bundle directly.
// This requires downloading the bundle or having it pre-installed.
// sh './gatling-charts-highcharts-bundle/bin/gatling.sh -s com.example.MySimulation'
}
}
}
stage('Publish Reports') {
steps {
script {
// Gatling generates reports in the 'target/gatling' directory (for sbt/maven)
// or in the 'results' directory within the bundle's distribution.
// You need to archive these reports so they are accessible from Jenkins.
// Adjust the path based on your build tool and Gatling configuration
def reportDir = 'target/gatling/*' // For sbt/maven
// def reportDir = 'results/*' // For Gatling Bundle
archiveArtifacts artifacts: "${reportDir}", allowEmptyArchive: true
}
}
}
}
post {
always {
// Clean up workspace if needed
// cleanWs()
}
success {
echo 'Gatling performance tests completed successfully!'
}
failure {
echo 'Gatling performance tests failed!'
}
}
}
Explanation
agent any: This tells Jenkins to run the pipeline on any available agent. You might want to specify a label (e.g.,agent { label 'performance-agent' }) if you have dedicated agents with specific tools installed.stage('Checkout'): This stage clones your Gatling project from your version control system.stage('Build & Test'): This is where the magic happens.gatlingSimulation: Crucially, you need to tell Gatling which simulation to run. This path is relative to your project’s root directory../sbt gatling:test/mvn gatling:test: These commands invoke your build tool to run the Gatling tests. Thegatling:testtask (or similar) is provided by Gatling plugins for sbt and Maven, which handle compiling your simulations and executing them.- Gatling Bundle: If you’re not using build tool plugins, you’d typically download the Gatling bundle and execute
gatling.shdirectly, specifying your simulation class. This is less common in automated pipelines as build tools offer better dependency management.
stage('Publish Reports'): After the tests run, Gatling generates detailed HTML reports. ThearchiveArtifactsstep tells Jenkins to save these reports, making them viewable directly from the build’s page in Jenkins.- The
reportDirvariable needs to match where Gatling outputs its results. For sbt/Maven with standard configurations, it’s oftentarget/gatling/. If you’re using the Gatling bundle, it might beresults/. allowEmptyArchive: trueis useful if, for instance, the tests fail very early and no reports are generated.
- The
postblock: This defines actions to take after the pipeline completes, regardless of success or failure (like cleanup) or specifically on success/failure.
Running the Pipeline
- Create a new "Pipeline" job in Jenkins.
- In the "Pipeline" section, select "Pipeline script from SCM".
- Choose your SCM (e.g., Git).
- Enter your repository URL and the branch to build.
- Set the "Script Path" to
Jenkinsfile(or whatever you named your pipeline script). - Save and click "Build Now".
Jenkins will then execute the stages defined in your Jenkinsfile. After a successful run, you’ll see a "Gatling" link on the build page, which leads to the generated performance reports.
Considerations for Production Pipelines
- Dedicated Agents: For serious performance testing, you should run Gatling simulations on dedicated Jenkins agents that are not the Jenkins master itself. Load generation can consume significant resources.
- Resource Management: Ensure your Jenkins agents have sufficient CPU, memory, and network bandwidth to simulate the desired load.
- Configuration: Externalize Gatling configurations (e.g., simulation class, number of users, ramp-up, duration) using Jenkins environment variables or a separate configuration file that your pipeline can read.
- Thresholds and Assertions: Gatling allows you to define assertions (e.g., "95% of requests must be below 1000ms"). You can configure your pipeline to fail if these assertions are not met, integrating performance testing as a gatekeeper for deployments.
- Distributed Testing: For very high loads, consider Gatling’s distributed mode, where multiple machines act as load generators. Integrating this into Jenkins requires more complex orchestration, potentially involving Jenkins agents coordinating with each other or using external tools.
This setup provides a solid foundation for automating your Gatling performance tests within your CI/CD workflow, enabling you to maintain application performance as you iterate.