Struct MockService

pub struct MockService<Request, Response, Assertion, Error = BoxError> {
    receiver: Receiver<Arc<Mutex<Option<ResponseSender<Request, Response, Error>>>>>,
    sender: Sender<Arc<Mutex<Option<ResponseSender<Request, Response, Error>>>>>,
    poll_count: Arc<AtomicUsize>,
    max_request_delay: Duration,
    _assertion_type: PhantomData<Assertion>,
}

A service implementation that allows intercepting requests for checking them.

The type is generic over the request and response types, and also has an extra generic type parameter that’s used as a tag to determine if the internal assertions should panic or return errors for proptest minimization. See AssertionType for more information.

The mock service can be cloned, and provides methods for checking the received requests as well as responding to them individually.

Internally, the instance that’s operating as the service will forward requests to a [broadcast] channel that the other instances listen to.

See the module-level documentation for an example.

Fields

receiver: Receiver<Arc<Mutex<Option<ResponseSender<Request, Response, Error>>>>>

sender: Sender<Arc<Mutex<Option<ResponseSender<Request, Response, Error>>>>>

poll_count: Arc<AtomicUsize>

max_request_delay: Duration

_assertion_type: PhantomData<Assertion>

Implementations

impl MockService<(), (), ()>

An entry point for starting the MockServiceBuilder.

This impl block exists for ergonomic reasons. The generic type parameters don’t matter, because they are actually set by MockServiceBuilder::finish.

pub fn build() -> MockServiceBuilder

Create a MockServiceBuilder to help with the creation of a MockService.

impl<Request, Response, Error> MockService<Request, Response, PanicAssertion, Error>

Implementation of MockService methods that use standard Rust panicking assertions.

pub async fn expect_request( &mut self, expected: Request, ) -> ResponseSender<Request, Response, Error>

where Request: PartialEq + Debug,

Expect a specific request to be received.

The expected request should be the next one in the internal queue, or if the queue is empty, it should be received in at most the max delay time configured by MockServiceBuilder::with_max_request_delay.

If the received request matches the expected request, a ResponseSender is returned which can be used to inspect the request and respond to it. If no response is sent, the sender of the requests receives an error.

Panics

If no request is received or if a request is received that’s not equal to the expected request, this method panics.

Example

let call = tokio::spawn(mock_service.clone().oneshot("request"));

mock_service.expect_request("request").await.respond("response");

assert!(matches!(call.await, Ok(Ok("response"))));

pub async fn expect_request_that( &mut self, condition: impl FnOnce(&Request) -> bool, ) -> ResponseSender<Request, Response, Error>

where Request: Debug,

Expect a request to be received that matches a specified condition.

There should be a request already in the internal queue, or a request should be received in at most the max delay time configured by MockServiceBuilder::with_max_request_delay.

The received request is passed to the condition function, which should return true if it matches the expected condition or false otherwise. If true is returned, a ResponseSender is returned which can be used to inspect the request again and respond to it. If no response is sent, the sender of the requests receives an error.

Panics

If the condition function returns false, this method panics.

Example

let call = tokio::spawn(mock_service.clone().oneshot(1));

mock_service.expect_request_that(|request| *request > 0).await.respond("response");

assert!(matches!(call.await, Ok(Ok("response"))));

pub async fn expect_no_requests(&mut self)

where Request: Debug,

Expect no requests to be received.

The internal queue of received requests should be empty, and no new requests should arrive for the max delay time configured by MockServiceBuilder::with_max_request_delay.

Panics

If the queue is not empty or if a request is received before the max request delay timeout expires.

Example

mock_service.expect_no_requests().await;

async fn next_request(&mut self) -> ResponseSender<Request, Response, Error>

Returns the next request from the queue, or panics if there are no requests after a short timeout.

Returns the next request in the internal queue or waits at most the max delay time configured by MockServiceBuilder::with_max_request_delay for a new request to be received, and then returns that.

Panics

If the queue is empty and a request is not received before the max request delay timeout expires.

pub fn poll_count(&self) -> usize

Returns a count of the number of times this service has been polled.

Note: The poll count wraps around on overflow.

impl<Request, Response, Error> MockService<Request, Response, PropTestAssertion, Error>

Implementation of MockService methods that use [mod@proptest] assertions.

pub async fn expect_request( &mut self, expected: Request, ) -> Result<ResponseSender<Request, Response, Error>, TestCaseError>

where Request: PartialEq + Debug,

Expect a specific request to be received.

The expected request should be the next one in the internal queue, or if the queue is empty, it should be received in at most the max delay time configured by MockServiceBuilder::with_max_request_delay.

If the received request matches the expected request, a ResponseSender is returned which can be used to inspect the request and respond to it. If no response is sent, the sender of the requests receives an error.

If no request is received or if a request is received that’s not equal to the expected request, this method returns an error generated by a [mod@proptest] assertion.

Example

let call = tokio::spawn(mock_service.clone().oneshot("request"));

// NOTE: The try operator `?` is required for errors to be handled by proptest.
mock_service
    .expect_request("request").await?
    .respond("response");

prop_assert!(matches!(call.await, Ok(Ok("response"))));

pub async fn expect_request_that( &mut self, condition: impl FnOnce(&Request) -> bool, ) -> Result<ResponseSender<Request, Response, Error>, TestCaseError>

where Request: Debug,

Expect a request to be received that matches a specified condition.

There should be a request already in the internal queue, or a request should be received in at most the max delay time configured by MockServiceBuilder::with_max_request_delay.

The received request is passed to the condition function, which should return true if it matches the expected condition or false otherwise. If true is returned, a ResponseSender is returned which can be used to inspect the request again and respond to it. If no response is sent, the sender of the requests receives an error.

If the condition function returns false, this method returns an error generated by a [mod@proptest] assertion.

Example

let call = tokio::spawn(mock_service.clone().oneshot(1));

// NOTE: The try operator `?` is required for errors to be handled by proptest.
mock_service
    .expect_request_that(|request| *request > 0).await?
    .respond("OK");

prop_assert!(matches!(call.await, Ok(Ok("OK"))));

pub async fn expect_no_requests(&mut self) -> Result<(), TestCaseError>

where Request: Debug,

Expect no requests to be received.

The internal queue of received requests should be empty, and no new requests should arrive for the max delay time configured by MockServiceBuilder::with_max_request_delay.

If the queue is not empty or if a request is received before the max request delay timeout expires, an error generated by a [mod@proptest] assertion is returned.

Example

// NOTE: The try operator `?` is required for errors to be handled by proptest.
mock_service.expect_no_requests().await?;

async fn next_request( &mut self, ) -> Result<ResponseSender<Request, Response, Error>, TestCaseError>

A helper method to get the next request from the queue.

Returns the next request in the internal queue or waits at most the max delay time configured by MockServiceBuilder::with_max_request_delay for a new request to be received, and then returns that.

If the queue is empty and a request is not received before the max request delay timeout expires, an error generated by a [mod@proptest] assertion is returned.

pub fn poll_count(&self) -> usize

Returns a count of the number of times this service has been polled.

Note: The poll count wraps around on overflow.

impl<Request, Response, Assertion, Error> MockService<Request, Response, Assertion, Error>

Code that is independent of the assertions used in MockService.

pub async fn try_next_request( &mut self, ) -> Option<ResponseSender<Request, Response, Error>>

Try to get the next request received.

Returns the next element in the queue. If the queue is empty, waits at most the max request delay configured by MockServiceBuilder::with_max_request_delay for a request, and returns it.

If no request is received, returns None.

If too many requests are received and the queue fills up, the oldest requests are dropped and ignored. This means that calling this may not receive the next request if the queue is not dimensioned properly with the MockServiceBuilder::with_proxy_channel_size method.

Trait Implementations

impl<Request, Response, Assertion, Error> Clone for MockService<Request, Response, Assertion, Error>

fn clone(&self) -> Self

Clones the MockService.

This is a cheap operation, because it simply clones the [broadcast] channel endpoints.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<Request, Response, Assertion, Error> Service<Request> for MockService<Request, Response, Assertion, Error>

where Request: Send + 'static, Response: Send + 'static, Error: Send + 'static,

The [tower::Service] implementation of the MockService.

The MockService is always ready, and it intercepts the requests wrapping them in a ResponseSender which can be used to send a response.

type Response = Response

Responses given by the service.

type Error = Error

Errors produced by the service.

type Future = Pin<Box<dyn Future<Output = Result<<MockService<Request, Response, Assertion, Error> as Service<Request>>::Response, <MockService<Request, Response, Assertion, Error> as Service<Request>>::Error>> + Send>>

The future response value.

fn poll_ready( &mut self, _context: &mut Context<'_>, ) -> Poll<Result<(), Self::Error>>

Returns Poll::Ready(Ok(())) when the service is able to process requests.

fn call(&mut self, request: Request) -> Self::Future

Process the request and return the response asynchronously.