# MQTT test server

Mqttest is an [MQTT](https://mqtt.org/) 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](https://munic.io/).

## Current and planned features

- Simplified CI image
  - [x] Automatic open port discovery (simplifies parallel test execution)
  - [x] Statically-built single-file CLI binary (no runtime deps or fancy install)
  - [x] Use as a rust library
    - [x] Decode file dumps to rust structs
    - [x] 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
  - [x] No need for RC-prone connection of an observer client
  - [x] Json dump of mqtt packet data and metadata (time, connection id...)
  - [x] Global or per-connection dump filename
  - [ ] Flexible payload decoding
- Controllable connection behaviors:
  - [x] Ack delay
  - [x] Close connection after a number of packets or a timeout
  - [ ] Go offline
  - [ ] Bad packet flow (spurious/missing ack/publish)
  - [x] Override session lifetime
  - [x] Reject clients by id or password
  - [ ] Different pid-assignment strategies
  - [x] Different behavior for subsequent connections
  - [x] Stop server after a number of connections
  - [ ] Stop server after a max runtime
  - [ ] [Your useful behavior here](https://github.com/vincentdephily/mqttest/issues)
- Protocol support
  - [x] MQTT 3.1.1
  - [ ] MQTT 5
  - [ ] IPv6
  - [x] Warn about or reject extended client identifiers
  - [x] Warn about MQTT3 idioms obsoletted by MQTT5
  - [x] Documentation highlights MQTT implementation gotchas

## 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](https://rust-lang.org/) >= 1.39.0 if necessary.

### Standalone binary

```shell
# 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`:

```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`](src/test.rs) for more detailed examples) :

```rust
/// 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 conns: Vec<ConnInfo> = 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.fut.await.unwrap()
    });
    // Check run results
    assert_eq!(1, conns.len());
}
```

### Optional features

#### `cli`

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