Gatling Performance Testing Cheatsheet¶

Installation¶

Plattform	Befehl
Ubuntu/Debian	`wget https://repo1.maven.org/maven2/io/gatling/highcharts/gatling-charts-highcharts-bundle/3.10.3/gatling-charts-highcharts-bundle-3.10.3-bundle.zip && unzip gatling-charts-highcharts-bundle-3.10.3-bundle.zip && sudo mv gatling-charts-highcharts-bundle-3.10.3 /opt/gatling`
macOS (Homebrew)	`brew install gatling`
Windows (Manual)	Download from Maven Central, extract to `C:\gatling`, add `bin` directory to PATH
SDKMAN (Linux/Mac)	`sdk install gatling`
Docker	`docker pull denvazh/gatling:latest`
Maven Plugin	Add `io.gatling:gatling-maven-plugin:4.6.0` to `pom.xml`
Gradle Plugin	Add `id 'io.gatling.gradle' version '3.10.3'` to `build.gradle`
`# Install Java 11+ (required) sudo apt install openjdk-11-jdk -y # Ubuntu/Debian brew install openjdk@11 # macOS # Verify Java installation java -version`

Grundlegende Befehle¶

Befehl	Beschreibung
`gatling.sh`	Starten Sie den interaktiven Modus, um Simulationen auszuwählen und auszuführen
`gatling.sh -s com.example.MySimulation`	Eine bestimmte Simulationsklasse ausführen
`gatling.bat -s com.example.MySimulation`	Simulation auf Windows ausführen
`gatling.sh --help`	Hilfe und verfügbare Optionen anzeigen
`gatling.sh --version`	Gatling-Version anzeigen
`recorder.sh`	Starten Sie die Gatling Recorder GUI zum Aufzeichnen von Browser-Sitzungen
`recorder.bat`	Launch Recorder auf Windows
`gatling.sh -ro simulation-folder-name`	Berichte aus vorhandenen Simulationslogs generieren
`gatling.sh -s MySimulation -nr`	Simulation ohne Generierung von Berichten ausführen
`gatling.sh -s MySimulation -rd "Test description"`	Mit benutzerdefinierter Beschreibung für Berichte ausführen
`mvn gatling:test`	Führen Sie alle Gatling-Tests mit Maven aus
`mvn gatling:test -Dgatling.simulationClass=MySimulation`	Führen Sie eine spezifische Simulation mit Maven aus
`gradle gatlingRun`	Führen Sie alle Gatling-Tests mit Gradle aus
`gradle gatlingRun-com.example.MySimulation`	Spezifische Simulation mit Gradle ausführen
`ls user-files/simulations/`	Verfügbare Simulationsdateien auflisten
## Erweiterte Nutzung

Befehl	Beschreibung
`gatling.sh -s MySimulation -rf /custom/results`	Mit benutzerdefiniertem Ergebnisordner ausführen
`gatling.sh -s MySimulation -bf /custom/binaries`	Mit benutzerdefiniertem Binärverzeichnis ausführen
`gatling.sh -s MySimulation -rsf /custom/resources`	Mit benutzerdefiniertem Ressourcenverzeichnis ausführen
`gatling.sh -s MySimulation -df /custom/data`	Mit benutzerdefiniertem Datenverzeichnis ausführen
`gatling.sh -s MySimulation -cf /path/to/gatling.conf`	Mit benutzerdefinierter Konfigurationsdatei ausführen
`JAVA_OPTS="-Xms2G -Xmx4G" gatling.sh -s MySimulation`	Mit benutzerdefinierten JVM-Speichereinstellungen ausführen
`gatling.sh -s MySimulation -D baseUrl=https://api.example.com`	Systemeigenschaften an Simulation übergeben
`gatling.sh -s MySimulation -D users=100 -D duration=300`	Mehrere Systemeigenschaften übergeben
`mvn gatling:test -Dgatling.jvmArgs="-Xms2G -Xmx4G"`	Maven-Ausführung mit benutzerdefinierten JVM-Argumenten
`docker run -v $(pwd)/user-files:/opt/gatling/user-files denvazh/gatling`	Gatling in Docker-Container ausführen
`gatling.sh -s Sim1 && gatling.sh -s Sim2`	Mehrere Simulationen sequenziell ausführen
`for sim in Sim1 Sim2; do gatling.sh -s $sim -nr; done`	Stapellauf-Simulationen ohne Berichte durchführen
`mvn clean gatling:test -DbaseUrl=https://prod.example.com`	Maven-Ausführung mit umgebungsspezifischer URL
`gradle gatlingRun -Dusers=500 -Dduration=600`	Gradle-Ausführung mit dynamischen Parametern
`gatling.sh -s MySimulation 2>&1 \| tee test.log`	Ausführen und Ausgabe in Logdatei erfassen
## Konfiguration

Hauptkonfigurationsdatei (`gatling.conf`)¶

gatling {
  core {
    # Output directory for results
    outputDirectoryBaseName = "simulation"

    # Encoding for files
    encoding = "utf-8"

    # Timeout for requests
    timeOut = 60000

    # Directory for simulation classes
    simulationClass = ""
  }

  http {
    # Enable/disable SSL/TLS
    enableGA = false

    # Connection timeout
    connectTimeout = 10000

    # Request timeout
    requestTimeout = 60000

    # Max connections per host
    maxConnectionsPerHost = 6
  }

  data {
    # Directory for feeder files
    file {
      bufferSize = 256
    }
  }

  charting {
    # Indicators percentiles
    indicators {
      lowerBound = 800
      higherBound = 1200
      percentile1 = 50
      percentile2 = 75
      percentile3 = 95
      percentile4 = 99
    }
  }
}

Systemeinstellungen Konfiguration¶

# Set via command line
gatling.sh -s MySimulation \
  -Dgatling.core.outputDirectoryBaseName=custom-output \
  -Dgatling.http.requestTimeout=30000 \
  -Dgatling.charting.indicators.percentile1=90

Maven Konfiguration (`pom.xml`)¶

<plugin>
    <groupId>io.gatling</groupId>
    <artifactId>gatling-maven-plugin</artifactId>
    <version>4.6.0</version>
    <configuration>
        <simulationClass>com.example.MySimulation</simulationClass>
        <jvmArgs>
            <jvmArg>-Xms2G</jvmArg>
            <jvmArg>-Xmx4G</jvmArg>
            <jvmArg>-XX:+UseG1GC</jvmArg>
        </jvmArgs>
        <systemProperties>
            <baseUrl>https://api.example.com</baseUrl>
            <users>100</users>
        </systemProperties>
    </configuration>
</plugin>

Gradle Konfiguration (`build.gradle`)¶

gatling {
    simulations = {
        include 'com/example/**/*Simulation.scala'
    }

    jvmArgs = ['-Xms2G', '-Xmx4G', '-XX:+UseG1GC']

    systemProperties = [
        'baseUrl': 'https://api.example.com',
        'users': '100'
    ]
}

Häufige Anwendungsfälle¶

Anwendungsfall 1: Grundlegender API-Lasttest¶

# Create simulation file
cat > user-files/simulations/BasicApiTest.scala << 'EOF'
import io.gatling.core.Predef._
import io.gatling.http.Predef._
import scala.concurrent.duration._

class BasicApiTest extends Simulation {
  val httpProtocol = http
    .baseUrl("https://api.example.com")
    .acceptHeader("application/json")
    .contentTypeHeader("application/json")

  val scn = scenario("Basic API Test")
    .exec(http("Get Users")
      .get("/users")
      .check(status.is(200)))
    .pause(1)

  setUp(
    scn.inject(
      rampUsers(100) during (60 seconds)
    )
  ).protocols(httpProtocol)
}
EOF

# Run the test
gatling.sh -s BasicApiTest

# View results
open results/basicapitest-*/index.html  # macOS
xdg-open results/basicapitest-*/index.html  # Linux

Anwendungsfall 2: Stresstest mit gradueller Last¶

# Create stress test simulation
cat > user-files/simulations/StressTest.scala << 'EOF'
import io.gatling.core.Predef._
import io.gatling.http.Predef._
import scala.concurrent.duration._

class StressTest extends Simulation {
  val httpProtocol = http.baseUrl("https://api.example.com")

  val scn = scenario("Stress Test")
    .exec(http("Heavy Endpoint")
      .post("/api/process")
      .body(StringBody("""{"data": "test"}"""))
      .check(status.is(200)))

  setUp(
    scn.inject(
      nothingFor(5 seconds),
      atOnceUsers(10),
      rampUsers(50) during (30 seconds),
      constantUsersPerSec(20) during (60 seconds),
      rampUsersPerSec(20) to 50 during (60 seconds)
    )
  ).protocols(httpProtocol)
    .maxDuration(5 minutes)
    .assertions(
      global.responseTime.max.lt(5000),
      global.successfulRequests.percent.gt(95)
    )
}
EOF

# Run with custom memory settings
JAVA_OPTS="-Xms4G -Xmx8G" gatling.sh -s StressTest

Anwendungsfall 3: CI/CD-Integration mit Maven¶

# Add to Jenkins/GitLab CI pipeline
mvn clean gatling:test \
  -Dgatling.simulationClass=com.example.PerformanceTest \
  -DbaseUrl=${TEST_URL} \
  -Dusers=${CONCURRENT_USERS} \
  -Dduration=${TEST_DURATION}

# Check exit code for pass/fail
if [ $? -eq 0 ]; then
  echo "Performance test passed"
else
  echo "Performance test failed"
  exit 1
fi

# Archive results
tar -czf gatling-results.tar.gz target/gatling/

Anwendungsfall 4: Browser-Sitzung aufzeichnen¶

# Start recorder
recorder.sh

# Configure in GUI:
# - Listening Port: 8000
# - Output folder: user-files/simulations
# - Class name: RecordedSimulation

# Configure browser proxy to localhost:8000
# Perform actions in browser
# Stop recording

# Run recorded simulation
gatling.sh -s RecordedSimulation

Anwendungsfall 5: Datengesteuertes Testen mit Feedern¶

# Create CSV data file
cat > user-files/resources/users.csv << 'EOF'
username,password
user1,pass1
user2,pass2
user3,pass3
EOF

# Create simulation with feeder
cat > user-files/simulations/DataDrivenTest.scala << 'EOF'
import io.gatling.core.Predef._
import io.gatling.http.Predef._

class DataDrivenTest extends Simulation {
  val httpProtocol = http.baseUrl("https://api.example.com")

  val feeder = csv("users.csv").circular

  val scn = scenario("Login Test")
    .feed(feeder)
    .exec(http("Login")
      .post("/login")
      .body(StringBody("""{"username":"${username}","password":"${password}"}"""))
      .check(status.is(200)))

  setUp(scn.inject(atOnceUsers(10))).protocols(httpProtocol)
}
EOF

# Run test
gatling.sh -s DataDrivenTest

Best Practices¶

Geeignete Lastprofile verwenden: Mit gradueller Steigerung (rampUsers) beginnen, anstatt atOnceUsers, um realistische Verkehrsmuster zu simulieren und das System nicht sofort zu überlasten
Realistische Timeouts festlegen: Verbindungs- und Anfrage-Timeouts basierend auf Ihren SLAs konfigurieren (z.B.

Would you like me to fill in the remaining placeholders with specific translations?requestTimeout = 30000für 30 Sekunden), um Leistungsprobleme frühzeitig zu erkennen

Implementieren Sie Korrekte Assertions: Fügen Sie Assertions hinzu, um Tests automatisch fehlschlagen zu lassen, wenn die Leistung nachlässt ( global.responseTime.percentile3.lt(2000)stellt sicher, dass das 95. Perzentil unter 2 Sekunden liegt)
Verwenden Sie Feeder für dynamische Daten: Nutzen Sie CSV, JSON oder benutzerdefinierte Feeder anstelle von hartcodierten Testdaten, um das Verhalten echter Benutzer zu simulieren und Cache-Treffer zu vermeiden
Weisen Sie ausreichend Speicher zu: Erhöhen Sie bei groß angelegten Tests die JVM-Heap-Größe ( -Xms4G -Xmx8G), um OutOfMemory-Fehler zu verhindern und eine reibungslose Ausführung zu gewährleisten
Überwachen Sie Systemressourcen: Beobachten Sie CPU-, Speicher- und Netzwerkauslastung sowohl auf dem Lastgenerator als auch auf dem Zielsystem während der Tests, um Engpässe genau zu identifizieren
Führen Sie Tests aus einer produktionsähnlichen Umgebung aus: Führen Sie Lasttests aus einer Infrastruktur aus, die der Produktionsumgebung ähnelt (Netzwerklatenz, Bandbreite), um genaue Ergebnisse zu erhalten
Versionskontrolle Ihrer Simulationen: Speichern Sie Simulationscode in Git neben dem Anwendungscode, um Änderungen zu verfolgen und Zusammenarbeit zu ermöglichen
Trennen Sie Anliegen mit Szenarien: Unterteilen Sie komplexe Tests in mehrere Szenarien und Ketten für bessere Wartbarkeit und Wiederverwendbarkeit
Analysieren Sie Berichte gründlich: Überprüfen Sie nicht nur Antwortzeiten - untersuchen Sie Anforderungsverteilung, Fehlerraten und Antworzeitperzentile, um das vollständige Leistungsbild zu verstehen

Fehlersuche¶

Problem	Lösung
OutOfMemoryError during test execution	Increase JVM heap size: `JAVA_OPTS="-Xms4G -Xmx8G" gatling.sh -s MySimulation` or reduce concurrent users
"Simulation class not found" error	Ensure simulation is in `user-files/simulations/` and class name matches file name. Recompile if needed: `mvn clean compile`
Connection timeout errors	Increase timeout in `gatling.conf`: `gatling.http.connectTimeout = 30000` or check network connectivity to target system
SSL/TLS certificate errors	Disable certificate validation in simulation: `.disableCaching.disableWarmUp.shareConnections.silentResources` or add certificate to Java keystore
Recorder proxy not working	Überprüfen Sie die Browser-Proxy-Einstellungen (localhost:8000), stellen Sie sicher, dass der Recorder läuft, und verifizieren Sie, dass kein anderer Proxy/VPN interferiert
Reports not generating	Überprüfen Sie den Festplattenspeicher, verifizieren Sie Schreibberechtigungen im Ergebnisverzeichnis, stellen Sie sicher, dass der Test erfolgreich ohne Abstürze abgeschlossen wurde
High response times on load generator	Load Generator ist überlastet—reduzieren Sie gleichzeitige Benutzer, erhöhen Sie Ressourcen oder verwenden Sie verteiltes Testen mit mehreren Generatoren
"Too many open files" error (Linux)	Increase file descriptor limit: `ulimit -n 65536` before running Gatling, or add to `/etc/security/limits.conf`
Simulations compile but don't run	Überprüfen Sie Syntaxfehler im Scala-Code, verifizieren Sie alle Importe, stellen Sie die Kompatibilität der Gatling-Version sicher
Maven/Gradle plugin not found	Update plugin version in `pom.xml`/`build.gradle`, run `mvn clean install` or `gradle clean build`, check Maven Central connectivity
Inconsistent results between runs	Zielsystem zuerst aufwärmen, konsistente Testumgebung sicherstellen, externe Faktoren prüfen (anderer Verkehr, geplante Jobs)
WebSocket connection failures	Verify WebSocket protocol in simulation: `.ws("Connect").connect("/socket")`, check target server WebSocket support
Feeder file not found	Place CSV/JSON files in `user-files/resources/`, use relative path: `csv("data.csv")` not absolute path
Docker container exits immediately	Mount volumes correctly: `-v $(pwd)/user-files:/opt/gatling/user-files`, ensure simulation files exist in mounted directory
## Schnellreferenz: Last-Injektionsprofile

// Immediate load
atOnceUsers(100)

// Gradual ramp-up
rampUsers(100) during (60 seconds)

// Constant rate
constantUsersPerSec(20) during (5 minutes)

// Gradual rate increase
rampUsersPerSec(10) to 50 during (2 minutes)

// Staircase pattern
incrementUsersPerSec(5)
  .times(5)
  .eachLevelLasting(30 seconds)
  .separatedByRampsLasting(10 seconds)
  .startingFrom(10)

// Complex scenario
nothingFor(5 seconds),
atOnceUsers(10),
rampUsers(50) during (30 seconds),
constantUsersPerSec(20) during (60 seconds)

Nützliche Dateispeicherorte¶

Pfad	Beschreibung
`user-files/simulations/`	Simulation Scala Dateien
`user-files/resources/`	Feeder-Datendateien (CSV, JSON)
`user-files/bodies/`	Anforderungskörper-Vorlagen
`results/`	Generierte HTML-Berichte
`conf/gatling.conf`	Hauptkonfigurationsdatei
`conf/logback.xml`	Logging-Konfiguration
`target/gatling/`	Maven Build-Ausgabe und Berichte

Gatling Performance Testing Cheatsheet¶

Installation¶

Grundlegende Befehle¶

Hauptkonfigurationsdatei (gatling.conf)¶

Systemeinstellungen Konfiguration¶

Maven Konfiguration (pom.xml)¶

Gradle Konfiguration (build.gradle)¶

Häufige Anwendungsfälle¶

Anwendungsfall 1: Grundlegender API-Lasttest¶

Anwendungsfall 2: Stresstest mit gradueller Last¶

Anwendungsfall 3: CI/CD-Integration mit Maven¶

Anwendungsfall 4: Browser-Sitzung aufzeichnen¶

Anwendungsfall 5: Datengesteuertes Testen mit Feedern¶

Best Practices¶

Fehlersuche¶

Nützliche Dateispeicherorte¶

Hauptkonfigurationsdatei (`gatling.conf`)¶

Maven Konfiguration (`pom.xml`)¶

Gradle Konfiguration (`build.gradle`)¶