Skip to content

Latest commit

 

History

History
121 lines (98 loc) · 3.99 KB

README.md

File metadata and controls

121 lines (98 loc) · 3.99 KB
Raw

MQTT test server

Mqttest is an MQTT server designed for unittesting clients.

Compared to a standard server like Mosquitto, Mqttest brings a CI-friendly binary, fast RC-free tests, detailed machine-readable packet dumps, network problem simulations, selectable implementaion quirks, running the server as a library, etc.

Initial development has been sponsored by Munic.

Current and planned features

  • Simplified CI image
    • Automatic open port discovery (simplifies parallel test execution)
    • Statically-built single-file CLI binary (no runtime deps or fancy install)
    • Use as a rust library
      • Decode file dumps to rust structs
      • Configure and start server
      • Runtime server control and client interaction using rust channels
      • Return dumps and stats after each run
    • Use as a library from other languages
  • Verbose log file and network dump
    • No need for RC-prone connection of an observer client
    • Json dump of mqtt packet data and metadata (time, connection id...)
    • Global or per-connection dump filename
    • Flexible payload decoding
  • Controllable connection behaviors:
    • Ack delay
    • Close connection after a number of packets or a timeout
    • Go offline
    • Bad packet flow (spurious/missing ack/publish)
    • Override session lifetime
    • Reject clients by id or password
    • Different pid-assignment strategies
    • Different behavior for subsequent connections
    • Stop server after a number of connections
    • Stop server after a max runtime
    • Your useful behavior here
  • Protocol support
    • MQTT 3.1.1
    • MQTT 5
    • IPv6
    • TLS
    • Warn about or reject extended client identifiers
    • Warn about MQTT3 idioms obsoletted by MQTT5
    • Documentation highlights MQTT implementation gotchas

Some "missing" features may already be partially implemented. They will be marked as done when fully done.

Non-features

  • Codec-level errors (better to unittest this at the codec library level).
  • Wildcard topics (at least for now - not useful ?).
  • Database or clustering support (offtopic).
  • High performance/scalability (though aim to be small and fast).

Usage

Install Rust >= 1.39.0 if necessary.

Standalone binary

# Build and install the executable
cargo install --path .

# See help
mqttest -h

Mqttest starts in just a few milliseconds. You can start a server with a different behaviour for each of your client unittest. Or you can start a single instance and leave it running while you do some ad-hoc testing.

Rust library

In your Cargo.toml:

[dev-dependencies]
# MQTT test server.
mqttest = { version = "0.2.0", default-features = false }
# mqttest needs to be started from a tokio async context.
tokio = "0.2"
# At your discretion, if you want to see server logs.
env_logger = "0.7"

In your unittests (see test.rs for more detailed examples) :

/// Boiler-plate to run and log async code from a unittest.
fn block_on<T>(f: impl Future<Output = T>) -> T {
    let _ = env_logger::builder().is_test(true).parse_filters("debug").try_init();
    tokio::runtime::Builder::new().basic_scheduler().enable_all().build().unwrap().block_on(f)
}

/// Example unittest. Bring your own client.
#[test]
fn connect() {
    let stats = block_on(async {
        // Create a server config
        let conf = Conf::new().max_connect(1);
        // Start the server
        let srv = Mqttest::start(conf).await.expect("Failed listen").await;
        // Start your client on the port that the server selected
        client::start(srv.port).await.expect("Client failure");
        // Wait for the server to finish
        srv.finish().await.unwrap()
    });
    // Check run results
    assert_eq!(1, stats.conn_count);
}

Optional features

cli

Required to build the binary (as opposed to the library). Enabled by default.