xk6-mqtt

MQTT protocol support for k6

⚠️ Warning

This is an experimental extension for k6. It is not officially supported yet. We are actively working on it to make it officially supported in the future.

xk6-mqtt is a k6 extension that adds first-class support for the MQTT protocol to your load testing and performance scripts. With this extension, you can connect to MQTT brokers, publish and subscribe to topics, and interact with MQTT systems directly from your k6 tests.

The API is intentionally designed to feel familiar to users of MQTT.js, the popular JavaScript MQTT client. This means you can leverage event-driven programming, both synchronous and asynchronous operations, and migrate existing MQTT.js-based test logic with minimal changes. The extension aims to provide a modern, ergonomic developer experience for MQTT load testing in JavaScript.

Example: Hello World

Comparing HTTP-based tests to MQTT ones, you’ll find differences in both structure and inner workings. The primary difference is that instead of continuously looping the main function (export default function() { ... }) over and over, each VU is now runs an asynchronous event loop.

When the MQTT connection is created, the connect handler function will be immediately called, all code inside it will be executed (usually code to set up other event handlers), and then blocked until the MQTT connection is closed (by the remote host or by using client.end()).

import { Client } from "k6/x/mqtt";

export default function () {
  const client = new Client()

  client.on("connect", async () => {
    console.log("Connected to MQTT broker")
    client.subscribe("greeting")
    client.publish("greeting", "Hello MQTT!")
  })

  client.on("message", (topic, message) => {
    const str = String.fromCharCode.apply(null, new Uint8Array(message))
    console.info("topic:", topic, "message:", str)
    client.end()
  })

  client.on("end", () => {
    console.log("Disconnected from MQTT broker")
  })

  client.connect(__ENV["MQTT_BROKER_ADDRESS"] || "mqtt://broker.emqx.io:1883")
}

Example: Async Programming

Async and event-based programming is fully supported. You can use setTimeout(), setInterval(), and other async patterns with xk6-mqtt event handlers.

import { Client } from "k6/x/mqtt";

export default function () {
  const client = new Client()

  client.on("connect", async () => {
    console.log("Connected to MQTT broker")
    await client.subscribeAsync("probe")

    const intervalId = setInterval(() => {
      client.publish("probe", "ping MQTT!")
    }, 1000)

    setTimeout(() => {
      clearInterval(intervalId)
      client.end()
    }, 3100)
  })

  client.on("message", (topic, message) => {
    console.info(String.fromCharCode.apply(null, new Uint8Array(message)))
  })

  client.on("end", () => {
    console.log("Disconnected from MQTT broker")
  })

  client.connect(__ENV["MQTT_BROKER_ADDRESS"] || "mqtt://broker.emqx.io:1883")
}