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`	Esegui e cattura l'output nel file di 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