tower_test/lib.rs
1#![warn(
2 missing_debug_implementations,
3 missing_docs,
4 rust_2018_idioms,
5 unreachable_pub
6)]
7#![forbid(unsafe_code)]
8#![allow(elided_lifetimes_in_paths)]
9// `rustdoc::broken_intra_doc_links` is checked on CI
10
11//! Mock [`Service`]s for use in tests.
12//!
13//! When testing code built on [tower], it is often useful to swap a real
14//! service for one whose behaviour the test controls. [`mock::Mock`] is a
15//! [`Service`] that does nothing on its own: each request it receives is handed
16//! to a paired [`mock::Handle`], and the response is whatever the test chooses
17//! to send back through that handle. This makes it possible to assert on the
18//! exact requests a [`Service`] makes and to decide, per request, how to
19//! respond (including failing).
20//!
21//! Create a [`Mock`]/[`Handle`] pair with [`mock::pair`], or use
22//! [`mock::spawn()`] to get a [`mock::Spawn`] wrapper whose readiness can be
23//! polled synchronously in tests (for example with [tokio-test]).
24//!
25//! # Example
26//!
27//! ```
28//! use tokio_test::{assert_ready_ok, block_on};
29//! use tower_service::Service;
30//! use tower_test::mock;
31//!
32//! // Create a mock service together with the handle used to drive it.
33//! let (mut service, mut handle) = mock::spawn();
34//!
35//! // A freshly-created mock is ready to accept a request.
36//! assert_ready_ok!(service.poll_ready());
37//!
38//! // Calling the service sends the request to the handle and returns a future
39//! // that resolves once the handle responds.
40//! let response = service.call("hello");
41//!
42//! // Receive the request through the handle and reply to it.
43//! let (request, send_response) =
44//! block_on(handle.next_request()).expect("the service was called");
45//! assert_eq!(request, "hello");
46//! send_response.send_response("world");
47//!
48//! // Now that a response has been sent, the service's response future resolves.
49//! assert_eq!(block_on(response).unwrap(), "world");
50//! ```
51//!
52//! [`Service`]: tower_service::Service
53//! [tower]: https://docs.rs/tower
54//! [tokio-test]: https://docs.rs/tokio-test
55//! [`Mock`]: mock::Mock
56//! [`Handle`]: mock::Handle
57
58mod macros;
59pub mod mock;