AWS SDK

/*

 * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.

 * SPDX-License-Identifier: Apache-2.0

 */

//! # aws-smithy-mocks

//!

//! A flexible mocking framework for testing clients generated by smithy-rs, including all packages of the AWS SDK for Rust.

//!

//! This crate provides a simple yet powerful way to mock SDK client responses for testing purposes.

//! It uses interceptors to return stub responses, allowing you to test both happy-path and error scenarios

//! without mocking the entire client or using traits.

//!

//! ## Key Features

//!

//! - **Simple API**: Create mock rules with a fluent API using the [`mock!`] macro

//! - **Flexible Response Types**: Return modeled outputs, errors, or raw HTTP responses

//! - **Request Matching**: Match requests based on their properties

//! - **Response Sequencing**: Define sequences of responses for testing retry behavior

//! - **Rule Modes**: Control how rules are matched and applied

//!

//! ## Basic Usage

//!

//! ```rust,ignore

//! use aws_sdk_s3::operation::get_object::GetObjectOutput;

//! use aws_sdk_s3::Client;

//! use aws_smithy_types::byte_stream::ByteStream;

//! use aws_smithy_mocks::{mock, mock_client};

//!

//! #[tokio::test]

//! async fn test_s3_get_object() {

//!     // Create a rule that returns a successful response

//!     let get_object_rule = mock!(Client::get_object)

//!         .match_requests(|req| req.bucket() == Some("test-bucket") && req.key() == Some("test-key"))

//!         .then_output(|| GetObjectOutput::builder()

//!             .body(ByteStream::from_static(b"test-content"))

//!             .build()

//!          );

//!

//!     // Create a mocked client with the rule

//!     let s3 = mock_client!(aws_sdk_s3, [&get_object_rule]);

//!

//!     // Use the client as you would normally

//!     let result = s3.get_object()

//!         .bucket("test-bucket")

//!         .key("test-key")

//!         .send()

//!         .await

//!         .expect("success response");

//!

//!     // Verify the response

//!     let data = result.body.collect().await.expect("successful read").to_vec();

//!     assert_eq!(data, b"test-content");

//!

//!     // Verify the rule was used

//!     assert_eq!(get_object_rule.num_calls(), 1);

//! }

//! ```

//!

//! ## Creating Rules

//!

//! Rules are created using the [`mock!`] macro, which takes a client operation as an argument:

//!

//! ```rust,ignore

//! let rule = mock!(Client::get_object)

//!     // Optional: Add a matcher to filter requests

//!     .match_requests(|req| req.bucket() == Some("test-bucket"))

//!     // Add a response

//!     .then_output(|| GetObjectOutput::builder().build());

//! ```

//!

//! ### Response Types

//!

//! You can return different types of responses:

//!

//! ```rust,ignore

//! // Return a modeled output

//! let success_rule = mock!(Client::get_object)

//!     .then_output(|| GetObjectOutput::builder().build());

//!

//! // Return a modeled error

//! let error_rule = mock!(Client::get_object)

//!     .then_error(|| GetObjectError::NoSuchKey(NoSuchKey::builder().build()));

//!

//! // Return an HTTP response

//! let http_rule = mock!(Client::get_object)

//!     .then_http_response(|| HttpResponse::new(

//!         StatusCode::try_from(503).unwrap(),

//!         SdkBody::from("service unavailable")

//!     ));

//! ```

//!

//! ### Response Sequences

//!

//! For testing retry behavior or complex scenarios, you can define sequences of responses using the sequence builder API:

//!

//! ```rust,ignore

//! let retry_rule = mock!(Client::get_object)

//!     .sequence()

//!     .http_status(503, None)                          // First call returns 503

//!     .http_status(503, None)                          // Second call returns 503

//!     .output(|| GetObjectOutput::builder().build())   // Third call succeeds

//!     .build();

//!

//! // With repetition using `times()`

//! let retry_rule = mock!(Client::get_object)

//!     .sequence()

//!     .http_status(503, None)

//!     .times(2)                                        // First two calls return 503

//!     .output(|| GetObjectOutput::builder().build())   // Third call succeeds

//!     .build();

//! ```

//!

//! The sequence builder API provides a fluent interface for defining sequences of responses.

//! After providing all responses in the sequence, the rule is considered exhausted.

//!

//! ## Creating Mocked Clients

//!

//! Use the [`mock_client!`] macro to create a client with your rules:

//!

//! ```rust,ignore

//! // Create a client with a single rule

//! let client = mock_client!(aws_sdk_s3, [&rule]);

//!

//! // Create a client with multiple rules and a specific rule mode

//! let client = mock_client!(aws_sdk_s3, RuleMode::Sequential, [&rule1, &rule2]);

//!

//! // Create a client with additional configuration

//! let client = mock_client!(

//!     aws_sdk_s3,

//!     RuleMode::Sequential,

//!     [&rule],

//!     |config| config.force_path_style(true)

//! );

//! ```

//!

//! ## Rule Modes

//!

//! The [`RuleMode`] enum controls how rules are matched and applied:

//!

//! - `RuleMode::Sequential`: Rules are tried in order. When a rule is exhausted, the next rule is used.

//! - `RuleMode::MatchAny`: The first matching rule is used, regardless of order.

//!

//! ```rust,ignore

//! let interceptor = MockResponseInterceptor::new()

//!     .rule_mode(RuleMode::Sequential)

//!     .with_rule(&rule1)

//!     .with_rule(&rule2);

//! ```

//!

//! ## Testing Retry Behavior

//!

//! The mocking framework supports testing retry behavior by allowing you to define sequences of responses:

//!

//! ```rust,ignore

//! #[tokio::test]

//! async fn test_retry() {

//!     // Create a rule that returns errors for the first two attempts, then succeeds

//!     let rule = mock!(Client::get_object)

//!         .sequence()

//!         .http_status(503, None)

//!         .times(2)                                       // Service unavailable for first two calls

//!         .output(|| GetObjectOutput::builder().build())  // Success on third call

//!         .build();

//!

//!     // Create a client with retry enabled

//!     let client = mock_client!(aws_sdk_s3, [&rule]);

//!

//!     // The operation should succeed after retries

//!     let result = client.get_object()

//!         .bucket("test-bucket")

//!         .key("test-key")

//!         .send()

//!         .await;

//!

//!     assert!(result.is_ok());

//!     assert_eq!(rule.num_calls(), 3);  // Called 3 times (2 failures + 1 success)

//! }

//! ```

//!

/* Automatically managed default lints */

#![cfg_attr(docsrs, feature(doc_auto_cfg))]

/* End of automatically managed default lints */

#![warn(

    missing_docs,

    rustdoc::missing_crate_level_docs,

    unreachable_pub,

    rust_2018_idioms

)]

mod interceptor;

mod rule;

pub use interceptor::{create_mock_http_client, MockResponseInterceptor};

pub(crate) use rule::MockResponse;

pub use rule::{Rule, RuleBuilder, RuleMode};

// why do we need a macro for this?

// We want customers to be able to provide an ergonomic way to say the method they're looking for,

// `Client::list_buckets`, e.g. But there isn't enough information on that type to recover everything.

// This macro commits a small amount of crimes to recover that type information so we can construct

// a rule that can intercept these operations.

/// `mock!` macro that produces a [`RuleBuilder`] from a client invocation

///

/// See the `examples` folder of this crate for fully worked examples.

///

/// # Examples

///

/// **Mock and return a success response**:

///

/// ```rust,ignore

/// use aws_sdk_s3::operation::get_object::GetObjectOutput;

/// use aws_sdk_s3::Client;

/// use aws_smithy_types::byte_stream::ByteStream;

/// use aws_smithy_mocks::mock;

/// let get_object_happy_path = mock!(Client::get_object)

///   .match_requests(|req|req.bucket() == Some("test-bucket") && req.key() == Some("test-key"))

///   .then_output(||GetObjectOutput::builder().body(ByteStream::from_static(b"12345-abcde")).build());

/// ```

///

/// **Mock and return an error**:

/// ```rust,ignore

/// use aws_sdk_s3::operation::get_object::GetObjectError;

/// use aws_sdk_s3::types::error::NoSuchKey;

/// use aws_sdk_s3::Client;

/// use aws_smithy_mocks::mock;

/// let get_object_error_path = mock!(Client::get_object)

///   .then_error(||GetObjectError::NoSuchKey(NoSuchKey::builder().build()));

/// ```

///

#[macro_export]

macro_rules! mock {

    ($operation: expr) => {

        #[allow(unreachable_code)]

        {

            $crate::RuleBuilder::new_from_mock(

                // We don't actually want to run this code, so we put it in a closure. The closure

                // has the types we want which makes this whole thing type-safe (and the IDE can even

                // figure out the right input/output types in inference!)

                // The code generated here is:

                // `Client::list_buckets(todo!())`

                || $operation(todo!()).as_input().clone().build().unwrap(),

                || $operation(todo!()).send(),

            )

        }

    };

}

// This could be obviated by a reasonable trait, since you can express it with SdkConfig if clients implement From<&SdkConfig>.

/// `mock_client!` macro produces a Client configured with a number of Rules and appropriate test default configuration.

///

/// # Examples

///

/// **Create a client that uses a mock failure and then a success**:

///

/// ```rust,ignore

/// use aws_sdk_s3::operation::get_object::{GetObjectOutput, GetObjectError};

/// use aws_sdk_s3::types::error::NoSuchKey;

/// use aws_sdk_s3::Client;

/// use aws_smithy_types::byte_stream::ByteStream;

/// use aws_smithy_mocks::{mock_client, mock, RuleMode};

/// let get_object_error_path = mock!(Client::get_object)

///   .then_error(||GetObjectError::NoSuchKey(NoSuchKey::builder().build()))

///   .build();

/// let get_object_happy_path = mock!(Client::get_object)

///   .match_requests(|req|req.bucket() == Some("test-bucket") && req.key() == Some("test-key"))

///   .then_output(||GetObjectOutput::builder().body(ByteStream::from_static(b"12345-abcde")).build())

///   .build();

/// let client = mock_client!(aws_sdk_s3, RuleMode::Sequential, &[&get_object_error_path, &get_object_happy_path]);

///

///

/// **Create a client but customize a specific setting**:

/// rust,ignore

/// use aws_sdk_s3::operation::get_object::GetObjectOutput;

/// use aws_sdk_s3::Client;

/// use aws_smithy_types::byte_stream::ByteStream;

/// use aws_smithy_mocks::{mock_client, mock, RuleMode};

/// let get_object_happy_path = mock!(Client::get_object)

///   .match_requests(|req|req.bucket() == Some("test-bucket") && req.key() == Some("test-key"))

///   .then_output(||GetObjectOutput::builder().body(ByteStream::from_static(b"12345-abcde")).build())

///   .build();

/// let client = mock_client!(

///     aws_sdk_s3,

///     RuleMode::Sequential,

///     &[&get_object_happy_path],

///     // Perhaps you need to force path style

///     |client_builder|client_builder.force_path_style(true)

/// );

/// ```

///

#[macro_export]

macro_rules! mock_client {

    ($aws_crate: ident, $rules: expr) => {

        $crate::mock_client!($aws_crate, $crate::RuleMode::Sequential, $rules)

    };

    ($aws_crate: ident, $rule_mode: expr, $rules: expr) => {{

        $crate::mock_client!($aws_crate, $rule_mode, $rules, |conf| conf)

    }};

    ($aws_crate: ident, $rule_mode: expr, $rules: expr, $additional_configuration: expr) => {{

        let mut mock_response_interceptor =

            $crate::MockResponseInterceptor::new().rule_mode($rule_mode);

        for rule in $rules {

            mock_response_interceptor = mock_response_interceptor.with_rule(rule)

        }

        // Create a mock HTTP client

        let mock_http_client = $crate::create_mock_http_client();

        // Allow callers to avoid explicitly specifying the type

        fn coerce<T: Fn($aws_crate::config::Builder) -> $aws_crate::config::Builder>(f: T) -> T {

            f

        }

        $aws_crate::client::Client::from_conf(

            coerce($additional_configuration)(

                $aws_crate::config::Config::builder()

                    .with_test_defaults()

                    .region($aws_crate::config::Region::from_static("us-east-1"))

                    .http_client(mock_http_client)

                    .interceptor(mock_response_interceptor),

            )

            .build(),

        )

    }};

}

/*

 * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.

 * SPDX-License-Identifier: Apache-2.0

 */

use aws_smithy_runtime_api::client::interceptors::context::{Error, Input, Output};

use aws_smithy_runtime_api::client::orchestrator::HttpResponse;

use aws_smithy_runtime_api::client::result::SdkError;

use aws_smithy_runtime_api::http::StatusCode;

use aws_smithy_types::body::SdkBody;

use std::fmt;

use std::future::Future;

use std::sync::atomic::{AtomicUsize, Ordering};

use std::sync::Arc;

/// A mock response that can be returned by a rule.

///

/// This enum represents the different types of responses that can be returned by a mock rule:

/// - `Output`: A successful modeled response

/// - `Error`: A modeled error

/// - `Http`: An HTTP response

///

#[derive(Debug)]

pub(crate) enum MockResponse<O, E> {

    /// A successful modeled response.

    Output(O),

    /// A modeled error.

    Error(E),

    /// An HTTP response.

    Http(HttpResponse),

}

/// A function that matches requests.

type MatchFn = Arc<dyn Fn(&Input) -> bool + Send + Sync>;

type ServeFn = Arc<dyn Fn(usize) -> Option<MockResponse<Output, Error>> + Send + Sync>;

/// A rule for matching requests and providing mock responses.

///

/// Rules are created using the `mock!` macro or the `RuleBuilder`.

///

#[derive(Clone)]

pub struct Rule {

    /// Function that determines if this rule matches a request.

    pub(crate) matcher: MatchFn,

    /// Handler function that generates responses.

    pub(crate) response_handler: ServeFn,

    /// Number of times this rule has been called.

    pub(crate) call_count: Arc<AtomicUsize>,

    /// Maximum number of responses this rule will provide.

    pub(crate) max_responses: usize,

}

impl fmt::Debug for Rule {

    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {

        write!(f, "Rule")

    }

}

impl Rule {

    /// Creates a new rule with the given matcher, response handler, and max responses.

    pub(crate) fn new<O, E>(

        matcher: MatchFn,

        response_handler: Arc<dyn Fn(usize) -> Option<MockResponse<O, E>> + Send + Sync>,

        max_responses: usize,

    ) -> Self

    where

        O: fmt::Debug + Send + Sync + 'static,

        E: fmt::Debug + Send + Sync + std::error::Error + 'static,

    {

        Rule {

            matcher,

            response_handler: Arc::new(move |idx: usize| {

                if idx < max_responses {

                    response_handler(idx).map(|resp| match resp {

                        MockResponse::Output(o) => MockResponse::Output(Output::erase(o)),

                        MockResponse::Error(e) => MockResponse::Error(Error::erase(e)),

                        MockResponse::Http(http_resp) => MockResponse::Http(http_resp),

                    })

                } else {

                    None

                }

            }),

            call_count: Arc::new(AtomicUsize::new(0)),

            max_responses,

        }

    }

    /// Gets the next response.

    pub(crate) fn next_response(&self) -> Option<MockResponse<Output, Error>> {

        let idx = self.call_count.fetch_add(1, Ordering::SeqCst);

        (self.response_handler)(idx)

    }

    /// Returns the number of times this rule has been called.

    pub fn num_calls(&self) -> usize {

        self.call_count.load(Ordering::SeqCst)

    }

    /// Checks if this rule is exhausted (has provided all its responses).

    pub fn is_exhausted(&self) -> bool {

        self.num_calls() >= self.max_responses

    }

}

/// RuleMode describes how rules will be interpreted.

/// - In RuleMode::MatchAny, the first matching rule will be applied, and the rules will remain unchanged.

/// - In RuleMode::Sequential, the first matching rule will be applied, and that rule will be removed from the list of rules **once it is exhausted**.

#[derive(Debug, Clone, Copy, PartialEq, Eq)]

pub enum RuleMode {

    /// Match rules in the order they were added. The first matching rule will be applied and the

    /// rules will remain unchanged

    Sequential,

    /// The first matching rule will be applied, and that rule will be removed from the list of rules

    /// **once it is exhausted**. Each rule can have multiple responses, and all responses in a rule

    /// will be consumed before moving to the next rule.

    MatchAny,

}

/// A builder for creating rules.

///

/// This builder provides a fluent API for creating rules with different response types.

///

pub struct RuleBuilder<I, O, E> {

    /// Function that determines if this rule matches a request.

    pub(crate) input_filter: MatchFn,

    /// Phantom data for the input type.

    pub(crate) _ty: std::marker::PhantomData<(I, O, E)>,

}

impl<I, O, E> RuleBuilder<I, O, E>

where

    I: fmt::Debug + Send + Sync + 'static,

    O: fmt::Debug + Send + Sync + 'static,

    E: fmt::Debug + Send + Sync + std::error::Error + 'static,

{

    /// Creates a new [`RuleBuilder`]

    #[doc(hidden)]

    pub fn new() -> Self {

        RuleBuilder {

            input_filter: Arc::new(|i: &Input| i.downcast_ref::<I>().is_some()),

            _ty: std::marker::PhantomData,

        }

    }

    /// Creates a new [`RuleBuilder`]. This is normally constructed with the [`mock!`] macro

    #[doc(hidden)]

    pub fn new_from_mock<F, R>(_input_hint: impl Fn() -> I, _output_hint: impl Fn() -> F) -> Self

    where

        F: Future<Output = Result<O, SdkError<E, R>>>,

    {

        Self {

            input_filter: Arc::new(|i: &Input| i.downcast_ref::<I>().is_some()),

            _ty: Default::default(),

        }

    }

    /// Sets the function that determines if this rule matches a request.

    pub fn match_requests<F>(mut self, filter: F) -> Self

    where

        F: Fn(&I) -> bool + Send + Sync + 'static,

    {

        self.input_filter = Arc::new(move |i: &Input| match i.downcast_ref::<I>() {

            Some(typed_input) => filter(typed_input),

            _ => false,

        });

        self

    }

    /// Start building a response sequence

    ///

    /// A sequence allows a single rule to generate multiple responses which can

    /// be used to test retry behavior.

    ///

    /// # Examples

    ///

    /// With repetition using `times()`:

    ///

    /// ```rust,ignore

    /// let rule = mock!(Client::get_object)

    ///     .sequence()

    ///     .http_status(503, None)

    ///     .times(2)                                        // First two calls return 503

    ///     .output(|| GetObjectOutput::builder().build())   // Third call succeeds

    ///     .build();

    /// ```

    pub fn sequence(self) -> ResponseSequenceBuilder<I, O, E> {

        ResponseSequenceBuilder::new(self.input_filter)

    }

    /// Creates a rule that returns a modeled output.

    pub fn then_output<F>(self, output_fn: F) -> Rule

    where

        F: Fn() -> O + Send + Sync + 'static,

    {

        self.sequence().output(output_fn).build()

    }

    /// Creates a rule that returns a modeled error.

    pub fn then_error<F>(self, error_fn: F) -> Rule

    where

        F: Fn() -> E + Send + Sync + 'static,

    {

        self.sequence().error(error_fn).build()

    }

    /// Creates a rule that returns an HTTP response.

    pub fn then_http_response<F>(self, response_fn: F) -> Rule

    where

        F: Fn() -> HttpResponse + Send + Sync + 'static,

    {

        self.sequence().http_response(response_fn).build()

    }

}

type SequenceGeneratorFn<O, E> = Arc<dyn Fn() -> MockResponse<O, E> + Send + Sync>;

/// A builder for creating response sequences

pub struct ResponseSequenceBuilder<I, O, E> {

    /// The response generators in the sequence

    generators: Vec<SequenceGeneratorFn<O, E>>,

    /// Function that determines if this rule matches a request

    input_filter: MatchFn,

    /// Marker for the input, output, and error types

    _marker: std::marker::PhantomData<I>,

}

impl<I, O, E> ResponseSequenceBuilder<I, O, E>

where

    I: fmt::Debug + Send + Sync + 'static,

    O: fmt::Debug + Send + Sync + 'static,

    E: fmt::Debug + Send + Sync + std::error::Error + 'static,

{

    /// Create a new response sequence builder

    pub(crate) fn new(input_filter: MatchFn) -> Self {

        Self {

            generators: Vec::new(),

            input_filter,

            _marker: std::marker::PhantomData,

        }

    }

    /// Add a modeled output response to the sequence

    ///

    /// # Examples

    ///

    /// ```rust,ignore

    /// let rule = mock!(Client::get_object)

    ///     .sequence()

    ///     .output(|| GetObjectOutput::builder().build())

    ///     .build();

    /// ```

    pub fn output<F>(mut self, output_fn: F) -> Self

    where

        F: Fn() -> O + Send + Sync + 'static,

    {

        let generator = Arc::new(move || MockResponse::Output(output_fn()));

        self.generators.push(generator);

        self

    }

    /// Add a modeled error response to the sequence

    pub fn error<F>(mut self, error_fn: F) -> Self

    where

        F: Fn() -> E + Send + Sync + 'static,

    {

        let generator = Arc::new(move || MockResponse::Error(error_fn()));

        self.generators.push(generator);

        self

    }

    /// Add an HTTP status code response to the sequence

    pub fn http_status(mut self, status: u16, body: Option<String>) -> Self {

        let status_code = StatusCode::try_from(status).unwrap();

        let generator: SequenceGeneratorFn<O, E> = match body {

            Some(body) => Arc::new(move || {

                MockResponse::Http(HttpResponse::new(status_code, SdkBody::from(body.clone())))

            }),

            None => Arc::new(move || {

                MockResponse::Http(HttpResponse::new(status_code, SdkBody::empty()))

            }),

        };

        self.generators.push(generator);

        self

    }

    /// Add an HTTP response to the sequence

    pub fn http_response<F>(mut self, response_fn: F) -> Self

    where

        F: Fn() -> HttpResponse + Send + Sync + 'static,

    {

        let generator = Arc::new(move || MockResponse::Http(response_fn()));

        self.generators.push(generator);

        self

    }

    /// Repeat the last added response multiple times (total count)

    pub fn times(mut self, count: usize) -> Self {

        if count <= 1 {

            return self;

        }

        if let Some(last_generator) = self.generators.last().cloned() {

            // Add count-1 more copies (we already have one)

            for _ in 1..count {

                self.generators.push(last_generator.clone());

            }

        }

        self

    }

    /// Build the rule with this response sequence

    pub fn build(self) -> Rule {

        let generators = self.generators;

        let count = generators.len();

        Rule::new(

            self.input_filter,

            Arc::new(move |idx| {

                if idx < count {

                    Some(generators[idx]())

                } else {

                    None

                }

            }),

            count,

        )

    }

}

/*

 * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.

 * SPDX-License-Identifier: Apache-2.0

 */

/// Basic test of using the mock_client macro from an "external" crate

mod fake_crate {

    pub(crate) mod client {

        use crate::fake_crate::config;

        pub(crate) struct Client {}

        impl Client {

            pub(crate) fn from_conf(_conf: config::Config) -> Self {

                Self {}

            }

        }

    }

    pub(crate) mod config {

        use aws_smithy_runtime_api::client::http::SharedHttpClient;

        use aws_smithy_runtime_api::client::interceptors::Intercept;

        pub(crate) struct Config {}

        impl Config {

            pub(crate) fn builder() -> Builder {

                Builder {}

            }

        }

        pub(crate) struct Builder {}

        impl Builder {

            pub fn build(self) -> Config {

                Config {}

            }

            pub fn region(self, _region: crate::fake_crate::config::Region) -> Self {

                Self {}

            }

            pub fn with_test_defaults(self) -> Self {

                Self {}

            }

            pub fn http_client(self, _http_client: SharedHttpClient) -> Self {

                Self {}

            }

            pub fn interceptor(self, _interceptor: impl Intercept + 'static) -> Self {

                self

            }

        }

        pub(crate) struct Region {}

        impl Region {

            pub fn from_static(_region: &'static str) -> Self {

                Self {}

            }

        }

    }

}

#[test]

fn mock_client() {

    aws_smithy_mocks::mock_client!(fake_crate, &[]);

}

version = "1.0.2"

version = "1.0.2"

version = "1.0.2"

version = "1.0.2"

version = "1.0.2"

version = "1.0.2"

version = "1.0.2"

version = "1.0.2"

version = "1.0.2"