my_api_client 0.9.2 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 796e9513f74e5c4fa6366ac0a67b5eea77a9e0c32f39325acc8a8702ef9852f1
-  data.tar.gz: 274bd8ec8be1b10cc1b39ae683579dfb0e2f72dac7a1eab2a8cc018baf3c5335
+  metadata.gz: 6cd0cadf555eff5fcc7b6ce43f2af6437c89243fa371b8c17eb6db893948c256
+  data.tar.gz: 9c69a2495c109a11c601bbe770f4f063fa4783f72d567d5b3b4f1a3ded514c99
 SHA512:
-  metadata.gz: b2fbd02137213962a81a896d930a046360134b0c1cf600f0cf2f2f6b0e5d44d12b94a560c903d80e215dda9374fe4cca9bd558bafe887974de8ba5a1ceaa19ca
-  data.tar.gz: c1fe1f75598e3f597e3c52f32b6b32aee80ec4d9cfd061dcb2a1765955020b5b35cd161112a6d57121b72917773558f065b097bac4324e6aa5c1df3f18f3390d
+  metadata.gz: 3b697f923d27cde7834774fc321f39a965f375619c591cb157f7e2743cdc54be44a41d160371e8c85f386159edbf6aeff269123d904c24eba0e6929ef540ec08
+  data.tar.gz: 8868f50cf3f9b1358b070d5a0261bc9db268ccf90bc2715a478b0a1b82bb6d9d210fd7b022caaafa6c0ee3afa63b1a0efd3566dee4a9e91e4b3541b748cd35c8

data/.gem_comet.yml

@@ -3,9 +3,10 @@
 # $ gem install gem_comet
 # $ gem_comet release {version number, like as "1.2.3"}
 
-version: 1
+version: 1.1
 
 release:
   base_branch: master
   release_branch: production
   version_file_path: lib/my_api_client/version.rb
+  changelog_file_path: CHANGELOG.md # optional

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2019-09-30 23:40:39 +0000 using RuboCop version 0.75.0.
+# on 2019-10-14 23:40:54 +0000 using RuboCop version 0.75.1.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Change log
 
+## 0.10.0 (Oct 23, 2019)
+
+### Feature
+
+* Shoulda-matchers for my_api_client ([#124](https://github.com/ryz310/my_api_client/pull/124))
+
+### Misc
+
+* Modify request specifications ([#120](https://github.com/ryz310/my_api_client/pull/120))
+* Re-generate .rubocop_todo.yml with RuboCop v0.75.1 ([#121](https://github.com/ryz310/my_api_client/pull/121))
+* ryz310/dependabot/bundler/jsonpath-1.0.5 ([#123](https://github.com/ryz310/my_api_client/pull/123))
+
 ## 0.9.2 (Oct 8, 2019)
 
 ### Bugfix

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    my_api_client (0.9.2)
+    my_api_client (0.10.0)
       activesupport (>= 4.2.0)
       jsonpath
       sawyer (>= 0.8.2)
@@ -33,12 +33,12 @@ GEM
       concurrent-ruby (~> 1.0)
     jaro_winkler (1.5.3)
     json (2.2.0)
-    jsonpath (1.0.4)
+    jsonpath (1.0.5)
       multi_json
       to_regexp (~> 0.2.1)
     method_source (0.9.2)
     minitest (5.12.2)
-    multi_json (1.13.1)
+    multi_json (1.14.1)
     multipart-post (2.1.1)
     parallel (1.18.0)
     parser (2.6.5.0)
@@ -67,7 +67,7 @@ GEM
     rspec-support (3.9.0)
     rspec_junit_formatter (0.4.1)
       rspec-core (>= 2, < 4, != 2.12.0)
-    rubocop (0.75.0)
+    rubocop (0.75.1)
       jaro_winkler (~> 1.5.1)
       parallel (~> 1.10)
       parser (>= 2.6)

data/README.jp.md

@@ -301,9 +301,9 @@ class PostUserApiClient < ExampleApiClient
 end
 ```
 
-## Testing
+## RSpec
 
-### RSpec
+### Setup
 
 RSpec を使ったテストをサポートしています。
 以下のコードを `spec/spec_helper.rb` (または `spec/rails_helper.rb`) に追記して下さい。
@@ -312,7 +312,103 @@ RSpec を使ったテストをサポートしています。
 require 'my_api_client/rspec'
 ```
 
-例えば以下のような `ApiClient` を定義しているとします。
+### Testing
+
+以下のような `ApiClient` を定義しているとします。
+
+```ruby
+class ExampleApiClient < MyApiClient::Base
+  endpoint 'https://example.com/v1'
+
+  error_handling status_code: 200, json: { '$.errors.code': 10 },
+                 raise: MyApiClient::ClientError
+
+  attr_reader :access_token
+
+  def initialize(access_token:)
+    @access_token = access_token
+  end
+
+  # GET https://example.com/v1/users
+  def get_users(condition:)
+    get 'users', headers: headers, query: { search: condition }
+  end
+
+  private
+
+  def headers
+    {
+      'Content-Type': 'application/json;charset=UTF-8',
+      'Authorization': "Bearer #{access_token}",
+    }
+  end
+end
+```
+
+通常の場合 `ApiClient` を新たに定義した際にテストすべき項目が 2 つあります。
+
+1. 指定したエンドポイントに対して、任意のパラメータを使ったリクエストが実行されること
+2. 特定のレスポンスに対して適切にエラーハンドリングが実行されること
+
+`my_api_client` ではこれらをテストするための Custom Matcher を用意しています。
+
+#### 1. 指定したエンドポイントに対して、任意のパラメータを使ったリクエストが実行されること
+
+例えば上述の `#get_users` の内部では、入力引数を用いて検索クエリが組み立てられていたり、 Header に `access_token` を利用したりしています。これらの値が正しくリクエストに用いられているかどうかのテストが必要となります。
+
+この場合 `request_to` と `with` という Custom Matcher を利用することで簡単にテストを記述することが出来ます。 `expect` にはブロック `{}` を指定する必要がある点にご注意ください。他にも `with` には `body` というキーワード引数も指定できます。
+
+```ruby
+RSpec.describe ExampleApiClient, type: :api_client do
+  let(:api_client) { described_class.new(access_token: 'access token') }
+  let(:headers) do
+    {
+      'Content-Type': 'application/json;charset=UTF-8',
+      'Authorization': 'Bearer access token',
+    }
+  end
+
+  describe '#get_users' do
+    it do
+      expect { api_client.get_users(condition: 'condition') }
+        .to request_to(:get, 'https://example.com/v1/users')
+        .with(headers: headers, query: { condition: 'condition' })
+    end
+  end
+end
+```
+
+#### 2. 特定のレスポンスに対して適切にエラーハンドリングが実行されること
+
+次に `error_handling` についてのテストも記述していきます。ここではレスポンスのステータスコードが `200` かつ Body に `'$.errors.code': 10` という値が含まれていた場合は `MyApiClient::ClientError` を `raise` する、というエラーハンドリングが定義されています。
+
+ここでは `be_handled_as_an_error` と `when_receive` という Custom Matcher を利用します。ここでも `expect` にはブロック `{}` を指定する必要がある点にご注意ください。
+
+`be_handled_as_an_error` の引数には期待する例外クラスを指定します。 `when_receive` にはリクエスト結果としてどのような値が返ってきたのかを指定します。
+
+なお、 `error_handling` で例外を発生させないケースは現在想定していないため、これ以外の Custom Matcher は定義されていません。何かユースケースがあれば教えて下さい。
+
+```ruby
+it do
+  expect { api_client.get_users(condition: 'condition') }
+    .to be_handled_as_an_error(MyApiClient::ClientError)
+    .when_receive(status_code: 200, body: { errors: { code: 10 } }.to_json)
+end
+```
+
+また、以下のように正常なレスポンスが返ってきた時に誤ってエラーハンドリングされていないかをテストすることもできます。
+
+```ruby
+it do
+  expect { api_client.get_users(condition: 'condition') }
+    .not_to be_handled_as_an_error(MyApiClient::ClientError)
+    .when_receive(status_code: 200, body: { users: { id: 1 } }.to_json)
+end
+```
+
+### Stubbing
+
+以下のような `ApiClient` を定義しているとします。
 
 ```ruby
 class ExampleApiClient < MyApiClient::Base

data/lib/generators/rails/templates/api_client.rb.erb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 class <%= "#{class_name}ApiClient" %> < ::ApplicationApiClient
-  endpoint '{ endpoint }'
+  endpoint 'https://example.com'
 
   # error_handling json: { '$.errors.code': 10 } do |params, logger|
   #   # Behavior when detected an error.

data/lib/generators/rspec/templates/api_client_spec.rb.erb

@@ -4,9 +4,46 @@ require 'rails_helper'
 
 RSpec.describe <%= "#{class_name}ApiClient" %>, <%= type_metatag(:api_client) %> do
   let(:api_client) { described_class.new }
+  let(:headers) do
+    {
+      'Content-Type': 'application/json',
+    }
+  end
+
+  shared_examples 'to handle errors' do
+    it do
+      expect { api_request }
+        .to be_handled_as_an_error(MyApiClient::ClientError)
+        .when_receive(status_code: 400)
+    end
 
+    it do
+      expect { api_request }
+        .to be_handled_as_an_error(MyApiClient::ServerError)
+        .when_receive(status_code: 500)
+    end
+  end
 <% yeild_request_arguments do |action, http_method, pathname| -%>
+
   describe '#<%= action %>' do
+    subject(:api_request) { api_client.<%= action %> }
+
+    it do
+      expect { api_request }
+        .to request_to(:<%= http_method %>, 'https://example.com/<%= pathname %>')
+<% if http_method == 'get' -%>
+        .with(headers: headers, query: {})
+<% else -%>
+        .with(headers: headers, body: {})
+<% end -%>
+    end
+
+    it_behaves_like 'to handle errors' do
+      it do
+        expect { api_request }.not_to be_handled_as_an_error
+          .when_receive(status_code: 200, body: nil, headers: nil)
+      end
+    end
   end
 <% end -%>
 end

data/lib/my_api_client/rspec.rb

@@ -1,7 +1,10 @@
 # frozen_string_literal: true
 
 require 'my_api_client'
+require 'my_api_client/rspec/matcher_helper'
 require 'my_api_client/rspec/stub'
+require 'my_api_client/rspec/matchers/be_handled_as_an_error'
+require 'my_api_client/rspec/matchers/request_to'
 
 RSpec.configure do |config|
   config.include MyApiClient::Stub

data/lib/my_api_client/rspec/matcher_helper.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module MyApiClient
+  # Helper module for rspec custom matcher
+  module MatcherHelper
+    def disable_logging
+      logger = instance_double(MyApiClient::Logger, info: nil, warn: nil)
+      allow(MyApiClient::Logger).to receive(:new).and_return(logger)
+    end
+
+    def dummy_response(status: 200, headers: {}, body: nil)
+      instance_double(
+        Sawyer::Response,
+        timing: 0.0,
+        data: instance_double(Sawyer::Resource),
+        status: status,
+        headers: headers,
+        body: body
+      )
+    end
+
+    def diff_as_object(actual, expected)
+      differ = RSpec::Support::Differ.new(
+        object_preparer: ->(object) { RSpec::Matchers::Composable.surface_descriptions_in(object) },
+        color: RSpec::Matchers.configuration.color?
+      )
+      differ.diff_as_object(actual, expected)
+    end
+  end
+end

data/lib/my_api_client/rspec/matchers/be_handled_as_an_error.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'rspec/expectations'
+
+RSpec::Matchers.define :be_handled_as_an_error do |expected_error_class|
+  include MyApiClient::MatcherHelper
+
+  match do |api_request|
+    init
+    handle_error(api_request).is_a? expected_error_class
+  end
+
+  match_when_negated do |api_request|
+    init
+    handle_error(api_request).nil?
+  end
+
+  chain :when_receive, :expected_response
+
+  failure_message do |api_request|
+    actual_error = handle_error(api_request)
+    if actual_error.nil?
+      "expected to be handled as #{expected_error_class.name}, " \
+      'but not to be handled'
+    else
+      "expected to be handled as #{expected_error_class.name}, " \
+      "but it was handled as #{actual_error.class.name}"
+    end
+  end
+
+  failure_message_when_negated do |api_request|
+    actual_error = handle_error(api_request)
+    'expected not to be handled as an error, ' \
+    "but it was handled as #{actual_error.class.name}"
+  end
+
+  def init
+    disable_logging
+    response = dummy_response(
+      status: expected_response[:status_code] || 200,
+      headers: expected_response[:headers] || {},
+      body: expected_response[:body] || nil
+    )
+    sawyer = instance_double(Sawyer::Agent, call: response)
+    allow(Sawyer::Agent).to receive(:new).and_return(sawyer)
+  end
+
+  def handle_error(api_request)
+    api_request.call
+  rescue MyApiClient::Error => e
+    e
+  else
+    nil
+  end
+
+  supports_block_expectations
+end

data/lib/my_api_client/rspec/matchers/request_to.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'rspec/expectations'
+
+RSpec::Matchers.define :request_to do |expected_method, expected_url|
+  include MyApiClient::MatcherHelper
+
+  match do |api_request|
+    disable_logging
+    @expected = {
+      request_line: request_line(expected_method, expected_url),
+      body: expected_options[:body],
+      headers: expected_options[:headers],
+      query: expected_options[:query],
+    }.compact
+    @actual = {}
+    sawyer = instance_double(Sawyer::Agent)
+    allow(Sawyer::Agent).to receive(:new) do |schema_and_hostname|
+      @actual_schema_and_hostname = schema_and_hostname
+    end.and_return(sawyer)
+    allow(sawyer).to receive(:call) do |method, pathname, body, options|
+      @actual =
+        {
+          request_line: request_line(method, @actual_schema_and_hostname + pathname),
+          body: body,
+          headers: options[:headers],
+          query: options[:query],
+        }.compact
+    end.and_return(dummy_response)
+    api_request.call
+    @expected == @actual
+  end
+
+  chain :with, :expected_options
+
+  description do
+    "request to \"#{request_line(expected_method, expected_url)}\""
+  end
+
+  failure_message do
+    <<~MESSAGE
+      expected to request to "#{@expected[:request_line]}"
+      Diff: #{diff_as_object(@actual, @expected)}
+    MESSAGE
+  end
+
+  def request_line(method, url)
+    "#{method.upcase} #{url}"
+  end
+
+  supports_block_expectations
+end

data/lib/my_api_client/rspec/stub.rb

@@ -107,7 +107,7 @@ module MyApiClient
     end
 
     def agent
-      instance_double('Sawyer::Agent').tap do |agent|
+      instance_double(Sawyer::Agent).tap do |agent|
         allow(agent).to receive(:parse_links) do |data|
           data ||= {}
           links = data.delete(:_links)

data/lib/my_api_client/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: my_api_client
 version: !ruby/object:Gem::Version
-  version: 0.9.2
+  version: 0.10.0
 platform: ruby
 authors:
 - ryz310
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-10-08 00:00:00.000000000 Z
+date: 2019-10-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -256,6 +256,9 @@ files:
 - lib/my_api_client/params/request.rb
 - lib/my_api_client/request.rb
 - lib/my_api_client/rspec.rb
+- lib/my_api_client/rspec/matcher_helper.rb
+- lib/my_api_client/rspec/matchers/be_handled_as_an_error.rb
+- lib/my_api_client/rspec/matchers/request_to.rb
 - lib/my_api_client/rspec/stub.rb
 - lib/my_api_client/version.rb
 - my_api_client.gemspec