Hoja de Referencia de Pruebas de Rendimiento con Gatling¶

Instalación¶

Platform	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`

Comandos Básicos¶

Comando	Descripción
`gatling.sh`	Iniciar modo interactivo para seleccionar y ejecutar simulaciones
`gatling.sh -s com.example.MySimulation`	Ejecutar una clase de simulación específica
`gatling.bat -s com.example.MySimulation`	Ejecutar simulación en Windows
`gatling.sh --help`	Mostrar ayuda y opciones disponibles
`gatling.sh --version`	Mostrar versión de Gatling
`recorder.sh`	Iniciar la GUI de Gatling Recorder para grabar sesiones de navegador
`recorder.bat`	Iniciar Recorder en Windows
`gatling.sh -ro simulation-folder-name`	Generar informes a partir de registros de simulación existentes
`gatling.sh -s MySimulation -nr`	Ejecutar simulación sin generar informes
`gatling.sh -s MySimulation -rd "Test description"`	Ejecutar con descripción personalizada para informes
`mvn gatling:test`	Ejecutar todas las pruebas de Gatling usando Maven
`mvn gatling:test -Dgatling.simulationClass=MySimulation`	Ejecutar simulación específica con Maven
`gradle gatlingRun`	Ejecutar todas las pruebas de Gatling usando Gradle
`gradle gatlingRun-com.example.MySimulation`	Ejecutar simulación específica con Gradle
`ls user-files/simulations/`	Listar archivos de simulación disponibles

Comando	Descripción
`gatling.sh -s MySimulation -rf /custom/results`	Ejecutar con carpeta de resultados personalizada
`gatling.sh -s MySimulation -bf /custom/binaries`	Ejecutar con directorio de binarios personalizado
`gatling.sh -s MySimulation -rsf /custom/resources`	Ejecutar con directorio de recursos personalizado
`gatling.sh -s MySimulation -df /custom/data`	Ejecutar con directorio de datos personalizado
`gatling.sh -s MySimulation -cf /path/to/gatling.conf`	Ejecutar con archivo de configuración personalizado
`JAVA_OPTS="-Xms2G -Xmx4G" gatling.sh -s MySimulation`	Ejecutar con configuraciones personalizadas de memoria JVM
`gatling.sh -s MySimulation -D baseUrl=https://api.example.com`	Pasar propiedades del sistema a la simulación
`gatling.sh -s MySimulation -D users=100 -D duration=300`	Pasar múltiples propiedades del sistema
`mvn gatling:test -Dgatling.jvmArgs="-Xms2G -Xmx4G"`	Maven ejecutar con argumentos JVM personalizados
`docker run -v $(pwd)/user-files:/opt/gatling/user-files denvazh/gatling`	Ejecutar Gatling en contenedor Docker
`gatling.sh -s Sim1 && gatling.sh -s Sim2`	Ejecutar múltiples simulaciones secuencialmente
`for sim in Sim1 Sim2; do gatling.sh -s $sim -nr; done`	Ejecutar simulaciones por lotes sin informes
`mvn clean gatling:test -DbaseUrl=https://prod.example.com`	Maven run con URL específica del entorno
`gradle gatlingRun -Dusers=500 -Dduration=600`	Gradle run con parámetros dinámicos
`gatling.sh -s MySimulation 2>&1 \| tee test.log`	Ejecutar y capturar la salida en un archivo de registro

Archivo de Configuración Principal (`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
    }
  }
}

Configuración de Propiedades del Sistema¶

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

Configuración de 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>

Configuración de Gradle (`build.gradle`)¶

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

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

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

Casos de Uso Comunes¶

Caso de Uso 1: Prueba de Carga Básica de API¶

# 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 de Uso 2: Prueba de Estrés con Carga Gradual¶

# 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 de Uso 3: Integración 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 de Uso 4: Grabación de Sesión de Navegador¶

# 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 de Uso 5: Pruebas Basadas en Datos con Alimentadores¶

# 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

Mejores Prácticas¶

Usar Perfiles de Carga Apropiados: Comenzar con un aumento gradual (rampUsers) en lugar de atOnceUserspara simular patrones de tráfico realistas y evitar sobrecargar el sistema inmediatamente
Establecer Tiempos de Espera Realistas: Configurar tiempos de espera de conexión y solicitud basados en sus SLA (por ejemplo,requestTimeout = 30000durante 30 segundos) para detectar problemas de rendimiento temprano
Implementar Aserciones Adecuadas: Agregue aserciones para fallar automáticamente las pruebas cuando el rendimiento se degrada (global.responseTime.percentile3.lt(2000)asegura el percentil 95 bajo 2 segundos)
Usar Feeders para Datos Dinámicos: Aproveche CSV, JSON o feeders personalizados en lugar de codificar datos de prueba para simular el comportamiento real del usuario y evitar hits de caché
Asignar Memoria Suficiente: Para pruebas a gran escala, aumente el tamaño del heap de JVM (-Xms4G -Xmx8G) para prevenir errores de OutOfMemory y garantizar una ejecución fluida
Monitorear Recursos del Sistema: Observe el uso de CPU, memoria y red tanto en el generador de carga como en el sistema objetivo durante las pruebas para identificar cuellos de botella con precisión
Ejecutar Pruebas desde un Entorno Similar a Producción: Ejecute pruebas de carga desde infraestructura similar a producción (latencia de red, ancho de banda) para obtener resultados precisos
Control de Versiones de sus Simulaciones: Almacene el código de simulación en Git junto con el código de la aplicación para rastrear cambios y permitir la colaboración
Separar Preocupaciones con Escenarios: Divida pruebas complejas en múltiples escenarios y cadenas para mejorar la mantenibilidad y reutilización
Analizar Informes a Fondo: No solo revise los tiempos de respuesta, examine la distribución de solicitudes, tasas de error y percentiles de tiempo de respuesta para comprender completamente el panorama de rendimiento

Resolución de Problemas¶

Problema	Solución
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	Verifique la configuración del proxy del navegador (localhost:8000), asegúrese de que el grabador esté en funcionamiento, compruebe que ningún otro proxy/VPN esté interfiriendo
Reports not generating	Verificar espacio en disco, comprobar permisos de escritura en el directorio de resultados, asegurar que la prueba se completó con éxito sin fallos
High response times on load generator	El generador de carga está sobrecargado: reduzca usuarios concurrentes, aumente recursos o use pruebas distribuidas con múltiples generadores
"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	Verificar errores de sintaxis en código Scala, comprobar que todas las importaciones sean correctas, asegurar la compatibilidad de la versión de 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	Caliente primero el sistema objetivo, asegúrese de un entorno de prueba consistente, verifique factores externos (otro tráfico, trabajos programados)
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
## Referencia Rápida: Perfiles de Inyección de Carga

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

Ubicaciones de Archivos Útiles¶

Path	Descripción
`user-files/simulations/`	Archivos Scala de simulación
`user-files/resources/`	Archivos de datos de alimentación (CSV, JSON)
`user-files/bodies/`	Plantillas de cuerpo de solicitud
`results/`	Informes HTML generados
`conf/gatling.conf`	Archivo de configuración principal
`conf/logback.xml`	Configuración de logging
`target/gatling/`	Salida de compilación y informes de Maven

Hoja de Referencia de Pruebas de Rendimiento con Gatling¶

Instalación¶

Comandos Básicos¶

Archivo de Configuración Principal (gatling.conf)¶

Configuración de Propiedades del Sistema¶

Configuración de Maven (pom.xml)¶

Configuración de Gradle (build.gradle)¶

Casos de Uso Comunes¶

Caso de Uso 1: Prueba de Carga Básica de API¶

Caso de Uso 2: Prueba de Estrés con Carga Gradual¶

Caso de Uso 3: Integración CI/CD con Maven¶

Caso de Uso 4: Grabación de Sesión de Navegador¶

Caso de Uso 5: Pruebas Basadas en Datos con Alimentadores¶

Mejores Prácticas¶

Resolución de Problemas¶

Ubicaciones de Archivos Útiles¶

Archivo de Configuración Principal (`gatling.conf`)¶

Configuración de Maven (`pom.xml`)¶

Configuración de Gradle (`build.gradle`)¶