tests: Document ClientId and migrate its tests to minitest (#441)

lib/googleauth/client_id.rb

@@ -17,37 +17,52 @@
 
 module Google
   module Auth
-    # Representation of an application's identity for user authorization
-    # flows.
+    ##
+    # Representation of an application's identity for user authorization flows.
+    #
     class ClientId
+      # Toplevel JSON key for the an installed app configuration.
+      # Must include client_id and client_secret subkeys if present.
       INSTALLED_APP = "installed".freeze
+      # Toplevel JSON key for the a webapp configuration.
+      # Must include client_id and client_secret subkeys if present.
       WEB_APP = "web".freeze
+      # JSON key for the client ID within an app configuration.
       CLIENT_ID = "client_id".freeze
+      # JSON key for the client secret within an app configuration.
       CLIENT_SECRET = "client_secret".freeze
+      # An error message raised when none of the expected toplevel properties
+      # can be found.
       MISSING_TOP_LEVEL_ELEMENT_ERROR =
         "Expected top level property 'installed' or 'web' to be present.".freeze
 
+      ##
       # Text identifier of the client ID
       # @return [String]
+      #
       attr_reader :id
 
+      ##
       # Secret associated with the client ID
       # @return [String]
+      #
       attr_reader :secret
 
       class << self
         attr_accessor :default
       end
 
-      # Initialize the Client ID
+      ##
+      # Initialize the Client ID. Both id and secret must be non-nil.
       #
       # @param [String] id
       #  Text identifier of the client ID
       # @param [String] secret
       #  Secret associated with the client ID
-      # @note Direction instantion is discouraged to avoid embedding IDs
-      #       & secrets in source. See {#from_file} to load from
+      # @note Direct instantiation is discouraged to avoid embedding IDs
+      #       and secrets in source. See {#from_file} to load from
       #       `client_secrets.json` files.
+      #
       def initialize id, secret
         CredentialsLoader.warn_if_cloud_sdk_credentials id
         raise "Client id can not be nil" if id.nil?
@@ -56,12 +71,14 @@ def initialize id, secret
         @secret = secret
       end
 
+      ##
       # Constructs a Client ID from a JSON file downloaded from the
       # Google Developers Console.
       #
       # @param [String, File] file
       #  Path of file to read from
       # @return [Google::Auth::ClientID]
+      #
       def self.from_file file
         raise "File can not be nil." if file.nil?
         File.open file.to_s do |f|
@@ -71,13 +88,14 @@ def self.from_file file
         end
       end
 
+      ##
       # Constructs a Client ID from a previously loaded JSON file. The hash
-      # structure should
-      # match the expected JSON format.
+      # structure should match the expected JSON format.
       #
       # @param [hash] config
       #  Parsed contents of the JSON file
       # @return [Google::Auth::ClientID]
+      #
       def self.from_hash config
         raise "Hash can not be nil." if config.nil?
         raw_detail = config[INSTALLED_APP] || config[WEB_APP]

test/client_id_test.rb

@@ -0,0 +1,153 @@
+# Copyright 2023 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require "helper"
+require "fakefs/safe"
+
+describe Google::Auth::ClientId do
+  # A set of validity checks for a loaded ClientId.
+  # This module can be included in any spec that defines `config`.
+  client_id_load_checks = Module.new do
+    def self.included spec
+      # Define a module with some checks that a client ID is valid.
+      # Memoize because this included hook gets called multiple times.
+      valid_config_checks = @valid_config_checks ||= Module.new do
+        extend Minitest::Spec::DSL
+
+        it "should include a valid id" do
+          _(client_id.id).must_equal "abc@example.com"
+        end
+
+        it "should include a valid secret" do
+          _(client_id.secret).must_equal "notasecret"
+        end
+      end
+
+      # Add these describe blocks to any spec class that includes the
+      # client_id_load_checks module. Each describe block, in turn, includes
+      # the valid_config_checks module defined above.
+      spec.instance_eval do
+        describe "loaded from hash" do
+          let(:client_id) { Google::Auth::ClientId.from_hash config }
+          include valid_config_checks
+        end
+
+        describe "loaded from file" do
+          file_path = "/client_secrets.json"
+          let :client_id do
+            FakeFS do
+              content = MultiJson.dump config
+              File.write file_path, content
+              Google::Auth::ClientId.from_file file_path
+            end
+          end
+          include valid_config_checks
+        end
+      end
+    end
+  end
+
+  describe "with web config" do
+    let :config do
+      {
+        "web" => {
+          "client_id"     => "abc@example.com",
+          "client_secret" => "notasecret"
+        }
+      }
+    end
+    include client_id_load_checks
+  end
+
+  describe "with installed app config" do
+    let :config do
+      {
+        "installed" => {
+          "client_id"     => "abc@example.com",
+          "client_secret" => "notasecret"
+        }
+      }
+    end
+    include client_id_load_checks
+  end
+
+  describe "with missing top level property" do
+    let :config do
+      {
+        "notvalid" => {
+          "client_id"     => "abc@example.com",
+          "client_secret" => "notasecret"
+        }
+      }
+    end
+
+    it "should raise error" do
+      error = assert_raises do
+        Google::Auth::ClientId.from_hash config
+      end
+      assert_match(/Expected top level property/, error.message)
+    end
+  end
+
+  describe "with missing client id" do
+    let :config do
+      {
+        "web" => {
+          "client_secret" => "notasecret"
+        }
+      }
+    end
+
+    it "should raise error" do
+      error = assert_raises do
+        Google::Auth::ClientId.from_hash config
+      end
+      assert_match(/Client id can not be nil/, error.message)
+    end
+  end
+
+  describe "with missing client secret" do
+    let :config do
+      {
+        "web" => {
+          "client_id" => "abc@example.com"
+        }
+      }
+    end
+
+    it "should raise error" do
+      error = assert_raises do
+        Google::Auth::ClientId.from_hash config
+      end
+      assert_match(/Client secret can not be nil/, error.message)
+    end
+  end
+
+  describe "with cloud sdk credentials" do
+    let :config do
+      {
+        "web" => {
+          "client_id"     => Google::Auth::CredentialsLoader::CLOUD_SDK_CLIENT_ID,
+          "client_secret" => "notasecret"
+        }
+      }
+    end
+
+    it "should raise warning" do
+      assert_output nil, "#{Google::Auth::CredentialsLoader::CLOUD_SDK_CREDENTIALS_WARNING}\n" do
+        Google::Auth::ClientId.from_hash config
+      end
+    end
+  end
+end