rack-test 1.1.0 → 2.1.0

data/lib/rack/test.rb

@@ -1,23 +1,52 @@
+# frozen_string_literal: true
+
 require 'uri'
-require 'rack'
-require 'rack/mock_session'
-require 'rack/test/cookie_jar'
-require 'rack/test/mock_digest_request'
-require 'rack/test/utils'
-require 'rack/test/methods'
-require 'rack/test/uploaded_file'
-require 'rack/test/version'
+
+# :nocov:
+begin
+  require "rack/version"
+rescue LoadError
+  require "rack"
+else
+  if Rack.release >= '2.3'
+    require "rack/request"
+    require "rack/mock"
+    require "rack/utils"
+  else
+    require "rack"
+  end
+end
+# :nocov:
+
+require 'forwardable'
+
+require_relative 'test/cookie_jar'
+require_relative 'test/utils'
+require_relative 'test/methods'
+require_relative 'test/uploaded_file'
+require_relative 'test/version'
 
 module Rack
   module Test
+    # The default host to use for requests, when a full URI is not
+    # provided.
     DEFAULT_HOST = 'example.org'.freeze
+
+    # The default multipart boundary to use for multipart request bodies
     MULTIPART_BOUNDARY = '----------XnJLe9ZIbbGUYtzPQJ16u1'.freeze
 
+    # The starting boundary in multipart requests
+    START_BOUNDARY = "--#{MULTIPART_BOUNDARY}\r\n".freeze
+
+    # The ending boundary in multipart requests
+    END_BOUNDARY = "--#{MULTIPART_BOUNDARY}--\r\n".freeze
+
     # The common base class for exceptions raised by Rack::Test
     class Error < StandardError; end
 
-    # This class represents a series of requests issued to a Rack app, sharing
-    # a single cookie jar
+    # Rack::Test::Session handles a series of requests issued to a Rack app.
+    # It keeps track of the cookies for the session, and allows for setting headers
+    # and a default rack environment that is used for future requests.
     #
     # Rack::Test::Session's methods are most often called through Rack::Test::Methods,
     # which will automatically build a session when it's first used.
@@ -25,93 +54,98 @@ module Rack
       extend Forwardable
       include Rack::Test::Utils
 
-      def_delegators :@rack_mock_session, :clear_cookies, :set_cookie, :last_response, :last_request
+      def self.new(app, default_host = DEFAULT_HOST) # :nodoc:
+        if app.is_a?(self)
+          # Backwards compatibility for initializing with Rack::MockSession
+          app
+        else
+          super
+        end
+      end
 
-      # Creates a Rack::Test::Session for a given Rack app or Rack::MockSession.
+      # The Rack::Test::CookieJar for the cookies for the current session.
+      attr_accessor :cookie_jar
+
+      # The default host used for the session for when using paths for URIs.
+      attr_reader :default_host
+
+      # Creates a Rack::Test::Session for a given Rack app or Rack::Test::BasicSession.
       #
       # Note: Generally, you won't need to initialize a Rack::Test::Session directly.
       # Instead, you should include Rack::Test::Methods into your testing context.
       # (See README.rdoc for an example)
-      def initialize(mock_session)
-        @headers = {}
-        @env = {}
-        @digest_username = nil
-        @digest_password = nil
-
-        @rack_mock_session = if mock_session.is_a?(MockSession)
-          mock_session
-        else
-          MockSession.new(mock_session)
-        end
-
-        @default_host = @rack_mock_session.default_host
-      end
-
-      # Issue a GET request for the given URI with the given params and Rack
-      # environment. Stores the issues request object in #last_request and
-      # the app's response in #last_response. Yield #last_response to a block
-      # if given.
       #
-      # Example:
-      #   get "/"
-      def get(uri, params = {}, env = {}, &block)
-        custom_request('GET', uri, params, env, &block)
+      # The following methods are defined via metaprogramming: get, post, put, patch,
+      # delete, options, and head. Each method submits a request with the given request
+      # method, with the given URI and optional parameters and rack environment.
+      # Examples:
+      #
+      #   # URI only:
+      #   get("/")                   # GET /
+      #   get("/?foo=bar")           # GET /?foo=bar
+      #
+      #   # URI and parameters
+      #   get("/foo", 'bar'=>'baz')  # GET /foo?bar=baz
+      #   post("/foo", 'bar'=>'baz') # POST /foo (bar=baz in request body)
+      #
+      #   # URI, parameters, and rack environment
+      #   get("/bar", {}, 'CONTENT_TYPE'=>'foo')
+      #   get("/bar", {'foo'=>'baz'}, 'HTTP_ACCEPT'=>'*')
+      #
+      # The above methods as well as #request and #custom_request store the Rack::Request
+      # submitted in #last_request. The methods store a Rack::MockResponse based on the
+      # response in #last_response. #last_response is also returned by the methods.
+      # If a block is given, #last_response is also yielded to the block.
+      def initialize(app, default_host = DEFAULT_HOST)
+        @env = {}
+        @app = app
+        @after_request = []
+        @default_host = default_host
+        @last_request = nil
+        @last_response = nil
+        clear_cookies
       end
 
-      # Issue a POST request for the given URI. See #get
-      #
-      # Example:
-      #   post "/signup", "name" => "Bryan"
-      def post(uri, params = {}, env = {}, &block)
-        custom_request('POST', uri, params, env, &block)
+      %w[get post put patch delete options head].each do |method_name|
+        class_eval(<<-END, __FILE__, __LINE__+1)
+          def #{method_name}(uri, params = {}, env = {}, &block)
+            custom_request('#{method_name.upcase}', uri, params, env, &block)
+          end
+        END
       end
 
-      # Issue a PUT request for the given URI. See #get
-      #
-      # Example:
-      #   put "/"
-      def put(uri, params = {}, env = {}, &block)
-        custom_request('PUT', uri, params, env, &block)
+      # Run a block after the each request completes.
+      def after_request(&block)
+        @after_request << block
       end
 
-      # Issue a PATCH request for the given URI. See #get
-      #
-      # Example:
-      #   patch "/"
-      def patch(uri, params = {}, env = {}, &block)
-        custom_request('PATCH', uri, params, env, &block)
+      # Replace the current cookie jar with an empty cookie jar.
+      def clear_cookies
+        @cookie_jar = CookieJar.new([], @default_host)
       end
 
-      # Issue a DELETE request for the given URI. See #get
-      #
-      # Example:
-      #   delete "/"
-      def delete(uri, params = {}, env = {}, &block)
-        custom_request('DELETE', uri, params, env, &block)
+      # Set a cookie in the current cookie jar.
+      def set_cookie(cookie, uri = nil)
+        cookie_jar.merge(cookie, uri)
       end
 
-      # Issue an OPTIONS request for the given URI. See #get
-      #
-      # Example:
-      #   options "/"
-      def options(uri, params = {}, env = {}, &block)
-        custom_request('OPTIONS', uri, params, env, &block)
+      # Return the last request issued in the session. Raises an error if no
+      # requests have been sent yet.
+      def last_request
+        raise Error, 'No request yet. Request a page first.' unless @last_request
+        @last_request
       end
 
-      # Issue a HEAD request for the given URI. See #get
-      #
-      # Example:
-      #   head "/"
-      def head(uri, params = {}, env = {}, &block)
-        custom_request('HEAD', uri, params, env, &block)
+      # Return the last response received in the session. Raises an error if
+      # no requests have been sent yet.
+      def last_response
+        raise Error, 'No response yet. Request a page first.' unless @last_response
+        @last_response
       end
 
       # Issue a request to the Rack app for the given URI and optional Rack
-      # environment. Stores the issues request object in #last_request and
-      # the app's response in #last_response. Yield #last_response to a block
-      # if given.
+      # environment.  Example:
       #
-      # Example:
       #   request "/"
       def request(uri, env = {}, &block)
         uri = parse_uri(uri, env)
@@ -119,9 +153,9 @@ module Rack
         process_request(uri, env, &block)
       end
 
-      # Issue a request using the given verb for the given URI. See #get
+      # Issue a request using the given HTTP verb for the given URI, with optional
+      # params and rack environment.  Example:
       #
-      # Example:
       #   custom_request "LINK", "/"
       def custom_request(verb, uri, params = {}, env = {}, &block)
         uri = parse_uri(uri, env)
@@ -133,22 +167,20 @@ module Rack
       # session. Use a value of nil to remove a previously configured header.
       #
       # In accordance with the Rack spec, headers will be included in the Rack
-      # environment hash in HTTP_USER_AGENT form.
+      # environment hash in HTTP_USER_AGENT form.  Example:
       #
-      # Example:
-      #   header "User-Agent", "Firefox"
+      #   header "user-agent", "Firefox"
       def header(name, value)
-        if value.nil?
-          @headers.delete(name)
-        else
-          @headers[name] = value
-        end
+        name = name.upcase
+        name.tr!('-', '_')
+        name = "HTTP_#{name}" unless name == 'CONTENT_TYPE' || name == 'CONTENT_LENGTH'
+        env(name, value)
       end
 
-      # Set an env var to be included on all subsequent requests through the
-      # session. Use a value of nil to remove a previously configured env.
+      # Set an entry in the rack environment to be included on all subsequent
+      # requests through the session. Use a value of nil to remove a previously
+      # value.  Example:
       #
-      # Example:
       #   env "rack.session", {:csrf => 'token'}
       def env(name, value)
         if value.nil?
@@ -170,16 +202,6 @@ module Rack
 
       alias authorize basic_authorize
 
-      # Set the username and password for HTTP Digest authorization, to be
-      # included in subsequent requests in the HTTP_AUTHORIZATION header.
-      #
-      # Example:
-      #   digest_authorize "bryan", "secret"
-      def digest_authorize(username, password)
-        @digest_username = username
-        @digest_password = password
-      end
-
       # Rack::Test will not follow any redirects automatically. This method
       # will follow the redirect returned (including setting the Referer header
       # on the new request) in the last response. If the last response was not
@@ -188,147 +210,173 @@ module Rack
         unless last_response.redirect?
           raise Error, 'Last response was not a redirect. Cannot follow_redirect!'
         end
-        request_method, params =
-          if last_response.status == 307
-            [last_request.request_method.downcase.to_sym, last_request.params]
-          else
-            [:get, {}]
-          end
+
+        if last_response.status == 307
+          request_method = last_request.request_method
+          params = last_request.params
+        else
+          request_method = 'GET'
+          params = {}
+        end
 
         # Compute the next location by appending the location header with the
         # last request, as per https://tools.ietf.org/html/rfc7231#section-7.1.2
         # Adding two absolute locations returns the right-hand location
         next_location = URI.parse(last_request.url) + URI.parse(last_response['Location'])
 
-        send(
-          request_method, next_location.to_s, params,
+        custom_request(
+          request_method,
+          next_location.to_s,
+          params,
           'HTTP_REFERER' => last_request.url,
           'rack.session' => last_request.session,
           'rack.session.options' => last_request.session_options
         )
       end
 
+      # Yield to the block, and restore the last request, last response, and
+      # cookie jar to the state they were prior to block execution upon
+      # exiting the block.
+      def restore_state
+        request = @last_request
+        response = @last_response
+        cookie_jar = @cookie_jar.dup
+        after_request = @after_request.dup
+
+        begin
+          yield
+        ensure
+          @last_request = request
+          @last_response = response
+          @cookie_jar = cookie_jar
+          @after_request = after_request
+        end
+      end
+
       private
 
-      def parse_uri(path, env)
-        URI.parse(path).tap do |uri|
-          uri.path = "/#{uri.path}" unless uri.path[0] == '/'
-          uri.host ||= @default_host
-          uri.scheme ||= 'https' if env['HTTPS'] == 'on'
+      # :nocov:
+      if !defined?(Rack::RELEASE) || Gem::Version.new(Rack::RELEASE) < Gem::Version.new('2.2.2')
+        def close_body(body)
+          body.close if body.respond_to?(:close)
+        end
+      # :nocov:
+      else
+        # close() gets called automatically in newer Rack versions.
+        def close_body(body)
         end
       end
 
+      # Normalize URI based on given URI/path and environment.
+      def parse_uri(path, env)
+        uri = URI.parse(path)
+        uri.path = "/#{uri.path}" unless uri.path.start_with?('/')
+        uri.host ||= @default_host
+        uri.scheme ||= 'https' if env['HTTPS'] == 'on'
+        uri
+      end
+
+      DEFAULT_ENV = {
+        'rack.test' => true,
+        'REMOTE_ADDR' => '127.0.0.1',
+        'SERVER_PROTOCOL' => 'HTTP/1.0',
+      }
+      # :nocov:
+      unless Rack.release >= '2.3'
+        DEFAULT_ENV['HTTP_VERSION'] = DEFAULT_ENV['SERVER_PROTOCOL']
+      end
+      # :nocov:
+      DEFAULT_ENV.freeze
+      private_constant :DEFAULT_ENV
+
+      # Update environment to use based on given URI.
       def env_for(uri, env)
-        env = default_env.merge(env)
+        env = DEFAULT_ENV.merge(@env).merge!(env)
 
         env['HTTP_HOST'] ||= [uri.host, (uri.port if uri.port != uri.default_port)].compact.join(':')
-
-        env.update('HTTPS' => 'on') if URI::HTTPS === uri
+        env['HTTPS'] = 'on' if URI::HTTPS === uri
         env['HTTP_X_REQUESTED_WITH'] = 'XMLHttpRequest' if env[:xhr]
-
-        # TODO: Remove this after Rack 1.1 has been released.
-        # Stringifying and upcasing methods has be commit upstream
         env['REQUEST_METHOD'] ||= env[:method] ? env[:method].to_s.upcase : 'GET'
 
-        params = env.delete(:params) do {} end
+        params = env.delete(:params)
+        query_array = [uri.query]
 
         if env['REQUEST_METHOD'] == 'GET'
-          # merge :params with the query string
+          # Treat params as query params
           if params
-            params = parse_nested_query(params) if params.is_a?(String)
-
-            uri.query = [uri.query, build_nested_query(params)].compact.reject { |v| v == '' }.join('&')
+            append_query_params(query_array, params)
           end
         elsif !env.key?(:input)
           env['CONTENT_TYPE'] ||= 'application/x-www-form-urlencoded'
+          params ||= {}
+          multipart = env.has_key?(:multipart) ? env.delete(:multipart) : env['CONTENT_TYPE'].start_with?('multipart/')
 
           if params.is_a?(Hash)
-            if data = build_multipart(params)
+            if !params.empty? && data = build_multipart(params, false, multipart)
               env[:input] = data
               env['CONTENT_LENGTH'] ||= data.length.to_s
-              env['CONTENT_TYPE'] = "multipart/form-data; boundary=#{MULTIPART_BOUNDARY}"
+              env['CONTENT_TYPE'] = "#{multipart_content_type(env)}; boundary=#{MULTIPART_BOUNDARY}"
             else
-              # NB: We do not need to set CONTENT_LENGTH here;
-              # Rack::ContentLength will determine it automatically.
-              env[:input] = params_to_string(params)
+              env[:input] = build_nested_query(params)
             end
           else
             env[:input] = params
           end
         end
 
+        if query_params = env.delete(:query_params)
+          append_query_params(query_array, query_params)
+        end
+        query_array.compact!
+        query_array.reject!(&:empty?)
+        uri.query = query_array.join('&')
+
         set_cookie(env.delete(:cookie), uri) if env.key?(:cookie)
 
         Rack::MockRequest.env_for(uri.to_s, env)
       end
 
-      def process_request(uri, env)
-        @rack_mock_session.request(uri, env)
+      # Append a string version of the query params to the array of query params.
+      def append_query_params(query_array, query_params)
+        query_params = parse_nested_query(query_params) if query_params.is_a?(String)
+        query_array << build_nested_query(query_params)
+      end
 
-        if retry_with_digest_auth?(env)
-          auth_env = env.merge('HTTP_AUTHORIZATION' => digest_auth_header,
-                               'rack-test.digest_auth_retry' => true)
-          auth_env.delete('rack.request')
-          process_request(uri.path, auth_env)
+      # Return the multipart content type to use based on the environment.
+      def multipart_content_type(env)
+        requested_content_type = env['CONTENT_TYPE']
+        if requested_content_type.start_with?('multipart/')
+          requested_content_type
         else
-          yield last_response if block_given?
-
-          last_response
+          'multipart/form-data'
         end
       end
 
-      def digest_auth_header
-        challenge = last_response['WWW-Authenticate'].split(' ', 2).last
-        params = Rack::Auth::Digest::Params.parse(challenge)
-
-        params.merge!('username' => @digest_username,
-                      'nc'        => '00000001',
-                      'cnonce'    => 'nonsensenonce',
-                      'uri'       => last_request.fullpath,
-                      'method'    => last_request.env['REQUEST_METHOD'])
-
-        params['response'] = MockDigestRequest.new(params).response(@digest_password)
-
-        "Digest #{params}"
-      end
-
-      def retry_with_digest_auth?(env)
-        last_response.status == 401 &&
-          digest_auth_configured? &&
-          !env['rack-test.digest_auth_retry']
-      end
-
-      def digest_auth_configured?
-        @digest_username
-      end
-
-      def default_env
-        { 'rack.test' => true, 'REMOTE_ADDR' => '127.0.0.1' }.merge(@env).merge(headers_for_env)
-      end
-
-      def headers_for_env
-        converted_headers = {}
+      # Submit the request with the given URI and rack environment to
+      # the mock session.  Returns and potentially yields the last response.
+      def process_request(uri, env)
+        env['HTTP_COOKIE'] ||= cookie_jar.for(uri)
+        @last_request = Rack::Request.new(env)
+        status, headers, body = @app.call(env).to_a
 
-        @headers.each do |name, value|
-          env_key = name.upcase.tr('-', '_')
-          env_key = 'HTTP_' + env_key unless env_key == 'CONTENT_TYPE'
-          converted_headers[env_key] = value
-        end
+        @last_response = MockResponse.new(status, headers, body, env['rack.errors'].flush)
+        close_body(body)
+        cookie_jar.merge(last_response.headers['set-cookie'], uri)
+        @after_request.each(&:call)
+        @last_response.finish
 
-        converted_headers
-      end
+        yield @last_response if block_given?
 
-      def params_to_string(params)
-        case params
-        when Hash then build_nested_query(params)
-        when nil  then ''
-        else params
-        end
+        @last_response
       end
     end
 
+    # Whether the version of rack in use handles encodings.
     def self.encoding_aware_strings?
-      defined?(Encoding) && ''.respond_to?(:encode)
+      Rack.release >= '1.6'
     end
   end
+
+  # For backwards compatibility with 1.1.0 and below
+  MockSession = Test::Session
 end