xk6-mqtt
    Preparing search index...

    Class Client

    MQTT client for connecting to brokers and managing MQTT operations.

    The Client class provides a high-level, event-driven interface for interacting with MQTT brokers. It supports both synchronous and asynchronous operations for connecting, subscribing, publishing, and unsubscribing, and is designed to be familiar to users of MQTT.js.

    Event-Driven Usage

    Register event handlers for connection lifecycle and message events using .on() method:

    Event Description
    connect Triggered when the client successfully connects to the broker.
    message Triggered when a message is received on a subscribed topic.
    end Triggered when the client disconnects from the broker.
    reconnect Triggered when the client attempts to reconnect.
    error Triggered when an error occurs.

    All event handlers are executed in the context of the k6 VU event loop.

    SSL/TLS

    xk6-mqtt does not provide its own custom TLS configuration options. Instead, it relies on the standard k6 TLS configuration for all SSL/TLS settings. This means you should configure certificates, verification, and other TLS-related options using the same environment variables and configuration files as you would for any other k6 protocol. This approach ensures consistency across your k6 tests and leverages the robust, well-documented TLS support already present in k6.

    Supported Broker URL Schemas

    xk6-mqtt supports connecting to MQTT brokers using the following URL schemas:

    Schema Description
    mqtt:// Plain TCP connection (no encryption)
    mqtts:// Secure connection over SSL/TLS (recommended for production)
    tcp:// Alias for mqtt://, plain TCP connection
    ssl:// Alias for mqtts://, secure SSL/TLS connection
    tls:// Alias for mqtts://, secure SSL/TLS connection
    ws:// MQTT over WebSocket (if supported by the broker)
    wss:// MQTT over secure WebSocket (if supported by the broker)

    If you omit the schema in the broker URL, mqtt:// (plain TCP) is used as the default.

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

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

      client.on("connect", () => {
        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")
    }
    Index

    Constructors

    constructor

    Properties

    connected

    Methods

    connect end endAsync on publish publishAsync reconnect subscribe subscribeAsync unsubscribe unsubscribeAsync

    Constructors

    Properties

    connected: boolean

    Indicates if the client is currently connected.

    Methods

    • Disconnects from the MQTT broker synchronously.

      Parameters

      • Optionaloptions: EndOptions

        Optional disconnect options.

      Returns void

    • Disconnects from the MQTT broker asynchronously.

      Parameters

      • Optionaloptions: EndOptions

        Optional disconnect options.

      Returns Promise<void>

      Promise that resolves when disconnection is complete.

    • Listen for the connect event.

      Parameters

      • event: "connect"
      • listener: () => void

        Callback for connect event.

      Returns void

    • Listen for the end event.

      Parameters

      • event: "end"
      • listener: () => void

        Callback for end event.

      Returns void

    • Listen for the reconnect event.

      Parameters

      • event: "reconnect"
      • listener: () => void

        Callback for reconnect event.

      Returns void

    • Listen for incoming messages.

      Parameters

      • event: "message"
      • listener: (topic: string, payload: ArrayBuffer) => void

        Callback for message event.

      Returns void

    • Listen for errors.

      Parameters

      • event: "error"
      • listener: (error: MQTTError) => void

        Callback for error event.

      Returns void

    • Publish a message to a MQTT topic synchronously.

      Parameters

      • topic: string

        The topic to publish to.

      • payload: StringOrArrayBuffer

        The message payload (string or ArrayBuffer).

      • Optionaloptions: PublishOptions

        Optional publish options.

      Returns void

    • Publishes a message to an MQTT topic asynchronously.

      Parameters

      • topic: string

        The topic to publish to.

      • payload: StringOrArrayBuffer

        The message payload (string or ArrayBuffer).

      • Optionaloptions: PublishOptions

        Optional publish options.

      Returns Promise<void>

      Promise that resolves when publish is complete.

    • Attempts to reconnect to the MQTT broker. Uses the same connection parameters as the last successful connection.

      Returns void

    • Unsubscribe from one or more topics asynchronously.

      Parameters

      Returns Promise<void>

      Promise that resolves when unsubscription is complete.

    Settings

    On This Page

    Constructors
    Properties
    Methods