Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: document Start and Await methods and mocks #14375

Merged
merged 7 commits into from
Jun 27, 2024
Merged

doc: document Start and Await methods and mocks #14375

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
618569a
doc: document Start and Await methods and mocks
scotthart Jun 26, 2024
fbdbf36
generated golden code
scotthart Jun 26, 2024
683ed19
generated service code
scotthart Jun 26, 2024
c6e6836
change copydoc to copybrief
scotthart Jun 26, 2024
644f778
regenerate
scotthart Jun 26, 2024
8f0e28b
address review comments
scotthart Jun 27, 2024
86437a0
regenerate code
scotthart Jun 27, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
12 changes: 12 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,18 @@ breaking changes in the upcoming 3.x release. This release is scheduled for

## v2.26.0 - TBD

### BREAKING TESTING CHANGES
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: doesn't matter, but line break?


If you don't mock Long Running Operations (LRO) in your tests, then these
changes will not affect you.

With the addition of new methods to support starting Long Running Operations
(LRO) synchronously and awaiting their completion separately, the overload set
for the preexisting LRO methods have been expanded. Uses of `EXPECT_CALL` that
do not have matchers for the arguments will be ambiguous. To quickly remedy this
change instances of `EXPECT_CALL(*mock, Method)` to
`EXPECT_CALL(*mock, Method(::testing::_))`.

### New Libraries

We are happy to announce the following GA libraries. Unless specifically noted,
Expand Down
144 changes: 144 additions & 0 deletions generator/integration_tests/golden/v1/golden_thing_admin_client.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -215,6 +215,17 @@ class GoldenThingAdminClient {
future<StatusOr<google::test::admin::database::v1::Database>>
CreateDatabase(std::string const& parent, std::string const& create_statement, Options opts = {});

// clang-format off
///
/// @copybrief CreateDatabase
///
/// Specifying the [`NoAwaitTag`] immediately returns the
/// [`google::longrunning::Operation`] that corresponds to the Long Running
/// Operation that has been started. No polling for operation status occurs.
///
/// [`NoAwaitTag`]: @ref google::cloud::NoAwaitTag
///
// clang-format on
StatusOr<google::longrunning::Operation>
CreateDatabase(ExperimentalTag, NoAwaitTag, std::string const& parent, std::string const& create_statement, Options opts = {});

Expand Down Expand Up @@ -266,9 +277,29 @@ class GoldenThingAdminClient {
future<StatusOr<google::test::admin::database::v1::Database>>
CreateDatabase(google::test::admin::database::v1::CreateDatabaseRequest const& request, Options opts = {});

// clang-format off
///
/// @copybrief CreateDatabase
///
/// Specifying the [`NoAwaitTag`] immediately returns the
/// [`google::longrunning::Operation`] that corresponds to the Long Running
/// Operation that has been started. No polling for operation status occurs.
///
/// [`NoAwaitTag`]: @ref google::cloud::NoAwaitTag
///
// clang-format on
StatusOr<google::longrunning::Operation>
CreateDatabase(ExperimentalTag, NoAwaitTag, google::test::admin::database::v1::CreateDatabaseRequest const& request, Options opts = {});

// clang-format off
///
/// @copybrief CreateDatabase
///
/// This method accepts a `google::longrunning::Operation` that corresponds
/// to a previously started Long Running Operation (LRO) and polls the status
/// of the LRO in the background.
///
// clang-format on
future<StatusOr<google::test::admin::database::v1::Database>>
CreateDatabase(ExperimentalTag, google::longrunning::Operation const& operation, Options opts = {});

Expand Down Expand Up @@ -370,6 +401,17 @@ class GoldenThingAdminClient {
future<StatusOr<google::test::admin::database::v1::UpdateDatabaseDdlMetadata>>
UpdateDatabaseDdl(std::string const& database, std::vector<std::string> const& statements, Options opts = {});

// clang-format off
///
/// @copybrief UpdateDatabaseDdl
///
/// Specifying the [`NoAwaitTag`] immediately returns the
/// [`google::longrunning::Operation`] that corresponds to the Long Running
/// Operation that has been started. No polling for operation status occurs.
///
/// [`NoAwaitTag`]: @ref google::cloud::NoAwaitTag
///
// clang-format on
StatusOr<google::longrunning::Operation>
UpdateDatabaseDdl(ExperimentalTag, NoAwaitTag, std::string const& database, std::vector<std::string> const& statements, Options opts = {});

Expand Down Expand Up @@ -419,9 +461,29 @@ class GoldenThingAdminClient {
future<StatusOr<google::test::admin::database::v1::UpdateDatabaseDdlMetadata>>
UpdateDatabaseDdl(google::test::admin::database::v1::UpdateDatabaseDdlRequest const& request, Options opts = {});

// clang-format off
///
/// @copybrief UpdateDatabaseDdl
///
/// Specifying the [`NoAwaitTag`] immediately returns the
/// [`google::longrunning::Operation`] that corresponds to the Long Running
/// Operation that has been started. No polling for operation status occurs.
///
/// [`NoAwaitTag`]: @ref google::cloud::NoAwaitTag
///
// clang-format on
StatusOr<google::longrunning::Operation>
UpdateDatabaseDdl(ExperimentalTag, NoAwaitTag, google::test::admin::database::v1::UpdateDatabaseDdlRequest const& request, Options opts = {});

// clang-format off
///
/// @copybrief UpdateDatabaseDdl
///
/// This method accepts a `google::longrunning::Operation` that corresponds
/// to a previously started Long Running Operation (LRO) and polls the status
/// of the LRO in the background.
///
// clang-format on
future<StatusOr<google::test::admin::database::v1::UpdateDatabaseDdlMetadata>>
UpdateDatabaseDdl(ExperimentalTag, google::longrunning::Operation const& operation, Options opts = {});

Expand Down Expand Up @@ -842,6 +904,17 @@ class GoldenThingAdminClient {
future<StatusOr<google::test::admin::database::v1::Backup>>
CreateBackup(std::string const& parent, google::test::admin::database::v1::Backup const& backup, std::string const& backup_id, Options opts = {});

// clang-format off
///
/// @copybrief CreateBackup
///
/// Specifying the [`NoAwaitTag`] immediately returns the
/// [`google::longrunning::Operation`] that corresponds to the Long Running
/// Operation that has been started. No polling for operation status occurs.
///
/// [`NoAwaitTag`]: @ref google::cloud::NoAwaitTag
///
// clang-format on
StatusOr<google::longrunning::Operation>
CreateBackup(ExperimentalTag, NoAwaitTag, std::string const& parent, google::test::admin::database::v1::Backup const& backup, std::string const& backup_id, Options opts = {});

Expand Down Expand Up @@ -897,9 +970,29 @@ class GoldenThingAdminClient {
future<StatusOr<google::test::admin::database::v1::Backup>>
CreateBackup(google::test::admin::database::v1::CreateBackupRequest const& request, Options opts = {});

// clang-format off
///
/// @copybrief CreateBackup
///
/// Specifying the [`NoAwaitTag`] immediately returns the
/// [`google::longrunning::Operation`] that corresponds to the Long Running
/// Operation that has been started. No polling for operation status occurs.
///
/// [`NoAwaitTag`]: @ref google::cloud::NoAwaitTag
///
// clang-format on
StatusOr<google::longrunning::Operation>
CreateBackup(ExperimentalTag, NoAwaitTag, google::test::admin::database::v1::CreateBackupRequest const& request, Options opts = {});

// clang-format off
///
/// @copybrief CreateBackup
///
/// This method accepts a `google::longrunning::Operation` that corresponds
/// to a previously started Long Running Operation (LRO) and polls the status
/// of the LRO in the background.
///
// clang-format on
future<StatusOr<google::test::admin::database::v1::Backup>>
CreateBackup(ExperimentalTag, google::longrunning::Operation const& operation, Options opts = {});

Expand Down Expand Up @@ -1222,6 +1315,17 @@ class GoldenThingAdminClient {
future<StatusOr<google::test::admin::database::v1::Database>>
RestoreDatabase(std::string const& parent, std::string const& database_id, std::string const& backup, Options opts = {});

// clang-format off
///
/// @copybrief RestoreDatabase
///
/// Specifying the [`NoAwaitTag`] immediately returns the
/// [`google::longrunning::Operation`] that corresponds to the Long Running
/// Operation that has been started. No polling for operation status occurs.
///
/// [`NoAwaitTag`]: @ref google::cloud::NoAwaitTag
///
// clang-format on
StatusOr<google::longrunning::Operation>
RestoreDatabase(ExperimentalTag, NoAwaitTag, std::string const& parent, std::string const& database_id, std::string const& backup, Options opts = {});

Expand Down Expand Up @@ -1282,9 +1386,29 @@ class GoldenThingAdminClient {
future<StatusOr<google::test::admin::database::v1::Database>>
RestoreDatabase(google::test::admin::database::v1::RestoreDatabaseRequest const& request, Options opts = {});

// clang-format off
///
/// @copybrief RestoreDatabase
///
/// Specifying the [`NoAwaitTag`] immediately returns the
/// [`google::longrunning::Operation`] that corresponds to the Long Running
/// Operation that has been started. No polling for operation status occurs.
///
/// [`NoAwaitTag`]: @ref google::cloud::NoAwaitTag
///
// clang-format on
StatusOr<google::longrunning::Operation>
RestoreDatabase(ExperimentalTag, NoAwaitTag, google::test::admin::database::v1::RestoreDatabaseRequest const& request, Options opts = {});

// clang-format off
///
/// @copybrief RestoreDatabase
///
/// This method accepts a `google::longrunning::Operation` that corresponds
/// to a previously started Long Running Operation (LRO) and polls the status
/// of the LRO in the background.
///
// clang-format on
future<StatusOr<google::test::admin::database::v1::Database>>
RestoreDatabase(ExperimentalTag, google::longrunning::Operation const& operation, Options opts = {});

Expand Down Expand Up @@ -1509,9 +1633,29 @@ class GoldenThingAdminClient {
future<StatusOr<google::test::admin::database::v1::Database>>
LongRunningWithoutRouting(google::test::admin::database::v1::RestoreDatabaseRequest const& request, Options opts = {});

// clang-format off
///
/// @copybrief LongRunningWithoutRouting
///
/// Specifying the [`NoAwaitTag`] immediately returns the
/// [`google::longrunning::Operation`] that corresponds to the Long Running
/// Operation that has been started. No polling for operation status occurs.
///
/// [`NoAwaitTag`]: @ref google::cloud::NoAwaitTag
///
// clang-format on
StatusOr<google::longrunning::Operation>
LongRunningWithoutRouting(ExperimentalTag, NoAwaitTag, google::test::admin::database::v1::RestoreDatabaseRequest const& request, Options opts = {});

// clang-format off
///
/// @copybrief LongRunningWithoutRouting
///
/// This method accepts a `google::longrunning::Operation` that corresponds
/// to a previously started Long Running Operation (LRO) and polls the status
/// of the LRO in the background.
///
// clang-format on
future<StatusOr<google::test::admin::database::v1::Database>>
LongRunningWithoutRouting(ExperimentalTag, google::longrunning::Operation const& operation, Options opts = {});

Expand Down
15 changes: 15 additions & 0 deletions generator/integration_tests/golden/v1/mocks/mock_golden_thing_admin_connection.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,9 @@ class MockGoldenThingAdminConnection : public golden_v1::GoldenThingAdminConnect
ListDatabases,
(google::test::admin::database::v1::ListDatabasesRequest request), (override));

/// Due to additional overloads for this method
/// `EXPECT_CALL(*mock, CreateDatabase)` is now ambiguous. Use
/// `EXPECT_CALL(*mock, CreateDatabase(::testing::_))` instead.
MOCK_METHOD(future<StatusOr<google::test::admin::database::v1::Database>>,
CreateDatabase,
(google::test::admin::database::v1::CreateDatabaseRequest const& request), (override));
Expand All @@ -66,6 +69,9 @@ class MockGoldenThingAdminConnection : public golden_v1::GoldenThingAdminConnect
GetDatabase,
(google::test::admin::database::v1::GetDatabaseRequest const& request), (override));

/// Due to additional overloads for this method
/// `EXPECT_CALL(*mock, UpdateDatabaseDdl)` is now ambiguous. Use
/// `EXPECT_CALL(*mock, UpdateDatabaseDdl(::testing::_))` instead.
MOCK_METHOD(future<StatusOr<google::test::admin::database::v1::UpdateDatabaseDdlMetadata>>,
UpdateDatabaseDdl,
(google::test::admin::database::v1::UpdateDatabaseDdlRequest const& request), (override));
Expand Down Expand Up @@ -98,6 +104,9 @@ class MockGoldenThingAdminConnection : public golden_v1::GoldenThingAdminConnect
TestIamPermissions,
(google::iam::v1::TestIamPermissionsRequest const& request), (override));

/// Due to additional overloads for this method
/// `EXPECT_CALL(*mock, CreateBackup)` is now ambiguous. Use
/// `EXPECT_CALL(*mock, CreateBackup(::testing::_))` instead.
MOCK_METHOD(future<StatusOr<google::test::admin::database::v1::Backup>>,
CreateBackup,
(google::test::admin::database::v1::CreateBackupRequest const& request), (override));
Expand Down Expand Up @@ -126,6 +135,9 @@ class MockGoldenThingAdminConnection : public golden_v1::GoldenThingAdminConnect
ListBackups,
(google::test::admin::database::v1::ListBackupsRequest request), (override));

/// Due to additional overloads for this method
/// `EXPECT_CALL(*mock, RestoreDatabase)` is now ambiguous. Use
/// `EXPECT_CALL(*mock, RestoreDatabase(::testing::_))` instead.
MOCK_METHOD(future<StatusOr<google::test::admin::database::v1::Database>>,
RestoreDatabase,
(google::test::admin::database::v1::RestoreDatabaseRequest const& request), (override));
Expand All @@ -146,6 +158,9 @@ class MockGoldenThingAdminConnection : public golden_v1::GoldenThingAdminConnect
ListBackupOperations,
(google::test::admin::database::v1::ListBackupOperationsRequest request), (override));

/// Due to additional overloads for this method
/// `EXPECT_CALL(*mock, LongRunningWithoutRouting)` is now ambiguous. Use
/// `EXPECT_CALL(*mock, LongRunningWithoutRouting(::testing::_))` instead.
MOCK_METHOD(future<StatusOr<google::test::admin::database::v1::Database>>,
LongRunningWithoutRouting,
(google::test::admin::database::v1::RestoreDatabaseRequest const& request), (override));
Expand Down
3 changes: 3 additions & 0 deletions generator/integration_tests/golden/v1/mocks/mock_request_id_connection.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,9 @@ class MockRequestIdServiceConnection : public golden_v1::RequestIdServiceConnect
CreateFoo,
(google::test::requestid::v1::CreateFooRequest const& request), (override));

/// Due to additional overloads for this method
/// `EXPECT_CALL(*mock, RenameFoo)` is now ambiguous. Use
/// `EXPECT_CALL(*mock, RenameFoo(::testing::_))` instead.
MOCK_METHOD(future<StatusOr<google::test::requestid::v1::Foo>>,
RenameFoo,
(google::test::requestid::v1::RenameFooRequest const& request), (override));
Expand Down
31 changes: 31 additions & 0 deletions generator/integration_tests/golden/v1/request_id_client.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -175,6 +175,17 @@ class RequestIdServiceClient {
future<StatusOr<google::test::requestid::v1::Foo>>
RenameFoo(std::string const& name, std::string const& destination_foo_id, Options opts = {});

// clang-format off
///
/// @copybrief RenameFoo
///
/// Specifying the [`NoAwaitTag`] immediately returns the
/// [`google::longrunning::Operation`] that corresponds to the Long Running
/// Operation that has been started. No polling for operation status occurs.
///
/// [`NoAwaitTag`]: @ref google::cloud::NoAwaitTag
///
// clang-format on
StatusOr<google::longrunning::Operation>
RenameFoo(ExperimentalTag, NoAwaitTag, std::string const& name, std::string const& destination_foo_id, Options opts = {});

Expand Down Expand Up @@ -215,9 +226,29 @@ class RequestIdServiceClient {
future<StatusOr<google::test::requestid::v1::Foo>>
RenameFoo(google::test::requestid::v1::RenameFooRequest const& request, Options opts = {});

// clang-format off
///
/// @copybrief RenameFoo
///
/// Specifying the [`NoAwaitTag`] immediately returns the
/// [`google::longrunning::Operation`] that corresponds to the Long Running
/// Operation that has been started. No polling for operation status occurs.
///
/// [`NoAwaitTag`]: @ref google::cloud::NoAwaitTag
///
// clang-format on
StatusOr<google::longrunning::Operation>
RenameFoo(ExperimentalTag, NoAwaitTag, google::test::requestid::v1::RenameFooRequest const& request, Options opts = {});

// clang-format off
///
/// @copybrief RenameFoo
///
/// This method accepts a `google::longrunning::Operation` that corresponds
/// to a previously started Long Running Operation (LRO) and polls the status
/// of the LRO in the background.
///
// clang-format on
future<StatusOr<google::test::requestid::v1::Foo>>
RenameFoo(ExperimentalTag, google::longrunning::Operation const& operation, Options opts = {});

Expand Down
3 changes: 3 additions & 0 deletions generator/internal/client_generator.cc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -176,6 +176,7 @@ R"""( std::unique_ptr<::google::cloud::AsyncStreamingReadWriteRpc<
// clang-format on
{method_string},
{"\n"},
{FormatStartMethodComments()},
{IsResponseTypeEmpty,
// clang-format off
" Status\n",
Expand Down Expand Up @@ -267,6 +268,7 @@ R"""( std::unique_ptr<::google::cloud::AsyncStreamingReadWriteRpc<
" future<StatusOr<$longrunning_deduced_response_type$>>\n"},
{" $method_name$($request_type$ const& request, Options opts = {});\n"},
{"\n"},
{FormatStartMethodComments()},
// clang-format on
{IsResponseTypeEmpty,
// clang-format off
Expand All @@ -276,6 +278,7 @@ R"""( std::unique_ptr<::google::cloud::AsyncStreamingReadWriteRpc<
"NoAwaitTag, "
"$request_type$ const& request, Options opts = {});\n\n"},
// clang-format on
{FormatAwaitMethodComments()},
{IsResponseTypeEmpty,
// clang-format off
" future<Status>\n",
Expand Down
Loading
Loading