fake_mechanize 0.0.1 → 0.0.2

data/README.rdoc

@@ -1,12 +1,65 @@
 = fake-mechanize
 
 == DESCRIPTION
-Description goes here.
+FakeMechanize provides methods and classes to write offline tests for applications which relies on Mechanize.
+It replace Mechanize and emulate an agent which aim to act like a real Mechanize Agent.
+Fake agent accepts options to define queries and their answers.
 
 == SYNOPSIS
 === Options
 === Types
 === Examples
+* Simple examples to test a basic api
+
+   # Initialize a fake agent
+   @http_agent = FakeMechanize::Agent.new
+
+   # Create answers and their params
+   @http_agent.respond_to do |mock|
+
+     # Answers to get queries to http://api.example.com/users/count?group=students
+     # with the string "42"
+     mock.get :uri => "http://api.example.com/users/count",
+              :parameters => {:group => "students"},
+              :body => "42"
+
+     # Answers to post queries to http://api.example.com/users/3/activate
+     # with the string "true"
+     mock.post :uri => "http://api.example.com/users/3/activate",
+               :body => "true"
+
+     # Answers to post queries to http://api.example.com/users/authentify
+     # with the string "Qt5c1HWwCXDhKskMrBqMdQ".
+     # This example could be an authentication process
+     mock.post   :uri => "http://api.example.com/users/authentify",
+                 :parameters   => {:Email => 'jack@bauer.com', :Passwd => 'secure'},
+                 :body => "Qt5c1HWwCXDhKskMrBqMdQ"
+
+     # Will reply with an http error code of 403 with no body if the post query
+     # to http://api.example.com/users/authentify does not have specified parameters.
+     mock.error  :uri => "http://api.example.com/users/authentify",
+                :params_not_equal  => {:Email => 'jack@bauer.com', :Passwd => 'secure'},
+                :method => :post,
+                :status => 403
+   end
+   
+   # Now you can use this agent like a real one
+   r = mock.get("http://api.example.com/users/count", :group => "students")
+   # => WWW::Mechanize::File
+   r.body # => "42"
+ 
+   # Posting
+   r = mock.post("http://api.example.com/users/authentify",
+                 :Email => "jack@bauer.com", :Passwd => "secure")
+   r.status # => 200
+   r.body   # => "Qt5c1HWwCXDhKskMrBqMdQ"
+ 
+   # Handling errors
+   r = mock.post("http://api.example.com/users/authentify",
+                 :Email => "jack@bauer.com", :Passwd => "bad")
+   r.status # => 403
+   r.body   # => nil
+ 
 
 == REQUIREMENTS
 

data/Rakefile

@@ -42,7 +42,16 @@ end
 
 task :default => :test
 
-desc "build rdoc using hanna theme"
-task :rdoc do
-  `rm -rf rdoc && rdoc --op=rdoc --title=FakeMechanize --inline-source --format=darkfish LICENSE README* lib/**/*.rb`
-end
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION')
+    version = File.read('VERSION')
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "FakeMechanize #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -1 +1 @@
-0.0.1
+0.0.2

data/examples/tiny_url.rb

@@ -0,0 +1,46 @@
+require 'rubygems'
+require 'fake_mechanize'
+require 'test/unit'
+
+# Small module to transform an url into its tiny form through TinyURL service.
+module TinyUrl
+  TinyMatch         = /http:\/\/tinyurl.com\/[a-z0-9]+/i
+  ApiAddress        = "http://tinyurl.com/api-create.php"
+  
+  class << self
+    def url_to_tiny(url)
+      return url if url.match(TinyMatch)
+      @cache      ||= {}
+      @cache[url] ||= mechanize_agent.get(ApiAddress, :url => url).body
+    end
+  
+    def mechanize_agent
+      @agent ||= WWW::Mechanize.new
+    end
+  end
+end
+
+# Test code part
+# First, we have to define a FakeMechanize::Agent with some urls and their result
+module TinyUrl
+  def self.mechanize_agent
+    if @http_agent.nil?
+      @http_agent = FakeMechanize::Agent.new do |mock|
+        mock.get :uri => ApiAddress,
+          :parameters => {:url => "http://www.google.com"},
+          :body => "http://tinyurl.com/dehdc"
+        mock.get :uri => ApiAddress,
+          :parameters => {:url => "https://rails.lighthouseapp.com/projects/8994-ruby-on-rails/tickets/2702-single-table-inherited-model-generator"},
+          :body => "http://tinyurl.com/pucvt5"
+      end
+    end
+    @http_agent
+  end
+end
+
+# Now, we can write tests on this
+class TinyUrlTest < Test::Unit::TestCase
+  def test_url_to_tiny_should_convert_url
+    assert_equal "http://tinyurl.com/dehdc", TinyUrl::url_to_tiny("http://www.google.com")
+  end
+end

data/lib/fake_mechanize.rb

@@ -1,7 +1,61 @@
+require 'rubygems'
 require 'mechanize'
 
+# = FakeMechanize module
+# FakeMechanize provides methods and classes to write offline tests for applications which relies on Mechanize.
+# == Examples
+#   # Initialize a fake agent
+#   @http_agent = FakeMechanize::Agent.new
+#   
+#   # Create answers and their params
+#   @http_agent.respond_to do |mock|
+#
+#     # Answers to get queries to http://api.example.com/users/count?group=students
+#     # with the string "42"
+#     mock.get :uri => "http://api.example.com/users/count",
+#              :parameters => {:group => "students"},
+#              :body => "42"
+#
+#     # Answers to post queries to http://api.example.com/users/3/activate
+#     # with the string "true"
+#     mock.post :uri => "http://api.example.com/users/3/activate",
+#               :body => "true"
+#
+#     # Answers to post queries to http://api.example.com/users/authentify
+#     # with the string "Qt5c1HWwCXDhKskMrBqMdQ".
+#     # This example could be an authentication process
+#     mock.post   :uri => "http://api.example.com/users/authentify",
+#                 :parameters   => {:Email => 'jack@bauer.com', :Passwd => 'secure'},
+#                 :body => "Qt5c1HWwCXDhKskMrBqMdQ"
+#
+#     # Will reply with an http error code of 403 with no body if the post query
+#     # to http://api.example.com/users/authentify does not have specified parameters.
+#     mock.error  :uri => "http://api.example.com/users/authentify",
+#                 :params_not_equal  => {:Email => 'jack@bauer.com', :Passwd => 'secure'},
+#                 :method => :post,
+#                 :status => 403
+#   end
+#   
+#   # Now you can use this agent like a real one
+#   r = mock.get("http://api.example.com/users/count", :group => "students")
+#   # => WWW::Mechanize::File
+#   r.body # => "42"
+#
+#   # Posting
+#   r = mock.post("http://api.example.com/users/authentify",
+#                 :Email => "jack@bauer.com", :Passwd => "secure")
+#   r.status # => 200
+#   r.body   # => "Qt5c1HWwCXDhKskMrBqMdQ"
+#
+#   # Handling errors
+#   r = mock.post("http://api.example.com/users/authentify",
+#                 :Email => "jack@bauer.com", :Passwd => "bad")
+#   r.status # => 403
+#   r.body   # => nil
+# 
 module FakeMechanize
-  HttpVerbs = [:head, :get, :post, :put, :delete]
+  # Supported http verbs
+  HttpVerbs = [:get, :post]
 end
 
 require 'fake_mechanize/request'

data/lib/fake_mechanize/agent.rb

@@ -1,44 +1,70 @@
-# = FakeMechanize module
-# FakeMechanize provides methods and classes to write tests for applications which relies on Mechanize.
-# == Examples
-# 
 module FakeMechanize
   # Agent acts like the original Mechanize::Agent but totally offline.
   # It provides a respond_to method to predefine queries and their answers.
   class Agent
+    # Represents a cookie jar built from WWW::Mechanize::CookieJar
     attr_accessor :cookie_jar
 
-    def initialize
+    # Create a new fake agent.
+    # Can be initialized with a block, see <tt>respond_to</tt> for more details.
+    def initialize(&block)
       @cookie_jar = WWW::Mechanize::CookieJar.new
       @responses  = []
       @errors     = []
       @history    = []
+      
+      respond_to(&block) if block_given?
     end
   
     def respond_to
       reset_responses!
-      yield Responder.new(@responses, @errors)
+      yield Responder.new(@responses, @errors) if block_given?
       @errors << ErrorRequest.new(:status => 404, :body => "not found")
     end
     
-    def assert_queried(method, uri, params = {})
-      request = Request.new(:method => method, :uri => uri, :request_headers => params)
+    # Returns true if query defined by <tt>method</tt>, <tt>uri</tt> and <tt>options</tt> was made.
+    # False otherwise.
+    # * <tt>method</tt> can be one of the following: :get, :post.
+    # * <tt>uri</tt> is a String that represents the called url.
+    # * <tt>options</tt> is an optional hash to specify parameters, headers ... Only :parameters options is actually supported.
+    def assert_queried(method, uri, options = {})
+      request = Request.new(:method => method, :uri => uri, :parameters => options[:parameters])
       @history.any? {|history_query| history_query == request}
     end
     
+    # Get method. Called like get method from the real Mechanize gem.
+    # Get can be achieved by two ways :
+    # * <tt>options</tt> is a String representing the url to call and <tt>parameters</tt> a hash for the parameters.
+    # * <tt>options</tt> is a Hash with <tt>:url</tt> the url and <tt>:params</tt> the parameters.
+    def get(options, parameters = nil)
+      if options.is_a? Hash
+        # TODO raise a Mechanize exception
+        raise "no url specified" unless url = options[:url]
+        parameters = options[:params]
+      else
+        url = options
+      end
+      return_mechanize_response Request.new(:method => :get, :uri => url, :parameters => parameters)
+    end
+    
+    # Post method. Called like post method from the real Mechanize gem.
+    # <tt>url</tt> is the url to post.
+    # <tt>query</tt> is a Hash of parameters.
+    def post(url, query = {})
+      return_mechanize_response Request.new(:method => :post, :uri => url, :parameters => query)
+    end
+    
     HttpVerbs.each do |method|
       module_eval <<-EOE, __FILE__, __LINE__
-        def was_#{method}?(uri, params = {})
-          assert_queried(:#{method}, uri, params)
-        end
-        
-        def #{method}(uri, args = {})
-          return_mechanize_response Request.new(:method => :#{method}, :uri => uri, :request_headers => args)
+        def was_#{method}?(uri, options = {})
+          assert_queried(:#{method}, uri, options)
         end
       EOE
     end
     
     protected
+    # Add <tt>given_request</tt> to history, search if for a matching query
+    # and returns a response or raise an error if http status is not 200.
     def return_mechanize_response(given_request)
       @history << given_request
       request = search_for_request(given_request)
@@ -47,14 +73,18 @@ module FakeMechanize
       page
     end
     
+    # Search through available <tt>@responses</tt> if <tt>given_request</tt> matches one of the defined responses.
     def search_for_request(given_request)
       @responses.find {|request| request == given_request} || search_for_error_request(given_request)
     end
     
+    # Search an error query in the error query list using match value for a request,
+    # the higher match will be the one returned (see ErrorRequest::match)
     def search_for_error_request(given_request)
       @errors.max_by {|request| request.match(given_request)}
     end
     
+    # Delete all predefined responses
     def reset_responses!
       @responses.clear
     end

data/lib/fake_mechanize/error_request.rb

@@ -1,12 +1,23 @@
 module FakeMechanize
+  # ErrorRequest is like a traditionnal request, but implements features to match "error" cases :
+  # if you have an authentication process which auth user with only one login/password couple,
+  # you can define an ErrorRequest which will always match if parameters do not match your login/password.
+  # ErrorRequest also implements a <tt>match</tt> function which compute a matching value given another request.
   class ErrorRequest < Request
+    # List of non matching parameters
     attr_reader :params_not_equal
     
+    # Initialize an ErrorRequest.
+    # <tt>args</tt> takes all Request options and an additionnal <tt>:params_not_equal</tt> option
+    # to define a hash of parameters that should not match.
     def initialize(args = {})
       super
       @params_not_equal = args[:params_not_equal]
     end
     
+    # Compute a match between <tt>alt</tt> and current instance, returning an integer.
+    # Computation is based on http method, uri and request_headers.
+    # The idea behind this match rate is to find the best ErrorRequest matching a query.
     def match(alt)
       count = 0
 
@@ -15,9 +26,10 @@ module FakeMechanize
       count += 1 if uri     == alt.uri
 
       # More complicated: evaluates if params are equals or if they are different on purpose
-      if !request_headers.empty? and request_headers == alt.request_headers
+      # TODO : handle headers
+      if !parameters.empty? and parameters == alt.parameters
         count += 1
-      elsif method == alt.method and uri == alt.uri and request_headers != params_not_equal
+      elsif method == alt.method and uri == alt.uri and parameters != params_not_equal
         count += 1
       end
 

data/lib/fake_mechanize/request.rb

@@ -2,13 +2,35 @@ module FakeMechanize
   # Request represents a request made to the server with its specific headers and its answer body, headers
   # and status (http code)
   class Request
-    attr_reader :method, :uri, :request_headers, :body, :status, :response_headers
+    # HTTP Method (get, post, ...)
+    attr_reader :method
+    # URI in its full form
+    attr_reader :uri
+    # Headers passed along with the request
+    attr_reader :request_headers
+    # Parameters passed with query (post or get)
+    attr_reader :parameters
+    # Body passed on answer
+    attr_reader :body
+    # HTTP Status code (200, 404, ...)
+    attr_reader :status
+    # Responses headers passed with status and body
+    attr_reader :response_headers
     
+    # Create a new Request with the following options :
+    # * <tt>:method</tt>: http method (verb) to respond to (:get, :post, ...).
+    # * <tt>:uri</tt> or <tt>:url</tt>: string which represents the queried url.
+    # * <tt>:request_headers</tt>: optionnals headers passed while querying.
+    # * <tt>:parameters</tt>: an optionnals hash of parameters, like the one passed in an html form or inlined in a get query.
+    # * <tt>:body</tt>: body that should be returned if query match. Defaut is nil.
+    # * <tt>:status</tt>: http status response code (200, 404, ...). Default is 200.
+    # * <tt>:response_headers</tt>: an optionnal hash for response headers.
     def initialize(args = {})
       # Query
       @method           = args[:method] || :get
-      @uri              = args[:uri]
+      @uri              = args[:url] || args[:uri]
       @request_headers  = args[:request_headers] || {}
+      @parameters       = args[:parameters] || {}
       
       # Answer
       @body             = args[:body]
@@ -20,7 +42,10 @@ module FakeMechanize
     # Returns true if equal, false otherwise.
     # Evaluation is based on method, uri and request_headers.
     def ==(alt)
-      method == alt.method and uri == alt.uri and request_headers == alt.request_headers
+      method == alt.method and
+        uri == alt.uri and
+        request_headers == alt.request_headers and
+        parameters == alt.parameters
     end
   end # Request
 end # FakeMechanize

data/lib/fake_mechanize/responder.rb

@@ -1,9 +1,12 @@
 module FakeMechanize
+  # Responder is a class responsible for creation of responses and errors requests.
   class Responder
     def initialize(responses, errors)
       @responses, @errors = responses, errors
     end
     
+    # Create a new error request. See ErrorRequest for options.
+    # If <tt>:method</tt> is omited, all http verbs can answer.
     def error(args)
       if args[:method]
         @errors << ErrorRequest.new(args)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: fake_mechanize
 version: !ruby/object:Gem::Version 
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors: 
 - Fabien Jakimowicz
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-07-23 00:00:00 +02:00
+date: 2009-10-30 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -38,6 +38,7 @@ files:
 - README.rdoc
 - Rakefile
 - VERSION
+- examples/tiny_url.rb
 - lib/fake_mechanize.rb
 - lib/fake_mechanize/agent.rb
 - lib/fake_mechanize/error_request.rb
@@ -47,6 +48,8 @@ files:
 - test/test_helper.rb
 has_rdoc: true
 homepage: http://github.com/jakimowicz/fake_mechanize
+licenses: []
+
 post_install_message: 
 rdoc_options: 
 - --charset=UTF-8
@@ -67,10 +70,11 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: fake-mechanize
-rubygems_version: 1.3.1
+rubygems_version: 1.3.5
 signing_key: 
-specification_version: 2
+specification_version: 3
 summary: toolset for offline unit tests on mechanize, like httpmock
 test_files: 
 - test/fake_mechanize_test.rb
 - test/test_helper.rb
+- examples/tiny_url.rb