evil-client 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1a0f6860291b235077bd6d9063eb9e1ec47cb9ef
-  data.tar.gz: cbb9aca48a0283cf8e6ec84bec9444ea74bb440c
+  metadata.gz: 237e89873909ecf0ad225c9a714e68702c96b5c6
+  data.tar.gz: 5a030e4b7629338ebe24359311e7dac5b4d74fe8
 SHA512:
-  metadata.gz: c1d2c2e407c90ef12db1d58c4aed5fef1a4c851934f90e25602ad5461c14278e30dcd3a1dbc7534dc17218797d46dedaa8f023389be46625f66bb046a06791a5
-  data.tar.gz: 433099e8dcebb8e48e0f22f057db11c68eb78556a1660508bdd22a261a40ad2c59407971459716c027d7c5d4b7cf122b2c03fa63d3308b06762e5658f3e7d763
+  metadata.gz: 0ae5ee8377ef7ca78252356a4cad2726ef854a676b4b0715c4e6a881d7c8d381896307b48d7d8e6cbe7920362369f4886dc8f654a39bab10e2cf160cf8c6fed8
+  data.tar.gz: 54acb1b3f1d7e94d879240eaa6eba66576c719b5833707ef68393dcded7c971b7a1ed248e840f514d1a377a3daa6f33892caaf93a4acecffd485459e9c9f177f

data/CHANGELOG.md

@@ -4,6 +4,35 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog], and this project adheres
 to [Semantic Versioning].
 
+## [1.1.0] [2017-08-10]
+
+Some syntax sugar has been added to both the client and its RSpec helpers.
+
+### Added
+
+- Assigned options are wrapped into simple delegator with rails-like methods
+  `#slice` and `#except`. This helps when you need to select part of assigned
+  options for some part of a request (nepalez)
+
+  Remember the options are collected from the very root of the client,
+  so at the endpoint operation there could be a lot of options
+  related to other endpoints, or to a different part of the request.
+
+- Every container has reference to its `#client` along the standalone `#name`
+  of its schema. This allows to select operation containers by
+  `#client`, `#name`, `#options` to stub their methods `#call` (nepalez)
+
+- RSpec stubs and expectations for operations (nepalez, palkan)
+
+### Removed
+
+- RSpec matcher `perform_operation` has been dropped in favor of
+  `stub_client_operation` and `expect_client_operation` (nepalez)
+
+- Unnecessary instance methods inherited from [Object] are removed
+  from various classes to avoid name conflicts with user-provided
+  scopes and operations (nepalez)
+
 ## [1.0.0] [2017-08-06]
 
 This is a total new reincarnation of the gem. I've changed its
@@ -326,6 +355,7 @@ formats will be added.
   response :not_found, 404, format: "json", raise: true
   ```
 
+[1.1.0]: https://github.com/evilmartians/evil-client/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/evilmartians/evil-client/compare/v0.3.3...v1.0.0
 [0.3.3]: https://github.com/evilmartians/evil-client/compare/v0.3.2...v0.3.3
 [0.3.2]: https://github.com/evilmartians/evil-client/compare/v0.3.1...v0.3.2

data/README.md

@@ -70,7 +70,7 @@ class CatsClient < Evil::Client
       path        { "cats/#{id}" } # added to root path
       http_method :patch # you can use plain syntax instead of a block
       format      "json"
-      body        { options.reject { |key, _val| key == :id } }
+      body        { options.except(:id, :version) } # [#slice] is available too
 
       # Parses json response and wraps it into Cat instance with additional
       # parameter

data/docs/index.md

@@ -68,7 +68,7 @@ class CatsClient < Evil::Client
       path        { "cats/#{id}" } # added to root path
       http_method :patch # you can use plain syntax instead of a block
       format      "json"
-      body        { options.reject { |key, _val| key == :id } }
+      body        { options.except(:id, :version) } # [#slice] is available too
 
       # Parses json response and wraps it into Cat instance with additional
       # parameter

data/docs/rspec.md

@@ -1,13 +1,16 @@
 When you provide a client to remote API, you would provide some means for its users to test their operations.
 
-Surely, they could use [webmock] to check the ultimate requests that are sent to the server. But doing this, they would inadvertedly specify not their own code, but your client's code too. What do they actually need is a means to check calls of your client's operations. This way they would back on correctness of your client, and take its interface as an endpoint.
+Surely, they could use [webmock] to check the ultimate requests that are sent to the server. But doing this, they would inadvertedly specify not their own code, but your client's code too. What do they actually need is a means to stub and check invocations of your client's operations. This way they would back on correctness of your client, and take its interface as an endpoint.
 
-For this reason, we support a special RSpec matcher `perform_operation`. It checks, what operations are called via evil-client, and what options are used in there.
-
-The matcher isn't loaded by default, so you must require it first:
+For this reason, we support a special RSpec stubs and expectations. sThey are not loaded by default, so you must require it first, and then include the module:
 
 ```ruby
 require "evil/client/rspec"
+
+RSpec.describe CatsClient, "cats.fetch" do
+  include Evil::Client::RSpec
+  # ...
+end
 ```
 
 Providing that you defined some client...
@@ -37,60 +40,87 @@ RSpec.describe CatsClient, "cats.fetch" do
   let(:scope)  { client.cats(version: 1) }
 
   it "fetches a cat by id" do
-    expect { scope.fetch(id: 8) }
-      .to perform_operation("CatsClient.client.fetch")
+    stub_client_operation(CatsClient, "cats.fetch")
+      .with(token: "foo", version: 1, id: 8) # full hash of collected options
+      .to_return 8 # returned value by operation
+
+    expect(scope.fetch(id: 8)).to eq 8
+    expect_client_operation(CatsClient, "cats.fetch")
+      .to_have_been_performed
   end
 end
 ```
 
-You can add chaining using one of 3 additional methods: `with`, `with_exactly`, or `without`.
+## Selection
+
+To select stubbed operations you can specify client class:
 
-## with
+```ruby
+stub_client_operation(CatsClient)
+```
 
-This method checks that the operation **includes some options**:
+or its superclass
 
 ```ruby
-expect { scope.fetch(id: 8) }
-  .to perform_operation("CatsClient.client.fetch")
-  .with token: "foo"
+stub_client_operation(Evil::Client)
 ```
 
-## with_exactly
+or leave it for default `Evil::Client`:
 
-This time you can check the full list of options given to operation:
+```ruby
+stub_client_operation()
+```
+
+or add a fully qualified name of the operation (for **exact** matching):
 
 ```ruby
-expect { scope.fetch(id: 8) }
-  .to perform_operation("CatsClient.client.fetch")
-  .with_exactly token: "foo", version: 1, id: 8
+stub_client_operation(CatsClient, "cats.fetch")
 ```
 
-## without
+or regexp for partial matching:
 
-You can also check that some keys are absent:
+```ruby
+stub_client_operation(CatsClient, /fetch/)
+```
+
+or use method `with` to check options exactly:
 
 ```ruby
-expect { scope.fetch(id: 8) }
-  .to perform_operation("CatsClient.client.fetch")
-  .without :name, :email
+stub_client_operation(CatsClient, "cats.fetch").with(token: "foo", version: 1, id: 8)
 ```
 
-This can be useful to check a behaviour of the client with optional attributes.
+or partially:
+
+```ruby
+stub_client_operation(CatsClient, "cats.fetch").with(hash_including(id: 8))
+```
 
-All checks can be negated as well:
+or via block:
 
 ```ruby
-expect { scope.fetch(id: 8) }
-  .not_to perform_operation("CatsClient.client.fetch")
-  .with token: "foo"
+stub_client_operation(CatsClient, "cats.fetch").with { |opts| opts[:id] == 8 }
 ```
 
-**Notice**: Under the hood the matcher doesn't stub the request, so its better to stub all requests by hand:
+## Return value
+
+You **must** define some value returned by a stub:
 
 ```ruby
-require "webmock/rspec"
+stub_client_operation(CatsClient, "cats.fetch").to_return(8)
+```
+
+or fall back to original implementation:
 
-before { stub_request :any, // }
+```ruby
+stub_client_operation(CatsClient, "cats.fetch").to_call_original
+```
+
+or raise an exception:
+
+```ruby
+stub_client_operation(CatsClient, "cats.fetch").to_raise StandardError, "Wrong id"
 ```
 
+## Some Hint
+
 [webmock]: https://github.com/bblimke/webmock

data/evil-client.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |gem|
   gem.name     = "evil-client"
-  gem.version  = "1.0.0"
+  gem.version  = "1.1.0"
   gem.author   = ["Andrew Kozin (nepalez)", "Ravil Bairamgalin (brainopia)"]
   gem.email    = ["andrew.kozin@gmail.com", "nepalez@evilmartians.com"]
   gem.homepage = "https://github.com/evilmartians/evil-client"
@@ -16,7 +16,7 @@ Gem::Specification.new do |gem|
   gem.add_runtime_dependency "dry-initializer", "~> 1.4"
   gem.add_runtime_dependency "i18n", "~> 0.8.6"
   gem.add_runtime_dependency "mime-types", "~> 3.1"
-  gem.add_runtime_dependency "rack", "~> 1"
+  gem.add_runtime_dependency "rack", "~> 2"
 
   gem.add_development_dependency "rake", ">= 10"
   gem.add_development_dependency "rspec", "~> 3.0"

data/lib/evil/client.rb

@@ -7,6 +7,7 @@ require "yaml"
 require "i18n"
 require "mime-types"
 require "securerandom"
+require "delegate"
 require "dry-initializer"
 require "net/http"
 require "net/https"
@@ -18,6 +19,9 @@ module Evil
   # Absctract base class for clients to remote APIs
   #
   class Client
+    require_relative "client/names"
+    Names.clean(self) # Remove unnecessary methods from the instance
+
     require_relative "client/exceptions/definition_error"
     require_relative "client/exceptions/name_error"
     require_relative "client/exceptions/response_error"
@@ -25,6 +29,7 @@ module Evil
     require_relative "client/exceptions/validation_error"
 
     require_relative "client/chaining"
+    require_relative "client/options"
     require_relative "client/settings"
     require_relative "client/schema"
     require_relative "client/container"

data/lib/evil/client/builder.rb

@@ -9,6 +9,8 @@ class Evil::Client
   # for scope/operation instance whose options reload the [#parent]'s ones.
   #
   class Builder
+    Names.clean(self) # Remove unnecessary methods from the instance
+
     # Load concrete implementations for the abstact builder
     require_relative "builder/scope"
     require_relative "builder/operation"

data/lib/evil/client/chaining.rb

@@ -3,6 +3,8 @@ class Evil::Client
   # Support chaining of calls for nested scopes/operations
   #
   module Chaining
+    Names.clean(self) # Remove unnecessary methods from the instance
+
     private
 
     def respond_to_missing?(name, *)

data/lib/evil/client/container.rb

@@ -5,6 +5,8 @@ class Evil::Client
   # and methods to build sub-scope/operation or perform the current operation.
   #
   class Container
+    Names.clean(self) # Remove unnecessary methods from the instance
+
     # Loads concrete implementations of the abstract container
     require_relative "container/scope"
     require_relative "container/operation"
@@ -17,6 +19,18 @@ class Evil::Client
     # @return [Evil::Client::Settings]
     attr_reader :settings
 
+    # The client of the [#schema]
+    # @return [Class]
+    def client
+      schema.client
+    end
+
+    # The name of the current schema
+    # @return [String]
+    def name
+      schema.to_s
+    end
+
     # Options assigned to the [#settings]
     #
     # These are opts given to the [#initializer],
@@ -24,7 +38,7 @@ class Evil::Client
     #
     # @return [Hash<Symbol, Object>]
     def options
-      @options ||= settings.options
+      settings.options
     end
 
     # The human-friendly representation of the scope instance
@@ -34,7 +48,7 @@ class Evil::Client
     #
     # @return [String]
     def to_s
-      "#<#{schema} #{options.map { |key, val| "@#{key}=#{val}" }.join(', ')}>"
+      "#<#{name} #{options.map { |key, val| "@#{key}=#{val}" }.join(', ')}>"
     end
     alias_method :to_str,  :to_s
     alias_method :inspect, :to_s

data/lib/evil/client/exceptions/name_error.rb

@@ -10,23 +10,21 @@ class Evil::Client
     # @return [Symbol] if name is valid
     # @raise  [self] if name isn't valid
     #
-    def self.check!(name, forbidden = [])
+    def self.check!(name)
       name = name.to_sym
-      return name if name[FORMAT] && !forbidden.include?(name)
-      raise new(name, forbidden)
+      return name if name[Names::FORMAT] && !Names::FORBIDDEN.include?(name)
+      raise new(name)
     end
 
     private
 
-    def initialize(name, forbidden)
+    def initialize(name)
       super "Invalid name :#{name}." \
             " It should contain latin letters in the lower case, digits," \
             " and underscores only; have minimum 2 chars;" \
             " start from a letter; end with either letter or digit." \
-            " The following names: '#{forbidden.join("', '")}'" \
+            " The following names: '#{Names::FORBIDDEN.join("', '")}'" \
             " are already used by Evil::Client."
     end
-
-    FORMAT = /^[a-z]([a-z\d_])*[a-z\d]$/
   end
 end

data/lib/evil/client/names.rb

@@ -0,0 +1,54 @@
+class Evil::Client
+  #
+  # Utility to remove unnecessary methods from instances
+  # to clear a namespace
+  # @private
+  #
+  module Names
+    extend self
+
+    # Removes unused instance methods inherited from [Object] from given class
+    #
+    # @param  [Class] klass
+    # @return [nil]
+    #
+    def clean(klass)
+      (klass.instance_methods - BasicObject.instance_methods - FORBIDDEN)
+        .each { |m| klass.send(:undef_method, m) if m[FORMAT] } && nil
+    end
+
+    # List of preserved methods.
+    # They also couldn't be used as names of operations/scopes/options
+    # to avoid name conflicts.
+    FORBIDDEN = %i[
+      basic_auth
+      class
+      datetime
+      hash
+      inspect
+      instance_exec
+      instance_variable_get
+      instance_variable_set
+      key_auth
+      logger
+      logger
+      object_id
+      operation
+      operations
+      options
+      schema
+      scope
+      scopes
+      self
+      send
+      settings
+      singleton_class
+      to_s
+      to_str
+      token_auth
+    ].freeze
+
+    # Matches whether a name can be used in operations/scopes/options
+    FORMAT = /^[a-z]([a-z\d_])*[a-z\d]$/
+  end
+end

data/lib/evil/client/options.rb

@@ -0,0 +1,27 @@
+class Evil::Client
+  # Wraps hash of options with railsy methods [#slice] and [#except]
+  #
+  # Both methods works on the root level only.
+  # Nevertheless, this is sufficient to select/reject a part of the whole
+  # options collected from the very root of the client.
+  #
+  class Options < SimpleDelegator
+    # Returns a new hash which include only selected keys
+    #
+    # @param  [Object, Array<Object>] keys
+    # @return [Hash]
+    #
+    def slice(*keys)
+      select { |key| keys.flatten.include? key }
+    end
+
+    # Returns a new hash where some keys are excluded from
+    #
+    # @param  [Object, Array<Object>] keys
+    # @return [Hash]
+    #
+    def except(*keys)
+      reject { |key| keys.flatten.include? key }
+    end
+  end
+end

data/lib/evil/client/resolver.rb

@@ -7,6 +7,8 @@ class Evil::Client
   # (request, middleware or response).
   #
   class Resolver
+    Names.clean(self) # Remove unnecessary methods from the instance
+
     # Loads concrete implementation of the abstract resolver
     require_relative "resolver/request"
     require_relative "resolver/middleware"

data/lib/evil/client/rspec.rb

@@ -1,127 +1,25 @@
-#
-# Checks that an operation has been performed with given options
-#
-# @example
-#   subject do
-#     MyClient.new(token: "foo").users(version: 3).fetch(token: "bar", id: 42)
-#   end
-#
-#   # call only matcher
-#   expect { subject }.to perform_operation("MyClient.users.fetch")
-#
-#   # exact matcher
-#   expect { subject }
-#     .to perform_operation("MyClient.users.fetch")
-#     .with_exactly(token: "bar", version: 3, id: 42)
-#
-#   # partial matcher
-#   expect { subject }
-#     .to perform_operation("MyClient.users.fetch")
-#     .with(token: "bar", version: 3)
-#
-#   # absence matcher
-#   expect { subject }
-#     .to perform_operation("MyClient.users.fetch")
-#     .without(:user, :password)
-#
-#   # block syntax
-#   expect { subject }
-#     .to perform_operation("MyClient.users.fetch")
-#     .with { |token:, **| expect(token).to eq "bar" }
-#
-# @param [String] name The full name of the operation
-#
-RSpec::Matchers.define :perform_operation do |name|
-  supports_block_expectations
-
-  description { "perform operation #{name} " }
-
-  chain :with do |**options|
-    @some_options = options
-  end
-
-  chain :with_exactly do |**options|
-    @exact_options = options
-  end
-
-  chain :without do |*options|
-    @no_options = options.flatten.map(&:to_sym)
-  end
-
-  def full_signature(name)
-    name.dup.tap do |text|
-      text << " with options #{@exact_options}"              if @exact_options
-      text << " with options including #{@some_options}"     if @some_options
-      text << " without options :#{@no_options.join(', :')}" if @no_options
+class Evil::Client
+  #
+  # Collection of RSpec-related definitions
+  #
+  module RSpec
+    require_relative "rspec/evil_client_schema_matching"
+    require_relative "rspec/base_stub"
+    require_relative "rspec/allow_stub"
+    require_relative "rspec/expect_stub"
+
+    def stub_client_operation(klass = Evil::Client, name = nil)
+      AllowStub.new(klass, name)
     end
-  end
-
-  # rubocop: disable Metrics/CyclomaticComplexity
-  # rubocop: disable Style/InverseMethods
-  def expected_options?(options, check)
-    return if @exact_options && options != @exact_options
-    return if @some_options  && !(options >= @some_options)
-    return if (options.keys & @no_options.to_a).any?
-    check.nil? || check.call(options)
-  end
-  # rubocop: enable Metrics/CyclomaticComplexity
-  # rubocop: enable Style/InverseMethods
-
-  def stub_resolver
-    resolver = Evil::Client::Resolver::Request
 
-    allow(resolver).to receive(:call) do |schema, settings|
-      register(schema, settings)
-      resolver.new(schema, settings).send(:__call__)
+    def expect_client_operation(klass, name = nil)
+      ExpectStub.new(klass, name)
     end
-  end
-
-  def actual_operations
-    @actual_operations ||= []
-  end
-
-  def register(schema, settings)
-    actual_operations << [schema.to_s, settings.options]
-  end
-
-  def performed(name, check)
-    @performed ||= actual_operations.find do |(key, options)|
-      (key == name) && expected_options?(options, check)
-    end
-  end
-
-  match do |block|
-    stub_resolver
-    block.call
-    !performed(name, block_arg).nil?
-  end
-
-  match_when_negated do |block|
-    stub_resolver
-    block.call
-    performed(name, block_arg).nil?
-  end
-
-  def describe_expectations(name, perform)
-    "It was expected the operation #{full_signature(name)}" \
-    " #{'NOT ' unless perform}to be performed.\n" \
-    "The following operations has been actually performed:"
-  end
-
-  failure_message do
-    text = describe_expectations(name, true)
-    actual_operations.each.with_index(1) do |(key, opts), index|
-      text << format("\n   %02d) #{key} with #{opts}", index)
-    end
-    text
-  end
 
-  failure_message_when_negated do
-    text = describe_expectations(name, false)
-    actual_operations.each.with_index(1) do |(key, opts), index|
-      marker = performed(name, block_arg) == [key, opts] ? "->" : "  "
-      text << format("\n#{marker} % 2d) #{key} with #{opts}", index)
+    def unstub_all
+      allow(Evil::Client::Container::Operation)
+        .to receive(:new)
+        .and_call_original
     end
-    text
   end
 end