Gatling Performance Testing Cheatsheet

Gatling Performance Testing Cheatsheet

Installazione

Piattaforma	Comando
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

Comandi di Base

Comando	Descrizione
gatling.sh	Avvia la modalità interattiva per selezionare ed eseguire simulazioni
gatling.sh -s com.example.MySimulation	Esegui una classe di simulazione specifica
gatling.bat -s com.example.MySimulation	Esegui simulazione su Windows
gatling.sh --help	Mostra help e opzioni disponibili
gatling.sh --version	Mostra versione Gatling
recorder.sh	Avvia l’interfaccia grafica di Gatling Recorder per registrare sessioni del browser
recorder.bat	Avvia Recorder su Windows
gatling.sh -ro simulation-folder-name	Genera report dai log di simulazione esistenti
gatling.sh -s MySimulation -nr	Esegui simulazione senza generare report
gatling.sh -s MySimulation -rd "Test description"	Esegui con descrizione personalizzata per report
mvn gatling:test	Esegui tutti i test Gatling utilizzando Maven
mvn gatling:test -Dgatling.simulationClass=MySimulation	Esegui simulazione specifica con Maven
gradle gatlingRun	Esegui tutti i test Gatling utilizzando Gradle
gradle gatlingRun-com.example.MySimulation	Esegui simulazione specifica con Gradle
ls user-files/simulations/	Elenca i file di simulazione disponibili

Utilizzo Avanzato

Comando	Descrizione
gatling.sh -s MySimulation -rf /custom/results	Esegui con cartella dei risultati personalizzata
gatling.sh -s MySimulation -bf /custom/binaries	Esegui con directory di binari personalizzata
gatling.sh -s MySimulation -rsf /custom/resources	Esegui con directory delle risorse personalizzata
gatling.sh -s MySimulation -df /custom/data	Esegui con directory dei dati personalizzata
gatling.sh -s MySimulation -cf /path/to/gatling.conf	Esegui con file di configurazione personalizzato
JAVA_OPTS="-Xms2G -Xmx4G" gatling.sh -s MySimulation	Esegui con impostazioni personalizzate della memoria JVM
gatling.sh -s MySimulation -D baseUrl=https://api.example.com	Passa le proprietà di sistema alla simulazione
gatling.sh -s MySimulation -D users=100 -D duration=300	Passa più proprietà di sistema
mvn gatling:test -Dgatling.jvmArgs="-Xms2G -Xmx4G"	Esecuzione di Maven con argomenti JVM personalizzati
docker run -v $(pwd)/user-files:/opt/gatling/user-files denvazh/gatling	Esegui Gatling in un container Docker
gatling.sh -s Sim1 && gatling.sh -s Sim2	Esegui più simulazioni in sequenza
for sim in Sim1 Sim2; do gatling.sh -s $sim -nr; done	Esegui simulazioni batch senza report
mvn clean gatling:test -DbaseUrl=https://prod.example.com	Maven run con URL specifico per ambiente
gradle gatlingRun -Dusers=500 -Dduration=600	Esegui Gradle con parametri dinamici
`gatling.sh -s MySimulation 2>&1	tee test.log`

Configurazione

File di Configurazione Principale (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
    }
  }
}

Configurazione delle Proprietà di Sistema

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

Configurazione Maven (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>

Configurazione Gradle (build.gradle)

gatling {
    simulations = {
        include 'com/example/**/*Simulation.scala'
    }
    
    jvmArgs = ['-Xms2G', '-Xmx4G', '-XX:+UseG1GC']
    
    systemProperties = [
        'baseUrl': 'https://api.example.com',
        'users': '100'
    ]
}

Casi d’Uso Comuni

Caso d’Uso 1: Test di Carico API di Base

# 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

Caso d’Uso 2: Test di Stress con Carico Graduale

# 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

Caso d’Uso 3: Integrazione CI/CD con 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/

Caso d’Uso 4: Registrazione Sessione Browser

# 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

Caso d’Uso 5: Test Guidati dai Dati con Feeders

# 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

Migliori Pratiche

• Utilizzare Profili di Carico Appropriati: Iniziare con un aumento graduale (rampUsers) invece di atOnceUsersper simulare pattern di traffico realistici ed evitare di sovraccaricare immediatamente il sistema

• Impostare Timeout Realistici: Configurare timeout di connessione e richiesta in base ai propri SLA (ad esempio,

Note: Some placeholders (numbers 4, 8, 9, 11, 13, 14-18) were left blank as no specific text was provided to translate.requestTimeout = 30000per 30 secondi) per identificare precocemente i problemi di prestazioni

• Implementare Asserzioni Appropriate: Aggiungere asserzioni per far fallire automaticamente i test quando le prestazioni si degradano (global.responseTime.percentile3.lt(2000)garantisce il 95° percentile sotto i 2 secondi)

• Utilizzare Feeder per Dati Dinamici: Sfruttare CSV, JSON o feeder personalizzati invece di codificare staticamente i dati di test per simulare il comportamento di utenti reali ed evitare hit della cache

• Allocare Memoria Sufficiente: Per test su larga scala, aumentare le dimensioni dell’heap JVM (-Xms4G -Xmx8G) per prevenire errori OutOfMemory e garantire un’esecuzione fluida

• Monitorare le Risorse di Sistema: Osservare l’utilizzo di CPU, memoria e rete sia sul generatore di carico che sul sistema di destinazione durante i test per identificare accuratamente i colli di bottiglia

• Eseguire Test da un Ambiente Simile alla Produzione: Eseguire test di carico da un’infrastruttura simile alla produzione (latenza di rete, larghezza di banda) per risultati accurati

• Controllare le Versioni delle Simulazioni: Archiviare il codice di simulazione in Git accanto al codice dell’applicazione per tracciare le modifiche e consentire la collaborazione

• Separare le Preoccupazioni con gli Scenari: Suddividere test complessi in più scenari e catene per una migliore manutenibilità e riutilizzabilità

• Analizzare Accuratamente i Report: Non limitarsi a controllare i tempi di risposta—esaminare la distribuzione delle richieste, i tassi di errore e i percentili dei tempi di risposta per comprendere l’intero quadro delle prestazioni

Risoluzione dei Problemi

Problema	Soluzione
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	Controllare le impostazioni del proxy del browser (localhost:8000), assicurarsi che il recorder sia in esecuzione, verificare che nessun altro proxy/VPN stia interferendo
Reports not generating	Controllare lo spazio su disco, verificare i permessi di scrittura nella directory dei risultati, assicurarsi che il test sia stato completato con successo senza arresti anomali
High response times on load generator	Il load generator è sovraccarico—riduci gli utenti concorrenti, aumenta le risorse, o utilizza test distribuiti con più generatori
”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	Verifica errori di sintassi nel codice Scala, controlla che tutti gli import siano corretti, assicurati della compatibilità della versione di Gatling
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	Riscaldare prima il sistema target, assicurare un ambiente di test coerente, verificare fattori esterni (altro traffico, job pianificati)
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

Riferimento Rapido: Profili di Iniezione del Carico

// 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)

Posizioni File Utili

Percorso	Descrizione
user-files/simulations/	File di simulazione Scala
user-files/resources/	File di dati Feeder (CSV, JSON)
user-files/bodies/	Modelli di corpo della richiesta
results/	Report HTML generati
conf/gatling.conf	File di configurazione principale
conf/logback.xml	Configurazione di logging
target/gatling/	Output di build e report di Maven