promote aws-smithy-mocks out of experimental #4098

aajtodd · 2025-04-22T14:27:10Z

Motivation and Context

Description

Rename aws-smithy-mocks-experimental to aws-smithy-mocks and reset version to 0.1.0
Fix #3926 by having mock_client! macro always set an HTTP client. By default it returns a dummy I'm a teapot response to aid in debugging and be easy to tell where that response is coming from. Also when a rule sets an HTTP response it is not set as an extension in the request and returned by the HTTP client. This allows for more thorough and accurate integration testing as the client/runtime will see the response coming from the HTTP client instead of being ignored and then replaced as it was before
Added a new sequence builder API for allowing a rule to generate more than one response. This allows for testing retries for example.
Also deleted a hyper 1.x test that is no longer needed and was ignored anyway

Questions

In this PR I've simply renamed/moved aws-smithy-mocks-experimental to aws-smithy-mocks. Do we want or need to publish one last version of aws-smithy-mocks-experimental with a deprecated API that instructs users it has moved? Alternatively we could publish an informational advisory notice about the rename. We don't currently promote the crate anywhere and the dev guide will get updated so I'm on the fence for what we want to do.

Testing

Added new unit tests to exercise the API without needing an SDK client by leveraging the manual Operation APIs.
Added new integration tests for S3 to cover the macros and test the library e2e.

Checklist

For changes to the smithy-rs codegen or runtime crates, I have created a changelog entry Markdown file in the .changelog directory, specifying "client," "server," or both in the applies_to key.
For changes to the AWS SDK, generated SDK code, or SDK runtime crates, I have created a changelog entry Markdown file in the .changelog directory, specifying "aws-sdk-rust" in the applies_to key.

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

github-actions · 2025-04-22T17:32:23Z

A new generated diff is ready to view.

AWS SDK (ignoring whitespace)
Client Test (ignoring whitespace)
No codegen difference in the Server Test
No codegen difference in the Server Test Python
No codegen difference in the Server Test Typescript

A new doc preview is ready to view.

rcoh

I am really excited about this!

rcoh · 2025-04-22T17:21:52Z

rust-runtime/aws-smithy-mocks-experimental/src/lib.rs

@@ -3,11 +3,13 @@
 * SPDX-License-Identifier: Apache-2.0
 */

-//! This crate allows mocking of smithy clients.
+//! This crate has been deprecated. Please migrate to the `aws-smithy-mocks` crate.


We should link a migration guide from here

Right now the API should be compatible so I would hope/think that simply changing out the crate would be enough. I didn't force users to go through the new sequence() builder API, they can still do:

mock!(Client::get_object) .then_output(|| ...);

If we wanted a breaking change then I'd probably consider whether we even want to keep these since a sequence of 1 is the same:

mock!(Client::get_object) .sequence() .output(|| ...) .build()

I see mild utility in keeping the existing API for convenience but mostly I kept it so that existing code should be easy to migrate and still work.

The migration guide isn't as much as a "here's how you NEED to migrate" as much as its "here's all the cool things you can do with the new API"

rust-runtime/aws-smithy-mocks/src/lib.rs

rcoh · 2025-04-22T17:25:48Z

rust-runtime/aws-smithy-mocks/src/lib.rs

+///
+#[macro_export]
+macro_rules! mock {
+    ($operation: expr) => {


There is apparently a slightly less cursed way to do this @compiler-errors came up with

landonxjames · 2025-04-23T19:09:01Z

rust-runtime/aws-smithy-mocks/src/interceptor.rs

+}
+
+/// Interceptor which produces mock responses based on a list of rules
+pub struct MockResponseInterceptor {


I guess this has to be pub since the macro expands to add a MockResponseInterceptor::new(), but it feels like it should just be pub(crate) since we don't really intend for it to be used outside of the context of the macro. Could we update the macro to instead use a pub function like add_mock_interceptor(&mut config_builder) that takes in the config builder and adds the interceptor so we can keep it pub(crate)?

Interesting. For an HTTP client, it does have a pub free function create_mock_http_client that returns SharedHttpClient, used by the macro. We could have a similar pub free function returning SharedInterceptor, used by the macro.

It was pub before though and I believe there are people wiring it up that way today (internally anyway). I was trying to keep migration issues to a minimum but if we all feel this is the right direction I'm open to it.

Personally, for APIs required by macros, but that I don't want to expose publicly, I put them in a doc(hidden) module named __macro_impl or something like that.

Historically, we've seen that you need to eject out of the macros, and I think we should maintain that as a possibility.

The only thing is this needs the HTTP client to be the one created by create_mock_http_client. I made that function public to allow people to construct what the mock is doing manually but I'm not sure how we can validate the interceptor is being used in conjunction with the right HTTP client. I left this public and allowed the possibility though simply because people are already using this without the macro.

ysaito1001

I love the work, especially documentation. Looks great, leaving minor nits and comments on top of Landon's.

ysaito1001 · 2025-04-23T21:28:48Z

aws/sdk/integration-tests/s3/tests/mocks.rs

+        .key("foo")
+        .send()
+        .await
+        .expect_err("404"); // async fn mock_client() {


nit: should we remove comment?

ysaito1001 · 2025-04-23T23:09:02Z

rust-runtime/aws-smithy-mocks/src/interceptor.rs

+}
+
+/// Interceptor which produces mock responses based on a list of rules
+pub struct MockResponseInterceptor {


Interesting. For an HTTP client, it does have a pub free function create_mock_http_client that returns SharedHttpClient, used by the macro. We could have a similar pub free function returning SharedInterceptor, used by the macro.

ysaito1001 · 2025-04-23T23:31:31Z

rust-runtime/aws-smithy-mocks/src/rule.rs

+    }
+
+    /// Repeat the last added response multiple times (total count)
+    pub fn times(mut self, count: usize) -> Self {


What would happen if we specified .times(0)? I've worked with google mocks for C++ where TIMES(0) means that no call is expected for the mock method.

Right now anything less than 1 has no additional effect.

Got it, we should probably call out in the doc stating anything less than 1 has no effect or leave TODO.

In addition to documenting, I would probably panic on 0, this will be run in tests anyway and we want to make it as obvious as possible.

github-actions · 2025-04-24T14:16:52Z

A new generated diff is ready to view.

AWS SDK (ignoring whitespace)
Client Test (ignoring whitespace)
No codegen difference in the Server Test
No codegen difference in the Server Test Python
No codegen difference in the Server Test Typescript

A new doc preview is ready to view.

jlizen · 2025-04-24T16:29:37Z

Do we want or need to publish one last version of aws-smithy-mocks-experimental with a deprecated API that instructs users it has moved? Alternatively we could publish an informational advisory notice about the rename. We don't currently promote the crate anywhere and the dev guide will get updated so I'm on the fence for what we want to do.

I think probably yes and yes, it's low-cost and avoids potential confusion.

jlizen · 2025-04-24T16:30:44Z

.changelog/1745330307.md

+    let retry_rule = mock!(aws_sdk_s3::Client::get_object)
+        .sequence()
+        .http_status(503, None)
+        .times(2)                                            // Return 503 HTTP status twice


Nice, I like this API that you landed on.

jlizen · 2025-04-24T16:33:59Z

rust-runtime/aws-smithy-mocks/src/rule.rs

+    }
+
+    /// Repeat the last added response multiple times (total count)
+    pub fn times(mut self, count: usize) -> Self {


In addition to documenting, I would probably panic on 0, this will be run in tests anyway and we want to make it as obvious as possible.

github-actions · 2025-04-25T13:44:48Z

A new generated diff is ready to view.

AWS SDK (ignoring whitespace)
Client Test (ignoring whitespace)
No codegen difference in the Server Test
No codegen difference in the Server Test Python
No codegen difference in the Server Test Typescript

A new doc preview is ready to view.

aajtodd added 16 commits April 22, 2025 10:20

rename aws-smithy-mocks-experimental to aws-smithy-mocks

3f4df6a

fix examples

00e619d

wip refactor to allow composing sequences

94206b4

fix interceptor

e2c2a56

cleanup tests

322f651

add additional tests and fix impl

26bf6f7

fix serve method to not take input

06f3b65

add lib documentation

e7222b7

move interceptor impl out of lib.rs

dd00aaf

wip integration tests

cdf713c

add failing test

ba06e21

add sequence builder API over serve function

3d11168

fix integration tests

59d068c

fix documentation and add retry test

ed7bbf8

update changelog and versions

9f52ab5

update changelog

5674bfa

aajtodd requested review from a team as code owners April 22, 2025 14:27

aajtodd added 2 commits April 22, 2025 12:30

fix nonexistent example reference

955c5b2

add back aws-smithy-mocks-experimental in deprecated form

a16ec90

rcoh reviewed Apr 23, 2025

View reviewed changes

landonxjames reviewed Apr 23, 2025

View reviewed changes

ysaito1001 reviewed Apr 23, 2025

View reviewed changes

aajtodd added 3 commits April 24, 2025 09:32

slurp readme instead, fix integration test deps

2550b54

Merge remote-tracking branch 'origin/main' into todaaron/promote-mocks

2702c3e

update lockfiles

5da3baa

jlizen reviewed Apr 24, 2025

View reviewed changes

panic on zero

338986a

ysaito1001 approved these changes Apr 25, 2025

View reviewed changes

rcoh approved these changes Apr 30, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

promote aws-smithy-mocks out of experimental #4098

promote aws-smithy-mocks out of experimental #4098

aajtodd commented Apr 22, 2025

github-actions bot commented Apr 22, 2025

rcoh left a comment

rcoh Apr 22, 2025

aajtodd Apr 24, 2025

rcoh Apr 30, 2025

rcoh Apr 22, 2025

landonxjames Apr 23, 2025

ysaito1001 Apr 23, 2025

aajtodd Apr 24, 2025

rcoh Apr 24, 2025 •

edited

Loading

aajtodd Apr 25, 2025

ysaito1001 left a comment

ysaito1001 Apr 23, 2025

ysaito1001 Apr 23, 2025

ysaito1001 Apr 23, 2025

aajtodd Apr 24, 2025

ysaito1001 Apr 24, 2025

jlizen Apr 24, 2025

github-actions bot commented Apr 24, 2025

jlizen commented Apr 24, 2025

jlizen Apr 24, 2025

jlizen Apr 24, 2025

github-actions bot commented Apr 25, 2025

promote aws-smithy-mocks out of experimental #4098

Are you sure you want to change the base?

promote aws-smithy-mocks out of experimental #4098

Conversation

aajtodd commented Apr 22, 2025

Motivation and Context

Description

Questions

Testing

Checklist

github-actions bot commented Apr 22, 2025

rcoh left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rcoh Apr 24, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ysaito1001 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented Apr 24, 2025

jlizen commented Apr 24, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented Apr 25, 2025

rcoh Apr 24, 2025 •

edited

Loading