docs(storage): user guide for mocking `Storage` by dbolduc · Pull Request #3483 · googleapis/google-cloud-rust

dbolduc · 2025-10-07T21:15:11Z

codecov · 2025-10-07T21:23:21Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.86%. Comparing base (a1afde2) to head (f9b01b1).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3483      +/-   ##
==========================================
+ Coverage   95.84%   95.86%   +0.02%     
==========================================
  Files         120      120              
  Lines        4789     4789              
==========================================
+ Hits         4590     4591       +1     
+ Misses        199      198       -1

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

coryan · 2025-10-08T18:37:27Z

guide/src/storage/mocking.md

+- Why the design of the `Storage` client deviates from the design of other
+  Google Cloud clients
+- How to write testable interfaces using the `Storage` client
+- How to mock reads
+- How to mock writes


I think the why is important, but tutorials / guides should emphasize how to do things... Why is for "in-depth guides":

Suggested change

- Why the design of the `Storage` client deviates from the design of other

Google Cloud clients

- How to write testable interfaces using the `Storage` client

- How to mock reads

- How to mock writes

- How to write testable interfaces using the `Storage` client

- How to mock reads

- How to mock writes

- Why the design of the `Storage` client deviates from the design of other

Google Cloud clients

coryan · 2025-10-08T18:37:46Z

guide/src/storage/mocking.md

+mocking guide (which applies to the `StorageControl` client), see
+[How to write tests using a client](../mock_a_client.md).
+
+## Design rationale


Consider moving this to the end or even a separate page.

coryan · 2025-10-08T18:38:38Z

guide/src/storage/mocking.md

+forward requests from the client to their stub (which could be the real
+implementation or a mock).
+
+Because dynamic dispatch is used, the exact type of the stub does not need to be


Suggested change

Because dynamic dispatch is used, the exact type of the stub does not need to be

Because these clients use dynamic dispatch, the exact type of the stub does not need to be

coryan · 2025-10-08T18:38:59Z

guide/src/storage/mocking.md

+implementation or a mock).
+
+Because dynamic dispatch is used, the exact type of the stub does not need to be
+known by the compiler. The clients do not need to be templated on their stub.


"templated" is a C++-ism, "generic on"?

coryan · 2025-10-08T18:40:26Z

guide/src/storage/mocking.md

+Applications that need to test their code, should write their interfaces in
+terms of the generic `T`.


Suggested change

Applications that need to test their code, should write their interfaces in

terms of the generic `T`.

Applications that need to test their code, should write their interfaces in

terms of the generic `T` with the correct constraints.

or maybe "constrained as needed"?

coryan · 2025-10-08T18:41:46Z

guide/src/storage/mocking.md

+
+## Mocking reads
+
+Let's say we have an application function which downloads an object and counts


Check the style guide. Google docs use the second person singular... "In this guide you will test an application function ..."

Used second person, singular.

I like saying "we" because it makes me feel like I am on the same team as the reader. It's fine though.

coryan · 2025-10-08T18:42:20Z

guide/src/storage/mocking.md

+We want to test our code against a known response from the server. We can do
+this by faking the `ReadObjectResponse`.


Here too, change to use "you".

coryan · 2025-10-08T18:44:44Z

guide/src/storage/mocking.md

+{{#rustdoc_include ../../samples/tests/storage/mocking.rs:fake-read-object-resp}}
+```
+
+We define the mock as usual, using `mockall`.


I am not sure "as usual" is quite right. It is usual for us in this project, applications may use something else. Maybe "This guide uses the mockall crate to create a mock. You can use a different crate in your tests" ?

Done. FWIW, I think mockall is the main mocking framework in the ecosystem.

dbolduc

PTAL

dbolduc · 2025-10-08T19:53:07Z

guide/src/storage/mocking.md

+- Why the design of the `Storage` client deviates from the design of other
+  Google Cloud clients
+- How to write testable interfaces using the `Storage` client
+- How to mock reads
+- How to mock writes


dbolduc · 2025-10-08T19:53:14Z

guide/src/storage/mocking.md

+mocking guide (which applies to the `StorageControl` client), see
+[How to write tests using a client](../mock_a_client.md).
+
+## Design rationale


dbolduc · 2025-10-08T19:53:21Z

guide/src/storage/mocking.md

+forward requests from the client to their stub (which could be the real
+implementation or a mock).
+
+Because dynamic dispatch is used, the exact type of the stub does not need to be


dbolduc · 2025-10-08T19:53:26Z

guide/src/storage/mocking.md

+implementation or a mock).
+
+Because dynamic dispatch is used, the exact type of the stub does not need to be
+known by the compiler. The clients do not need to be templated on their stub.


dbolduc · 2025-10-08T19:53:32Z

guide/src/storage/mocking.md

+Applications that need to test their code, should write their interfaces in
+terms of the generic `T`.


dbolduc · 2025-10-08T19:54:06Z

guide/src/storage/mocking.md

+
+## Mocking reads
+
+Let's say we have an application function which downloads an object and counts


Used second person, singular.

I like saying "we" because it makes me feel like I am on the same team as the reader. It's fine though.

dbolduc · 2025-10-08T19:59:56Z

guide/src/storage/mocking.md

+We want to test our code against a known response from the server. We can do
+this by faking the `ReadObjectResponse`.


dbolduc · 2025-10-08T20:00:00Z

guide/src/storage/mocking.md

+{{#rustdoc_include ../../samples/tests/storage/mocking.rs:fake-read-object-resp}}
+```
+
+We define the mock as usual, using `mockall`.


Done. FWIW, I think mockall is the main mocking framework in the ecosystem.

product-auto-label bot added the api: storage Issues related to the Cloud Storage API. label Oct 7, 2025

dbolduc force-pushed the storage-mocking-user-guide branch from 2a3e083 to 03a10cf Compare October 8, 2025 15:08

dbolduc marked this pull request as ready for review October 8, 2025 15:31

dbolduc requested a review from a team October 8, 2025 15:31

coryan requested changes Oct 8, 2025

View reviewed changes

dbolduc added 3 commits October 8, 2025 16:00

docs(storage): user guide for mocking Storage

62436ce

fix lint

fcb2776

address review comments

f9b01b1

dbolduc force-pushed the storage-mocking-user-guide branch from 03a10cf to f9b01b1 Compare October 8, 2025 20:01

dbolduc commented Oct 8, 2025

View reviewed changes

coryan approved these changes Oct 8, 2025

View reviewed changes

dbolduc merged commit c341a0e into googleapis:main Oct 9, 2025
24 checks passed

dbolduc deleted the storage-mocking-user-guide branch October 10, 2025 15:59

	Because dynamic dispatch is used, the exact type of the stub does not need to be
	Because these clients use dynamic dispatch, the exact type of the stub does not need to be

		Applications that need to test their code, should write their interfaces in
		terms of the generic `T`.


		## Mocking reads

		Let's say we have an application function which downloads an object and counts

		We want to test our code against a known response from the server. We can do
		this by faking the `ReadObjectResponse`.

Conversation

dbolduc commented Oct 7, 2025

Uh oh!

codecov bot commented Oct 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dbolduc left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

codecov bot commented Oct 7, 2025 •

edited

Loading