chore(ci): run doctests

.github/workflows/ci.yml

@@ -21,7 +21,7 @@
         required: false
 
 jobs:
   CI:
     if: ${{ github.repository == 'googleapis/google-cloud-ruby' }}
     strategy:
       matrix:
@@ -41,7 +41,7 @@
           - os: ubuntu-latest
             ruby: "4.0"
             # (b/515549177): Disabled linkinator globally due to broken external doc links.
-            task: "--rubocop-toplevel --rubocop --build --yard"
+            task: "--rubocop-toplevel --rubocop --build --yard --doctest"
           - os: macos-latest
             ruby: "4.0"
             task: "--test"
@@ -52,20 +52,20 @@
     runs-on: ${{ matrix.os }}
     steps:
     - name: Checkout repo
       uses: actions/checkout@v6
     - name: Install Ruby ${{ matrix.ruby }}
       uses: ruby/setup-ruby@v1
       with:
         ruby-version: "${{ matrix.ruby }}"
     - name: Install NodeJS 18.x
       uses: actions/setup-node@v6
       with:
         node-version: "18.x || 24.x"
     - name: Install tools
       run: "gem install --no-document toys && npm install linkinator"
     - name: Test ${{ matrix.task }}
       run: |
         toys ci -v ${{ matrix.task }} --github-event-name=${{ github.event_name }} --github-event-payload=${{ github.event_path }} ${{ github.event.inputs.flags }}
     - name: Open Issues
       if: ${{ failure() }}
       env:

.toys/.lib/sample_loader.rb

@@ -214,7 +214,7 @@ def run **params
     private
 
     def camelize name
-      ::File.basename(name, ".rb").split("_").map(&:capitalize).join
+      ::File.basename(name, ".rb").split(/[_-]/).map(&:capitalize).join
     end
 
     def traverse_name mod, name, type

.toys/ci.rb

@@ -19,14 +19,15 @@
   "rubocop",
   "build",
   "yard",
+  "doctest",
   "linkinator",
   "acceptance",
   "conformance",
   "samples-main",
   "samples-latest",
 ].freeze
-OPTIONAL_TASKS = ["conformance"].freeze
-ISSUE_TASKS = ["bundle", "test", "rubocop", "build", "yard", "linkinator"].freeze
+OPTIONAL_TASKS = ["conformance", "doctest"].freeze
+ISSUE_TASKS = ["bundle", "test", "rubocop", "build", "yard", "doctest", "linkinator"].freeze
 FAILURES_REPORT_PATH = "tmp/ci-failures.json"
 
 desc "Run CI tasks."

google-cloud-bigquery/support/doctest_helper.rb

@@ -13,6 +13,8 @@
 # limitations under the License.
 
 require "minitest/focus"
+require "minitest/mock"
+require "ostruct"
 
 require "google/cloud/bigquery"
 require "google/cloud/storage"

google-cloud-bigtable/support/doctest_helper.rb

@@ -13,6 +13,8 @@
 # limitations under the License.
 
 require "minitest/focus"
+require "minitest/mock"
+require "ostruct"
 
 require "google/cloud/bigtable"
 require "grpc/errors"

google-cloud-datastore/support/doctest_helper.rb

@@ -13,6 +13,8 @@
 # limitations under the License.
 
 require "minitest/focus"
+require "minitest/mock"
+require "ostruct"
 
 require "grpc"
 require "google/cloud/datastore"

google-cloud-dns/support/doctest_helper.rb

@@ -13,6 +13,8 @@
 # limitations under the License.
 
 require "minitest/focus"
+require "minitest/mock"
+require "ostruct"
 
 require "google/cloud/dns"
 

google-cloud-error_reporting/support/doctest_helper.rb

@@ -13,6 +13,7 @@
 # limitations under the License.
 
 require "minitest/focus"
+require "minitest/mock"
 require "ostruct"
 
 require "google/cloud/error_reporting"

google-cloud-firestore/support/doctest_helper.rb

@@ -13,6 +13,8 @@
 # limitations under the License.
 
 require "minitest/focus"
+require "minitest/mock"
+require "ostruct"
 
 require "google/cloud/firestore"
 
@@ -64,7 +66,9 @@ def on_error &block
         def last_error
         end
       end
+      remove_const :DocumentListener if const_defined? :DocumentListener
       DocumentListener = StubbedListener
+      remove_const :QueryListener if const_defined? :QueryListener
       QueryListener = StubbedListener
     end
   end
@@ -89,6 +93,11 @@ def mock_firestore
   doctest.skip "Google::Cloud::Firestore::V1::FirestoreClient"
   doctest.skip "Google::Cloud::Firestore::V1beta1::FirestoreClient"
   doctest.skip "Google::Cloud::Firestore::Admin::V1::FirestoreAdminClient"
+  doctest.skip "#listen"
+  doctest.skip "#on_snapshot"
+  doctest.skip "Listener"
+  doctest.skip "Watch"
+  doctest.skip "Google::Cloud::Firestore::BulkWriter"
 
   doctest.before "Google::Cloud#firestore" do
     mock_firestore

google-cloud-logging/support/doctest_helper.rb

@@ -13,6 +13,8 @@
 # limitations under the License.
 
 require "minitest/focus"
+require "minitest/mock"
+require "ostruct"
 
 require "google/cloud/storage"
 require "google/cloud/logging"

google-cloud-pubsub/support/doctest_helper.rb

@@ -13,6 +13,7 @@
 # limitations under the License.
 
 require "minitest/focus"
+require "minitest/mock"
 require "ostruct"
 
 require "google/cloud/pubsub"
@@ -67,7 +68,7 @@ def stop! *_args
 def mock_pubsub
   Google::Cloud::PubSub.stub_new do |*args|
     credentials = OpenStruct.new(client: OpenStruct.new(updater_proc: Proc.new {}))
-    pubsub = Google::Cloud::PubSub::Project.new(Google::Cloud::PubSub::Service.new("my-project", credentials))
+    pubsub = Google::Cloud::PubSub::Project.new(Google::Cloud::PubSub::Service.new("my-project", credentials, logger: Google::Cloud::PubSub::InternalLogger.new(nil)))
 
     pubsub.service.mocked_topic_admin = Minitest::Mock.new
     pubsub.service.mocked_subscription_admin = Minitest::Mock.new
@@ -94,14 +95,14 @@ def mock_pubsub
 
   doctest.before "Google::Cloud" do
     mock_pubsub do |mock_topic_admin, mock_subscription_admin|
-      mock_topic_admin.expect :publish, OpenStruct.new(message_ids: ["1"]), [Hash]
+      mock_topic_admin.expect :publish_internal, OpenStruct.new(message_ids: ["1"]), [Hash]
       mock_topic_admin.expect :get_topic, topic_resp, topic: topic_path("my-topic")
     end
   end
 
   doctest.before "Google::Cloud::PubSub" do
     mock_pubsub do |mock_topic_admin, mock_subscription_admin|
-      mock_topic_admin.expect :publish, OpenStruct.new(message_ids: ["1"]), [Hash]
+      mock_topic_admin.expect :publish_internal, OpenStruct.new(message_ids: ["1"]), [Hash]
       mock_topic_admin.expect :get_topic, topic_resp, topic: topic_path("my-topic")
     end
   end
@@ -110,7 +111,7 @@ def mock_pubsub
 
   doctest.before "Google::Cloud::PubSub::Message" do
     mock_pubsub do |mock_topic_admin, mock_subscription_admin|
-      mock_topic_admin.expect :publish, OpenStruct.new(message_ids: ["1"]), [Hash]
+      mock_topic_admin.expect :publish_internal, OpenStruct.new(message_ids: ["1"]), [Hash]
       mock_topic_admin.expect :get_topic, topic_resp, topic: topic_path("my-topic")
       mock_subscription_admin.expect :get_subscription, subscription_resp, subscription: subscription_path("my-topic-sub")
       mock_subscription_admin.expect :streaming_pull, [OpenStruct.new(received_messages: [Google::Cloud::PubSub::V1::ReceivedMessage.new(ack_id: "2", message: pubsub_message)])].to_enum, [Enumerator, Hash]
@@ -125,7 +126,7 @@ def mock_pubsub
 
   doctest.before "Google::Cloud::PubSub::Project" do
     mock_pubsub do |mock_topic_admin, mock_subscription_admin|
-      mock_topic_admin.expect :publish, OpenStruct.new(message_ids: ["1"]), [Hash]
+      mock_topic_admin.expect :publish_internal, OpenStruct.new(message_ids: ["1"]), [Hash]
       mock_topic_admin.expect :get_topic, topic_resp, topic: topic_path("my-topic")
     end
   end
@@ -140,7 +141,7 @@ def mock_pubsub
       mock_subscription_admin.expect :streaming_pull, [].to_enum, [Enumerator, Hash]
       mock_subscription_admin.expect :streaming_pull, [].to_enum, [Enumerator, Hash]
       mock_subscription_admin.expect :streaming_pull, [].to_enum, [Enumerator, Hash]
-      mock_subscription_admin.expect :acknowledge, nil, ["projects/my-project/subscriptions/my-sub", ["2"], Hash]
+      mock_subscription_admin.expect :acknowledge_internal, nil, ["projects/my-project/subscriptions/my-sub", ["2"], Hash]
     end
   end
 
@@ -165,14 +166,14 @@ def mock_pubsub
       mock_subscription_admin.expect :streaming_pull, [].to_enum, [Enumerator, Hash]
       mock_subscription_admin.expect :streaming_pull, [].to_enum, [Enumerator, Hash]
       mock_subscription_admin.expect :streaming_pull, [].to_enum, [Enumerator, Hash]
-      mock_subscription_admin.expect :modify_ack_deadline, nil, [Hash]
+      mock_subscription_admin.expect :modify_ack_deadline_internal, nil, [Hash]
     end
   end
 
   doctest.before "Google::Cloud::PubSub::ReceivedMessage#reject!" do
     mock_pubsub do |mock_topic_admin, mock_subscription_admin|
       mock_subscription_admin.expect :get_subscription, subscription_resp, subscription: subscription_path("my-topic-sub")
-      mock_subscription_admin.expect :pull, OpenStruct.new(received_messages: [Google::Cloud::PubSub::V1::ReceivedMessage.new(ack_id: "2", message: pubsub_message)]), [Hash]
+      mock_subscription_admin.expect :pull_internal, OpenStruct.new(received_messages: [Google::Cloud::PubSub::V1::ReceivedMessage.new(ack_id: "2", message: pubsub_message)]), [Hash]
       mock_subscription_admin.expect :streaming_pull, [OpenStruct.new(received_messages: [Google::Cloud::PubSub::V1::ReceivedMessage.new(ack_id: "2", message: pubsub_message)])].to_enum, [Enumerator, Hash]
       mock_subscription_admin.expect :streaming_pull, [].to_enum, [Enumerator, Hash]
       mock_subscription_admin.expect :streaming_pull, [].to_enum, [Enumerator, Hash]
@@ -190,16 +191,16 @@ def mock_pubsub
       mock_subscription_admin.expect :streaming_pull, [].to_enum, [Enumerator, Hash]
       mock_subscription_admin.expect :streaming_pull, [].to_enum, [Enumerator, Hash]
       mock_subscription_admin.expect :streaming_pull, [].to_enum, [Enumerator, Hash]
-      mock_subscription_admin.expect :acknowledge, nil, [Hash]
+      mock_subscription_admin.expect :acknowledge_internal, nil, [Hash]
     end
   end
 
   doctest.before "Google::Cloud::PubSub::Subscriber#wait_for_messages" do
     mock_pubsub do |mock_topic_admin, mock_subscription_admin|
       mock_subscription_admin.expect :get_subscription, subscription_resp("my-topic-sub"), subscription: subscription_path("my-topic-sub")
-      mock_subscription_admin.expect :pull, OpenStruct.new(received_messages: [Google::Cloud::PubSub::V1::ReceivedMessage.new(ack_id: "2", message: pubsub_message)]),
+      mock_subscription_admin.expect :pull_internal, OpenStruct.new(received_messages: [Google::Cloud::PubSub::V1::ReceivedMessage.new(ack_id: "2", message: pubsub_message)]),
                              subscription: subscription_path("my-topic-sub"), max_messages: 100, return_immediately: false
-      mock_subscription_admin.expect :acknowledge, nil, subscription: subscription_path("my-topic-sub"), ack_ids: ["2"]
+      mock_subscription_admin.expect :acknowledge_internal, nil, subscription: subscription_path("my-topic-sub"), ack_ids: ["2"]
     end
   end
 
@@ -213,27 +214,27 @@ def mock_pubsub
   doctest.before "Google::Cloud::PubSub::Subscriber#pull@The `immediate: false` option is now recommended to avoid adverse impacts on pull operations:" do
      mock_pubsub do |mock_topic_admin, mock_subscription_admin|
      mock_subscription_admin.expect :get_subscription, subscription_resp("my-topic-sub"), subscription: subscription_path("my-topic-sub")
-     mock_subscription_admin.expect :pull, OpenStruct.new(received_messages: [Google::Cloud::PubSub::V1::ReceivedMessage.new(ack_id: "2", message: pubsub_message)]),
+     mock_subscription_admin.expect :pull_internal, OpenStruct.new(received_messages: [Google::Cloud::PubSub::V1::ReceivedMessage.new(ack_id: "2", message: pubsub_message)]),
                              subscription: subscription_path("my-topic-sub"), max_messages: 100, return_immediately: false
-     mock_subscription_admin.expect :acknowledge, nil, subscription: subscription_path("my-topic-sub"), ack_ids: ["2"]
+     mock_subscription_admin.expect :acknowledge_internal, nil, subscription: subscription_path("my-topic-sub"), ack_ids: ["2"]
     end
   end
 
   doctest.before "Google::Cloud::PubSub::Subscriber#pull@A maximum number of messages returned can also be specified:" do
     mock_pubsub do |mock_topic_admin, mock_subscription_admin|
       mock_subscription_admin.expect :get_subscription, subscription_resp("my-topic-sub"), subscription: subscription_path("my-topic-sub")
-      mock_subscription_admin.expect :pull, OpenStruct.new(received_messages: [Google::Cloud::PubSub::V1::ReceivedMessage.new(ack_id: "2", message: pubsub_message)]),
+      mock_subscription_admin.expect :pull_internal, OpenStruct.new(received_messages: [Google::Cloud::PubSub::V1::ReceivedMessage.new(ack_id: "2", message: pubsub_message)]),
                              subscription: subscription_path("my-topic-sub"), max_messages: 10, return_immediately: false
-      mock_subscription_admin.expect :acknowledge, nil, subscription: subscription_path("my-topic-sub"), ack_ids: ["2"]
+      mock_subscription_admin.expect :acknowledge_internal, nil, subscription: subscription_path("my-topic-sub"), ack_ids: ["2"]
     end
   end
 
   doctest.before "Google::Cloud::PubSub::Subscriber#modify_ack_deadline" do
     mock_pubsub do |mock_topic_admin, mock_subscription_admin|
       mock_subscription_admin.expect :get_subscription, subscription_resp, subscription: subscription_path("my-topic-sub")
-      mock_subscription_admin.expect :pull, OpenStruct.new(received_messages: [Google::Cloud::PubSub::V1::ReceivedMessage.new(ack_id: "2", message: pubsub_message)]),
+      mock_subscription_admin.expect :pull_internal, OpenStruct.new(received_messages: [Google::Cloud::PubSub::V1::ReceivedMessage.new(ack_id: "2", message: pubsub_message)]),
                              subscription: subscription_path("my-sub"), max_messages: 100, return_immediately: false
-      mock_subscription_admin.expect :modify_ack_deadline, nil, subscription: subscription_path("my-sub"), ack_ids: ["2"], ack_deadline_seconds: 120
+      mock_subscription_admin.expect :modify_ack_deadline_internal, nil, subscription: subscription_path("my-sub"), ack_ids: ["2"], ack_deadline_seconds: 120
 
 
     end
@@ -262,7 +263,7 @@ def mock_pubsub
       mock_subscription_admin.expect :streaming_pull, [].to_enum, [Enumerator, Hash]
       mock_subscription_admin.expect :streaming_pull, [].to_enum, [Enumerator, Hash]
       mock_subscription_admin.expect :streaming_pull, [].to_enum, [Enumerator, Hash]
-      mock_subscription_admin.expect :acknowledge, nil, ["projects/my-project/subscriptions/my-ordered-topic-sub", ["2"], Hash]
+      mock_subscription_admin.expect :acknowledge_internal, nil, ["projects/my-project/subscriptions/my-ordered-topic-sub", ["2"], Hash]
     end
   end
 
@@ -276,7 +277,7 @@ def mock_pubsub
       mock_subscription_admin.expect :streaming_pull, [].to_enum, [Enumerator, Hash]
       mock_subscription_admin.expect :streaming_pull, [].to_enum, [Enumerator, Hash]
       mock_subscription_admin.expect :streaming_pull, [].to_enum, [Enumerator, Hash]
-      mock_subscription_admin.expect :acknowledge, nil, [Hash]
+      mock_subscription_admin.expect :acknowledge_internal, nil, [Hash]
     end
   end
 
@@ -286,28 +287,34 @@ def mock_pubsub
   doctest.before "Google::Cloud::PubSub::Publisher" do
     mock_pubsub do |mock_topic_admin, mock_subscription_admin|
       mock_topic_admin.expect :get_topic, topic_resp, topic: topic_path("my-topic-only")
-      mock_topic_admin.expect :publish, OpenStruct.new(message_ids: ["1"]), [Hash]
+      mock_topic_admin.expect :publish_internal, OpenStruct.new(message_ids: ["1"]), [Hash]
+    end
+  end
+
+  doctest.before "Google::Cloud::PubSub::Publisher#reload!" do
+    mock_pubsub do |mock_topic_admin, mock_subscription_admin|
+      mock_topic_admin.expect :get_topic, topic_resp, topic: topic_path("my-topic")
     end
   end
 
   doctest.before "Google::Cloud::PubSub::Publisher#async_publisher" do
     mock_pubsub do |mock_topic_admin, mock_subscription_admin|
       mock_topic_admin.expect :get_topic, topic_resp, topic: topic_path("my-topic")
-      mock_topic_admin.expect :publish, OpenStruct.new(message_ids: ["1"]), [Hash]
+      mock_topic_admin.expect :publish_internal, OpenStruct.new(message_ids: ["1"]), [Hash]
     end
   end
 
   doctest.before "Google::Cloud::PubSub::Publisher#publish" do
     mock_pubsub do |mock_topic_admin, mock_subscription_admin|
       mock_topic_admin.expect :get_topic, topic_resp, topic: topic_path("my-topic")
-      mock_topic_admin.expect :publish, OpenStruct.new(message_ids: ["1"]), [Hash]
+      mock_topic_admin.expect :publish_internal, OpenStruct.new(message_ids: ["1"]), [Hash]
     end
   end
 
   doctest.before "Google::Cloud::PubSub::Publisher#publish@Additionally, a message can be published with attributes:" do
     mock_pubsub do |mock_topic_admin, mock_subscription_admin|
       mock_topic_admin.expect :get_topic, topic_resp, topic: topic_path("my-topic")
-      mock_topic_admin.expect :publish, OpenStruct.new(message_ids: ["1"]), [Hash]
+      mock_topic_admin.expect :publish_internal, OpenStruct.new(message_ids: ["1"]), [Hash]
     end
   end
 
@@ -319,14 +326,14 @@ def mock_pubsub
         pubsub_message("task 2 completed", { "foo" => "baz" }),
         pubsub_message("task 3 completed", { "foo" => "bif" })
       ]
-      mock_topic_admin.expect :publish, OpenStruct.new(message_ids: ["1", "2", "3"]), [Hash]
+      mock_topic_admin.expect :publish_internal, OpenStruct.new(message_ids: ["1", "2", "3"]), [Hash]
     end
   end
 
   doctest.before "Google::Cloud::PubSub::Publisher#publish@Ordered messages are supported using ordering_key:" do
     mock_pubsub do |mock_topic_admin, mock_subscription_admin|
       mock_topic_admin.expect :get_topic, topic_resp, topic: topic_path("my-ordered-topic")
-      mock_topic_admin.expect :publish, OpenStruct.new(message_ids: ["1"]), [Hash]
+      mock_topic_admin.expect :publish_internal, OpenStruct.new(message_ids: ["1"]), [Hash]
     end
   end
 
@@ -347,7 +354,7 @@ def mock_pubsub
         pubsub_message("task 2 completed", { "foo" => "baz" }),
         pubsub_message("task 3 completed", { "foo" => "bif" })
       ]
-      mock_topic_admin.expect :publish, OpenStruct.new(message_ids: ["1", "2", "3"]), [Hash]
+      mock_topic_admin.expect :publish_internal, OpenStruct.new(message_ids: ["1", "2", "3"]), [Hash]
     end
   end
 end

google-cloud-storage/support/doctest_helper.rb

@@ -13,6 +13,8 @@
 # limitations under the License.
 
 require "minitest/focus"
+require "minitest/mock"
+require "ostruct"
 
 require "google/cloud/storage"
 require "google/cloud/pubsub"

google-cloud-trace/support/doctest_helper.rb

@@ -16,6 +16,8 @@
 require "google/cloud/trace"
 require "minitest/rg"
 require "minitest/focus"
+require "minitest/mock"
+require "ostruct"
 require "active_record"
 
 module Google