watermelon_testkit/lib.rs
1//! Run tests against isolated, disposable `nats-server` instances
2//!
3//! Every test gets its own [`NatsServer`], bound to random ports on
4//! `127.0.0.1` and backed by a private temporary directory, so tests can
5//! run in parallel without sharing any state.
6//!
7//! ```no_run
8//! use watermelon_testkit::NatsServer;
9//!
10//! # async fn example() {
11//! let Some(server) = NatsServer::builder().jetstream().start().await else {
12//! // nats-server isn't installed: skip the test
13//! return;
14//! };
15//! println!("connect to {}", server.client_url());
16//! # }
17//! ```
18//!
19//! # Locating `nats-server`
20//!
21//! The binary is taken from the `NATS_SERVER_BIN` environment variable when
22//! it points to an existing file, otherwise it's looked up in `PATH`.
23//!
24//! When no binary can be found [`NatsServerBuilder::start`] returns `None`,
25//! so that the test can be skipped. If the `CI` environment variable is set
26//! it panics instead, so that a misconfigured CI can't silently skip tests.
27//!
28//! # Debugging failures
29//!
30//! The server runs with trace logging enabled. When a test panics while a
31//! [`NatsServer`] is alive, the tail of the server log is printed and the
32//! server's temporary directory, containing the configuration and the full
33//! log, is kept.
34
35#![cfg(unix)]
36
37pub use self::server::{NatsServer, NatsServerBuilder};
38pub use self::time::{TimeoutExt, eventually};
39
40mod http;
41mod server;
42mod time;