Gatling MQTT Demo Scala / Maven

¿Por qué hacer load testing sobre MQTT?

MQTT (Message Queuing Telemetry Transport) es el protocolo ligero de mensajería más usado en IoT, telemetría industrial, vehículos conectados y sistemas de notificaciones en tiempo real. A diferencia de REST, MQTT opera sobre un modelo de publicación/suscripción donde los clientes se conectan a un broker que enruta mensajes por tópicos.

Testear un broker MQTT bajo carga es diferente a testear una API REST: los usuarios virtuales mantienen conexiones persistentes, se suscriben a tópicos, publican mensajes y esperan respuestas correlacionadas — todo de forma concurrente. Sin una herramienta específica, este patrón es difícil de simular con fidelidad. Gatling tiene una extensión oficial para MQTT que este proyecto demuestra de forma completa y ejecutable.

Stack técnico

Estructura del proyecto

Instalación y setup

Tres pasos. No requiere instalar Gatling manualmente — Maven lo descarga como dependencia.

1 — Clonar el repositorio

2 — Compilar (descarga dependencias automáticamente)

3 — Verificar versiones

En Windows usa mvnw.cmd en lugar de ./mvnw

La simulación explicada

El archivo principal MqttDemoSimulation.scala en menos de 30 líneas cubre el flujo completo de un cliente MQTT real.

package io.gatling.mqtt.demo

import java.util.UUID
import scala.concurrent.duration._
import io.gatling.core.Predef._
import io.gatling.mqtt.Predef._

class MqttDemoSimulation extends Simulation {

  // 1. Protocolo: broker HiveMQ público con TLS
  val baseMqttProtocol = mqtt
    .broker("broker.hivemq.com", 8883)
    .useTls(true)
    .correlateBy(jmesPath("id"))   // correlación por campo "id"

  // 2. Tópico único por ejecución (evita colisiones entre tests)
  val topic = s"gatling-mqtt-demo/${UUID.randomUUID()}"

  // 3. Escenario: cada VU hace connect → subscribe → publish → check
  val scn = scenario("Publisher")
    .exec(session => session.set("id", UUID.randomUUID()))
    .exec(mqtt("Connecting").connect)
    .exec(mqtt("Subscribing").subscribe(topic))
    .exec(
      mqtt("Publishing")
        .publish(topic)
        .message(StringBody("""{"id":"#{id}","message":"Hello from #{id}"}"""))
        .await(1.second)
        .check(jmesPath("message").is("Hello from #{id}"))
    )

  // 4. Inyección: 5 usuarios simultáneos
  setUp(
    scn.inject(atOnceUsers(5))
  ).protocols(baseMqttProtocol)
}

Las 4 fases del flujo por usuario virtual

Ejecutar el test

Dos formas equivalentes. Se recomienda el Maven Wrapper para garantizar la versión correcta sin instalación adicional.

Con Maven Wrapper (recomendado)

Con Maven instalado globalmente

Personalizar la carga

Modifica el bloque setUp en la simulación para ajustar el perfil de carga a tu escenario.

setUp(scn.inject(atOnceUsers(5))).protocols(baseMqttProtocol)

setUp(scn.inject(rampUsers(100).during(60.seconds))).protocols(baseMqttProtocol)

setUp(scn.inject(constantUsersPerSec(10).during(5.minutes))).protocols(baseMqttProtocol)

Reportes HTML

Al finalizar cada ejecución, Gatling genera un reporte HTML completo automáticamente en target/gatling/.

Adaptar a tu propio broker

El proyecto usa HiveMQ público por defecto — ideal para demos y aprendizaje. Para usar tu propio broker, modifica el bloque de protocolo:

val baseMqttProtocol = mqtt
  .broker("tu-broker.example.com", 1883)   // puerto 1883 sin TLS
  .useTls(false)                            // o true + puerto 8883
  .credentials("user", "password")       // si requiere auth
  .correlateBy(jmesPath("id"))