my_api_client 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eb13e4cf8d1a3d9b3a1bbb5154b695493384c1d94377d8260f0ababa59d42c55
-  data.tar.gz: 52df7eb8caa4ad533ce6130078da94da6ff59924efbb5f52c441225114c03fcb
+  metadata.gz: 8f79acd9dda7576ad4ef44c65c31d5c6fd4c3ebe64dc6ce8106bd81097931b84
+  data.tar.gz: ff17d603eabd348ff39e7c209e3fa601bcbaeee1a97beeda73e46b9c6d16eda4
 SHA512:
-  metadata.gz: b073a7464c97c5d2b9181cb0ed5e1de4296a808a0668d3bb9bf1357f4bad591a24c30ff7935e88383a934fe6867bca86878b673ca51898678ec057e36404413d
-  data.tar.gz: 7bba09a981e3e71a5de194a84cae6fb19cafa3631b283e1f778072837a354db67b555d80f13329b8895496de886393494155427ad0a8050d97b9a36b61171015
+  metadata.gz: e3258a69b3e289f8277d307759aeca39ea14dd8f0573ef686cb5fb24625b7afe30d9be4e65fe896c7ca9ebdd25612c2fe07b980e72bcb8dfe63598c0297fe46d
+  data.tar.gz: 6cf8c1ee680e128f4ecfda474a528dc61323dba9ca592b7f044e5a9024a27eb6e8926cb4423909c7299198abca88d48aa127cb11d0b0f72d74e2e95c7310550d

data/.rubocop.yml

@@ -38,6 +38,7 @@ RSpec/ExampleLength:
 RSpec/FilePath:
   Exclude:
     - 'spec/lib/my_api_client/errors/**/*'
+    - 'spec/lib/my_api_client/rspec/**/*'
 
 RSpec/NestedGroups:
   Max: 4

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    my_api_client (0.2.0)
+    my_api_client (0.3.0)
       activesupport (>= 4.2.0)
       jsonpath
       sawyer

data/README.jp.md

@@ -6,6 +6,11 @@ MyApiClient は API リクエストクラスを作成するための汎用的な
 
 また、 Ruby on Rails で利用することを想定してますが、それ以外の環境でも動作するように作っているつもりです。不具合などあれば Issue ページからご報告下さい。
 
+## Supported Versions
+
+* Ruby 2.4, 2.5, 2.6
+* Rails 4.2, 5.0, 5.1, 5.2
+
 ## Installation
 
 この gem は macOS と Linux で作動します。まずは、my_api_client を Gemfile に追加します:
@@ -31,7 +36,7 @@ create    spec/api_clients/path/to/resource_api_client_spec.rb
 
 最もシンプルな利用例を以下に示します。
 
-```rb
+```ruby
 class ExampleApiClient < MyApiClient::Base
   endpoint 'https://example.com'
 
@@ -78,7 +83,7 @@ api_clinet.get_users #=> #<Sawyer::Response>
 
 上記のコードにエラーハンドリングを追加してみます。
 
-```rb
+```ruby
 class ExampleApiClient < MyApiClient::Base
   endpoint 'https://example.com'
 
@@ -106,7 +111,7 @@ end
 
 一つずつ解説していきます。まず、以下のように `status_code` を指定するものについて。
 
-```rb
+```ruby
 error_handling status_code: 400..499, raise: MyApiClient::ClientError
 ```
 
@@ -118,7 +123,7 @@ https://github.com/ryz310/my_api_client/blob/master/lib/my_api_client/errors.rb
 
 次に、 `raise` の代わりに Block を指定する場合について。
 
-```rb
+```ruby
 error_handling status_code: 500..599 do |params, logger|
   logger.warn 'Server error occurred.'
   raise MyApiClient::ServerError, params
@@ -135,7 +140,7 @@ API request `GET https://example.com/path/to/resouce`: "Server error occurred."
 
 最後に `json` と `with` を利用する場合について。
 
-```rb
+```ruby
 error_handling json: { '$.errors.code': 10..19 }, with: :my_error_handling
 ```
 
@@ -152,7 +157,7 @@ error_handling json: { '$.errors.code': 10..19 }, with: :my_error_handling
 
 `with` にはインスタンスメソッド名を指定することで、エラーを検出した際に任意のメソッドを実行させることができます。メソッドに渡される引数は Block 定義の場合と同じく `params` と `logger` です。
 
-```rb
+```ruby
 # @param params [MyApiClient::Params::Params] HTTP req and res params
 # @param logger [MyApiClient::Logger] Logger for a request processing
 def my_error_handling(params, logger)
@@ -173,7 +178,7 @@ WIP
 
 多くの場合、同一ホストの API は リクエストヘッダーやエラー情報が同じ構造になっているため、上記のように一つのクラス内に複数の API を定義する設計が理にかなっていますが、 API 毎に個別に定義したい場合は、以下のように 1 つのクラスに 1 の API という構造で設計することも可能です。
 
-```rb
+```ruby
 class ExampleApiClient < MyApiClient::Base
   endpoint 'https://example.com'
 
@@ -227,6 +232,70 @@ WIP
 
 WIP
 
+### RSpec
+
+RSpec を使ったテストをサポートしています。
+以下のコードを `spec/spec_helper.rb` (または `spec/rails_helper.rb`) に追記して下さい。
+
+```ruby
+require 'my_api_client/rspec'
+```
+
+例えば以下のような `ApiClient` を定義しているとします。
+
+```ruby
+class ExampleApiClient < MyApiClient::Base
+  endpoint 'https://example.com'
+
+  def request(user_id:)
+    get "users/#{user_id}"
+  end
+end
+```
+
+`my_api_client_stub` を使うことで、 `ExampleApiClient#request` をスタブ化することができます。これで `#request` を実行してもリアルな HTTP リクエストが実行されなくなります。
+
+```ruby
+my_api_client_stub(ExampleApiClient, :request, response: { id: 12345 })
+
+response = ExampleApiClient.new.request(user_id: 1)
+response.id # => 12345
+```
+
+リクスエストパラメータを使ったレスポンスを返すようにスタブ化したい場合は、 block を利用することで実現できます。
+
+```ruby
+my_api_client_stub(ExampleApiClient, :request) do |params|
+  { id: params[:user_id] }
+end
+
+response = ExampleApiClient.new.request(user_id: 1)
+response.id # => 1
+```
+
+`receive` や `have_received` を使ったテストを書きたい場合は、 `my_api_client_stub` の戻り値を利用すると良いでしょう。
+
+```ruby
+def execute_api_request
+  ExampleApiClient.new.request(user_id: 1)
+end
+
+api_clinet = my_api_client_stub(ExampleApiClient, :request)
+execute_api_request
+expect(api_client).to have_received(:request).with(user_id: 1)
+```
+
+また、例外が発生する場合のテストを書きたい場合は、 `raise` オプションを利用することができます。
+
+```ruby
+def execute_api_request
+  ExampleApiClient.new.request(user_id: 1)
+end
+
+my_api_client_stub(ExampleApiClient, :request, raise: MyApiClient::Error)
+expect { execute_api_request }.to raise_error(MyApiClient::Error)
+```
+
 ## Contributing
 
 不具合の報告や Pull Request を歓迎しています。OSS という事で自分はなるべく頑張って英語を使うようにしていますが、日本語での報告でも大丈夫です :+1:

data/lib/my_api_client/rspec.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'my_api_client'
+require 'my_api_client/rspec/stub'
+
+RSpec.configure do |config|
+  config.include MyApiClient::Stub
+end

data/lib/my_api_client/rspec/stub.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module MyApiClient
+  # Test helper module for RSpec
+  module Stub
+    # Provides stubbing feature for `MyApiClient`.
+    #
+    # @param klass [Class]
+    #   Stubbing target class.
+    # @param action [Symbol]
+    #   Stubbing target method name.
+    # @param response [Object, nil]
+    #   Stubbed ApiClient will return parameters set by `response`.
+    #   default: nil
+    # @param raise [Class, MyApiClient::Error, nil]
+    #   Stubbed ApiClient will raise exception set by `raise`.
+    #   You can set either exception class or exception instance.
+    #   default: nil
+    # @return [InstanceDouble]
+    #   Returns a spy object for the ApiClient.
+    # rubocop:disable Metrics/AbcSize
+    def my_api_client_stub(klass, action, response: nil, raise: nil)
+      instance = instance_double(klass)
+      allow(klass).to receive(:new).and_return(instance)
+      if raise.present?
+        allow(instance).to receive(action).and_raise(process_raise_option(raise))
+      elsif block_given?
+        allow(instance).to receive(action) { |*request| stub_as_sawyer(yield(*request)) }
+      else
+        allow(instance).to receive(action).and_return(stub_as_sawyer(response))
+      end
+      instance
+    end
+    # rubocop:enable Metrics/AbcSize
+
+    private
+
+    # Provides a shorthand for `raise` option.
+    # `MyApiClient::Error` requires `MyApiClient::Params::Params` instance on
+    # initialize, but it makes trubolesome. `MyApiClient::NetworkError` is more.
+    # If given a error instance, it will return raw value without processing.
+    #
+    # @param exception [Clsas, MyApiClient::Error] Processing target.
+    # @return [MyApiClient::Error] Processed exception.
+    # @raise [RuntimeError] Unsupported error class was set.
+    def process_raise_option(exception)
+      case exception
+      when Class
+        params = instance_double(MyApiClient::Params::Params, to_bugsnag: {})
+        if exception == MyApiClient::NetworkError
+          exception.new(params, Net::OpenTimeout.new)
+        else
+          exception.new(params)
+        end
+      when MyApiClient::Error
+        exception
+      else
+        raise "Unsupported error class was set: #{exception.inspect}"
+      end
+    end
+
+    def stub_as_sawyer(params)
+      case params
+      when Hash  then Sawyer::Resource.new(agent, params)
+      when Array then params.map { |hash| sawyer_resource(hash) }
+      when nil   then nil
+      else params
+      end
+    end
+
+    def agent
+      instance_double('Sawyer::Agent').tap do |agent|
+        allow(agent).to receive(:parse_links) do |data|
+          data ||= {}
+          links = data.delete(:_links)
+          [data, links]
+        end
+      end
+    end
+  end
+end

data/lib/my_api_client/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module MyApiClient
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: my_api_client
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - ryz310
@@ -264,6 +264,8 @@ files:
 - lib/my_api_client/params/params.rb
 - lib/my_api_client/params/request.rb
 - lib/my_api_client/request.rb
+- lib/my_api_client/rspec.rb
+- lib/my_api_client/rspec/stub.rb
 - lib/my_api_client/version.rb
 - my_api_client.gemspec
 homepage: https://github.com/ryz310/my_api_client