faraday 0.9.1 → 1.8.0

data/Rakefile

@@ -1,71 +1,7 @@
-require 'date'
-require 'fileutils'
-require 'openssl'
-require 'rake/testtask'
-require 'bundler'
-Bundler::GemHelper.install_tasks
+# frozen_string_literal: true
 
-task :default => :test
+require 'rspec/core/rake_task'
 
-## helper functions
+RSpec::Core::RakeTask.new(:spec)
 
-def name
-  @name ||= Dir['*.gemspec'].first.split('.').first
-end
-
-def version
-  line = File.read("lib/#{name}.rb")[/^\s*VERSION\s*=\s*.*/]
-  line.match(/.*VERSION\s*=\s*['"](.*)['"]/)[1]
-end
-
-def gemspec_file
-  "#{name}.gemspec"
-end
-
-def gem_file
-  "#{name}-#{version}.gem"
-end
-
-def replace_header(head, header_name)
-  head.sub!(/(\.#{header_name}\s*= ').*'/) { "#{$1}#{send(header_name)}'"}
-end
-
-# Adapted from WEBrick::Utils. Skips cert extensions so it
-# can be used as a CA bundle
-def create_self_signed_cert(bits, cn, comment)
-  rsa = OpenSSL::PKey::RSA.new(bits)
-  cert = OpenSSL::X509::Certificate.new
-  cert.version = 2
-  cert.serial = 1
-  name = OpenSSL::X509::Name.new(cn)
-  cert.subject = name
-  cert.issuer = name
-  cert.not_before = Time.now
-  cert.not_after = Time.now + (365*24*60*60)
-  cert.public_key = rsa.public_key
-  cert.sign(rsa, OpenSSL::Digest::SHA1.new)
-  return [cert, rsa]
-end
-
-## standard tasks
-
-desc "Run all tests"
-task :test do
-  exec 'script/test'
-end
-
-desc "Generate certificates for SSL tests"
-task :'test:generate_certs' do
-  cert, key = create_self_signed_cert(1024, [['CN', 'localhost']], 'Faraday Test CA')
-  FileUtils.mkdir_p 'tmp'
-  File.open('tmp/faraday-cert.key', 'w') {|f| f.puts(key) }
-  File.open('tmp/faraday-cert.crt', 'w') {|f| f.puts(cert.to_s) }
-end
-
-file 'tmp/faraday-cert.key' => :'test:generate_certs'
-file 'tmp/faraday-cert.crt' => :'test:generate_certs'
-
-desc "Open an irb session preloaded with this library"
-task :console do
-  sh "irb -rubygems -r ./lib/#{name}.rb"
-end
+task default: :spec

data/examples/client_spec.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+# Requires Ruby with rspec and faraday gems.
+# rspec client_spec.rb
+
+require 'faraday'
+require 'json'
+
+# Example API client
+class Client
+  def initialize(conn)
+    @conn = conn
+  end
+
+  def sushi(jname, params: {})
+    res = @conn.get("/#{jname}", params)
+    data = JSON.parse(res.body)
+    data['name']
+  end
+end
+
+RSpec.describe Client do
+  let(:stubs)  { Faraday::Adapter::Test::Stubs.new }
+  let(:conn)   { Faraday.new { |b| b.adapter(:test, stubs) } }
+  let(:client) { Client.new(conn) }
+
+  it 'parses name' do
+    stubs.get('/ebi') do |env|
+      # optional: you can inspect the Faraday::Env
+      expect(env.url.path).to eq('/ebi')
+      [
+        200,
+        { 'Content-Type': 'application/javascript' },
+        '{"name": "shrimp"}'
+      ]
+    end
+
+    # uncomment to trigger stubs.verify_stubbed_calls failure
+    # stubs.get('/unused') { [404, {}, ''] }
+
+    expect(client.sushi('ebi')).to eq('shrimp')
+    stubs.verify_stubbed_calls
+  end
+
+  it 'handles 404' do
+    stubs.get('/ebi') do
+      [
+        404,
+        { 'Content-Type': 'application/javascript' },
+        '{}'
+      ]
+    end
+    expect(client.sushi('ebi')).to be_nil
+    stubs.verify_stubbed_calls
+  end
+
+  it 'handles exception' do
+    stubs.get('/ebi') do
+      raise Faraday::ConnectionFailed, nil
+    end
+
+    expect { client.sushi('ebi') }.to raise_error(Faraday::ConnectionFailed)
+    stubs.verify_stubbed_calls
+  end
+
+  context 'When the test stub is run in strict_mode' do
+    let(:stubs) { Faraday::Adapter::Test::Stubs.new(strict_mode: true) }
+
+    it 'verifies the all parameter values are identical' do
+      stubs.get('/ebi?abc=123') do
+        [
+          200,
+          { 'Content-Type': 'application/javascript' },
+          '{"name": "shrimp"}'
+        ]
+      end
+
+      # uncomment to raise Stubs::NotFound
+      # expect(client.sushi('ebi', params: { abc: 123, foo: 'Kappa' })).to eq('shrimp')
+      expect(client.sushi('ebi', params: { abc: 123 })).to eq('shrimp')
+      stubs.verify_stubbed_calls
+    end
+  end
+
+  context 'When the Faraday connection is configured with FlatParamsEncoder' do
+    let(:conn) { Faraday.new(request: { params_encoder: Faraday::FlatParamsEncoder }) { |b| b.adapter(:test, stubs) } }
+
+    it 'handles the same multiple URL parameters' do
+      stubs.get('/ebi?a=x&a=y&a=z') { [200, { 'Content-Type' => 'application/json' }, '{"name": "shrimp"}'] }
+
+      # uncomment to raise Stubs::NotFound
+      # expect(client.sushi('ebi', params: { a: %w[x y] })).to eq('shrimp')
+      expect(client.sushi('ebi', params: { a: %w[x y z] })).to eq('shrimp')
+      stubs.verify_stubbed_calls
+    end
+  end
+end

data/examples/client_test.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+# Requires Ruby with test-unit and faraday gems.
+# ruby client_test.rb
+
+require 'faraday'
+require 'json'
+require 'test/unit'
+
+# Example API client
+class Client
+  def initialize(conn)
+    @conn = conn
+  end
+
+  def sushi(jname, params: {})
+    res = @conn.get("/#{jname}", params)
+    data = JSON.parse(res.body)
+    data['name']
+  end
+end
+
+# Example API client test
+class ClientTest < Test::Unit::TestCase
+  def test_sushi_name
+    stubs = Faraday::Adapter::Test::Stubs.new
+    stubs.get('/ebi') do |env|
+      # optional: you can inspect the Faraday::Env
+      assert_equal '/ebi', env.url.path
+      [
+        200,
+        { 'Content-Type': 'application/javascript' },
+        '{"name": "shrimp"}'
+      ]
+    end
+
+    # uncomment to trigger stubs.verify_stubbed_calls failure
+    # stubs.get('/unused') { [404, {}, ''] }
+
+    cli = client(stubs)
+    assert_equal 'shrimp', cli.sushi('ebi')
+    stubs.verify_stubbed_calls
+  end
+
+  def test_sushi_404
+    stubs = Faraday::Adapter::Test::Stubs.new
+    stubs.get('/ebi') do
+      [
+        404,
+        { 'Content-Type': 'application/javascript' },
+        '{}'
+      ]
+    end
+
+    cli = client(stubs)
+    assert_nil cli.sushi('ebi')
+    stubs.verify_stubbed_calls
+  end
+
+  def test_sushi_exception
+    stubs = Faraday::Adapter::Test::Stubs.new
+    stubs.get('/ebi') do
+      raise Faraday::ConnectionFailed, nil
+    end
+
+    cli = client(stubs)
+    assert_raise Faraday::ConnectionFailed do
+      cli.sushi('ebi')
+    end
+    stubs.verify_stubbed_calls
+  end
+
+  def test_strict_mode
+    stubs = Faraday::Adapter::Test::Stubs.new(strict_mode: true)
+    stubs.get('/ebi?abc=123') do
+      [
+        200,
+        { 'Content-Type': 'application/javascript' },
+        '{"name": "shrimp"}'
+      ]
+    end
+
+    cli = client(stubs)
+    assert_equal 'shrimp', cli.sushi('ebi', params: { abc: 123 })
+
+    # uncomment to raise Stubs::NotFound
+    # assert_equal 'shrimp', cli.sushi('ebi', params: { abc: 123, foo: 'Kappa' })
+    stubs.verify_stubbed_calls
+  end
+
+  def test_non_default_params_encoder
+    stubs = Faraday::Adapter::Test::Stubs.new(strict_mode: true)
+    stubs.get('/ebi?a=x&a=y&a=z') do
+      [
+        200,
+        { 'Content-Type': 'application/javascript' },
+        '{"name": "shrimp"}'
+      ]
+    end
+    conn = Faraday.new(request: { params_encoder: Faraday::FlatParamsEncoder }) do |builder|
+      builder.adapter :test, stubs
+    end
+
+    cli = Client.new(conn)
+    assert_equal 'shrimp', cli.sushi('ebi', params: { a: %w[x y z] })
+
+    # uncomment to raise Stubs::NotFound
+    # assert_equal 'shrimp', cli.sushi('ebi', params: { a: %w[x y] })
+    stubs.verify_stubbed_calls
+  end
+
+  def client(stubs)
+    conn = Faraday.new do |builder|
+      builder.adapter :test, stubs
+    end
+    Client.new(conn)
+  end
+end

data/lib/faraday/adapter/test.rb

@@ -1,26 +1,60 @@
+# frozen_string_literal: true
+
 module Faraday
   class Adapter
-    # test = Faraday::Connection.new do
-    #   use Faraday::Adapter::Test do |stub|
-    #     stub.get '/nigiri/sake.json' do
-    #       [200, {}, 'hi world']
+    # @example
+    #   test = Faraday::Connection.new do
+    #     use Faraday::Adapter::Test do |stub|
+    #       # Define matcher to match the request
+    #       stub.get '/resource.json' do
+    #         # return static content
+    #         [200, {'Content-Type' => 'application/json'}, 'hi world']
+    #       end
+    #
+    #       # response with content generated based on request
+    #       stub.get '/showget' do |env|
+    #         [200, {'Content-Type' => 'text/plain'}, env[:method].to_s]
+    #       end
+    #
+    #       # A regular expression can be used as matching filter
+    #       stub.get /\A\/items\/(\d+)\z/ do |env, meta|
+    #         # in case regular expression is used, an instance of MatchData
+    #         # can be received
+    #         [200,
+    #          {'Content-Type' => 'text/plain'},
+    #          "showing item: #{meta[:match_data][1]}"
+    #         ]
+    #       end
+    #
+    #       # You can set strict_mode to exactly match the stubbed requests.
+    #       stub.strict_mode = true
     #     end
     #   end
-    # end
     #
-    # resp = test.get '/nigiri/sake.json'
-    # resp.body # => 'hi world'
+    #   resp = test.get '/resource.json'
+    #   resp.body # => 'hi world'
     #
+    #   resp = test.get '/showget'
+    #   resp.body # => 'get'
+    #
+    #   resp = test.get '/items/1'
+    #   resp.body # => 'showing item: 1'
+    #
+    #   resp = test.get '/items/2'
+    #   resp.body # => 'showing item: 2'
     class Test < Faraday::Adapter
       attr_accessor :stubs
 
+      # A stack of Stubs
       class Stubs
         class NotFound < StandardError
         end
 
-        def initialize
-          # {:get => [Stub, Stub]}
-          @stack, @consumed = {}, {}
+        def initialize(strict_mode: false)
+          # { get: [Stub, Stub] }
+          @stack = {}
+          @consumed = {}
+          @strict_mode = strict_mode
           yield(self) if block_given?
         end
 
@@ -28,17 +62,20 @@ module Faraday
           @stack.empty?
         end
 
-        def match(request_method, path, headers, body)
-          return false if !@stack.key?(request_method)
+        # @param env [Faraday::Env]
+        def match(env)
+          request_method = env[:method]
+          return false unless @stack.key?(request_method)
+
           stack = @stack[request_method]
           consumed = (@consumed[request_method] ||= [])
 
-          if stub = matches?(stack, path, headers, body)
+          stub, meta = matches?(stack, env)
+          if stub
             consumed << stack.delete(stub)
-            stub
-          else
-            matches?(consumed, path, headers, body)
+            return stub, meta
           end
+          matches?(consumed, env)
         end
 
         def get(path, headers = {}, &block)
@@ -49,15 +86,15 @@ module Faraday
           new_stub(:head, path, headers, &block)
         end
 
-        def post(path, body=nil, headers = {}, &block)
+        def post(path, body = nil, headers = {}, &block)
           new_stub(:post, path, headers, body, &block)
         end
 
-        def put(path, body=nil, headers = {}, &block)
+        def put(path, body = nil, headers = {}, &block)
           new_stub(:put, path, headers, body, &block)
         end
 
-        def patch(path, body=nil, headers = {}, &block)
+        def patch(path, body = nil, headers = {}, &block)
           new_stub(:patch, path, headers, body, &block)
         end
 
@@ -73,54 +110,109 @@ module Faraday
         def verify_stubbed_calls
           failed_stubs = []
           @stack.each do |method, stubs|
-            unless stubs.size == 0
-              failed_stubs.concat(stubs.map {|stub|
+            next if stubs.empty?
+
+            failed_stubs.concat(
+              stubs.map do |stub|
                 "Expected #{method} #{stub}."
-              })
+              end
+            )
+          end
+          raise failed_stubs.join(' ') unless failed_stubs.empty?
+        end
+
+        # Set strict_mode. If the value is true, this adapter tries to find matched requests strictly,
+        # which means that all of a path, parameters, and headers must be the same as an actual request.
+        def strict_mode=(value)
+          @strict_mode = value
+          @stack.each do |_method, stubs|
+            stubs.each do |stub|
+              stub.strict_mode = value
             end
           end
-          raise failed_stubs.join(" ") unless failed_stubs.size == 0
         end
 
         protected
 
-        def new_stub(request_method, path, headers = {}, body=nil, &block)
-          normalized_path = Faraday::Utils.normalize_path(path)
-          (@stack[request_method] ||= []) << Stub.new(normalized_path, headers, body, block)
+        def new_stub(request_method, path, headers = {}, body = nil, &block)
+          normalized_path, host =
+            if path.is_a?(Regexp)
+              path
+            else
+              [
+                Faraday::Utils.normalize_path(path),
+                Faraday::Utils.URI(path).host
+              ]
+            end
+          path, query = normalized_path.respond_to?(:split) ? normalized_path.split('?') : normalized_path
+          headers = Utils::Headers.new(headers)
+
+          stub = Stub.new(host, path, query, headers, body, @strict_mode, block)
+          (@stack[request_method] ||= []) << stub
         end
 
-        def matches?(stack, path, headers, body)
-          stack.detect { |stub| stub.matches?(path, headers, body) }
+        # @param stack [Hash]
+        # @param env [Faraday::Env]
+        def matches?(stack, env)
+          stack.each do |stub|
+            match_result, meta = stub.matches?(env)
+            return stub, meta if match_result
+          end
+          nil
         end
       end
 
-      class Stub < Struct.new(:path, :params, :headers, :body, :block)
-        def initialize(full, headers, body, block)
-          path, query = full.split('?')
-          params = query ?
-            Faraday::Utils.parse_nested_query(query) :
-            {}
-          super(path, params, headers, body, block)
-        end
-
-        def matches?(request_uri, request_headers, request_body)
-          request_path, request_query = request_uri.split('?')
-          request_params = request_query ?
-            Faraday::Utils.parse_nested_query(request_query) :
-            {}
-          request_path == path &&
-            params_match?(request_params) &&
+      # Stub request
+      class Stub < Struct.new(:host, :path, :query, :headers, :body, :strict_mode, :block) # rubocop:disable Style/StructInheritance
+        # @param env [Faraday::Env]
+        def matches?(env)
+          request_host = env[:url].host
+          request_path = Faraday::Utils.normalize_path(env[:url].path)
+          request_headers = env.request_headers
+          request_body = env[:body]
+
+          # meta is a hash used as carrier
+          # that will be yielded to consumer block
+          meta = {}
+          [(host.nil? || host == request_host) &&
+            path_match?(request_path, meta) &&
+            params_match?(env) &&
             (body.to_s.size.zero? || request_body == body) &&
-            headers_match?(request_headers)
+            headers_match?(request_headers), meta]
         end
 
-        def params_match?(request_params)
+        def path_match?(request_path, meta)
+          if path.is_a?(Regexp)
+            !!(meta[:match_data] = path.match(request_path))
+          else
+            path == request_path
+          end
+        end
+
+        # @param env [Faraday::Env]
+        def params_match?(env)
+          request_params = env[:params]
+          params = env.params_encoder.decode(query) || {}
+
+          if strict_mode
+            return Set.new(params) == Set.new(request_params)
+          end
+
           params.keys.all? do |key|
             request_params[key] == params[key]
           end
         end
 
         def headers_match?(request_headers)
+          if strict_mode
+            headers_with_user_agent = headers.dup.tap do |hs|
+              # NOTE: Set User-Agent in case it's not set when creating Stubs.
+              #       Users would not want to set Faraday's User-Agent explicitly.
+              hs[:user_agent] ||= Connection::USER_AGENT
+            end
+            return Set.new(headers_with_user_agent) == Set.new(request_headers)
+          end
+
           headers.keys.all? do |key|
             request_headers[key] == headers[key]
           end
@@ -131,7 +223,7 @@ module Faraday
         end
       end
 
-      def initialize(app, stubs=nil, &block)
+      def initialize(app, stubs = nil, &block)
         super(app)
         @stubs = stubs || Stubs.new
         configure(&block) if block
@@ -141,20 +233,28 @@ module Faraday
         yield(stubs)
       end
 
+      # @param env [Faraday::Env]
       def call(env)
         super
-        normalized_path = Faraday::Utils.normalize_path(env[:url])
-        params_encoder = env.request.params_encoder || Faraday::Utils.default_params_encoder
-
-        if stub = stubs.match(env[:method], normalized_path, env.request_headers, env[:body])
-          env[:params] = (query = env[:url].query) ?
-            params_encoder.decode(query)  :
-            {}
-          status, headers, body = stub.block.call(env)
-          save_response(env, status, body, headers)
-        else
-          raise Stubs::NotFound, "no stubbed request for #{env[:method]} #{normalized_path} #{env[:body]}"
+
+        env.request.params_encoder ||= Faraday::Utils.default_params_encoder
+        env[:params] = env.params_encoder.decode(env[:url].query) || {}
+        stub, meta = stubs.match(env)
+
+        unless stub
+          raise Stubs::NotFound, "no stubbed request for #{env[:method]} "\
+                                 "#{env[:url]} #{env[:body]}"
         end
+
+        block_arity = stub.block.arity
+        status, headers, body =
+          if block_arity >= 0
+            stub.block.call(*[env, meta].take(block_arity))
+          else
+            stub.block.call(env, meta)
+          end
+        save_response(env, status, body, headers)
+
         @app.call(env)
       end
     end