webrat 0.2.0 → 0.3.0

data/lib/webrat/core/methods.rb

@@ -0,0 +1,44 @@
+module Webrat
+  module Methods #:nodoc:
+
+    def self.delegate_to_session(*meths)
+      meths.each do |meth|
+        self.class_eval <<-RUBY
+          def #{meth}(*args, &blk)
+            @session ||= ::Webrat::MerbSession.new
+            @session.#{meth}(*args, &blk)
+          end
+        RUBY
+      end
+    end
+    
+    # all of these methods delegate to the @session, which should
+    # be created transparently.
+    #
+    # Note that when using Webrat, #request also uses @session, so
+    # that #request and webrat native functions behave interchangably
+
+    delegate_to_session \
+      :visits, :visit,
+      :within,
+      :header, :http_accept, :basic_auth,
+      :save_and_open_page,
+      :fill_in,
+      :check, 
+      :uncheck,
+      :choose,
+      :select,
+      :attach_file,
+      :cookies,
+      :response,
+      :current_page,
+      :current_url,
+      :click_link,
+      :click_area,
+      :click_button,
+      :reload, :reloads,
+      :clicks_link_within,
+      :field_labeled
+    
+  end
+end

data/lib/webrat/core/mime.rb

@@ -0,0 +1,29 @@
+module Webrat
+  module MIME
+    
+    def self.mime_type(string_or_symbol)
+      if string_or_symbol.is_a?(String)
+        string_or_symbol
+      else
+        case string_or_symbol
+        when :text              then "text/plain"
+        when :html              then "text/html"
+        when :js                then "text/javascript"
+        when :css               then "text/css"
+        when :ics               then "text/calendar"
+        when :csv               then "text/csv"
+        when :xml               then "application/xml"
+        when :rss               then "application/rss+xml"
+        when :atom              then "application/atom+xml"
+        when :yaml              then "application/x-yaml"
+        when :multipart_form    then "multipart/form-data"
+        when :url_encoded_form  then "application/x-www-form-urlencoded"
+        when :json              then "application/json"
+        else
+          raise ArgumentError.new("Invalid Mime type: #{string_or_symbol.inspect}")
+        end
+      end
+    end
+    
+  end
+end

data/lib/webrat/core/nokogiri.rb

@@ -0,0 +1,42 @@
+require "webrat/core_extensions/meta_class"
+
+module Webrat
+  
+  def self.nokogiri_document(stringlike) #:nodoc:
+    return stringlike.dom if stringlike.respond_to?(:dom)
+    
+    if stringlike === Nokogiri::HTML::Document || stringlike === Nokogiri::XML::NodeSet
+      stringlike
+    elsif stringlike === StringIO
+      Nokogiri::HTML(stringlike.string)
+    elsif stringlike.respond_to?(:body)
+      Nokogiri::HTML(stringlike.body.to_s)
+    else
+      Nokogiri::HTML(stringlike.to_s)
+    end
+  end
+  
+  def self.define_dom_method(object, dom) #:nodoc:
+    object.meta_class.send(:define_method, :dom) do
+      dom
+    end
+  end
+  
+end
+
+
+module Nokogiri
+  module CSS
+    class XPathVisitor
+      
+      def visit_pseudo_class_text(node) #:nodoc:
+        "@type='text'"
+      end
+
+      def visit_pseudo_class_password(node) #:nodoc:
+        "@type='password'"
+      end
+      
+    end
+  end
+end

data/lib/webrat/core/scope.rb

@@ -0,0 +1,208 @@
+require "nokogiri"
+require "webrat/core/form"
+require "webrat/core/locators"
+
+module Webrat
+  class Scope
+    include Logging
+    include Flunk
+    include Locators
+    
+    def self.from_page(session, response, response_body) #:nodoc:
+      new(session) do
+        @response = response
+        @response_body = response_body
+      end
+    end
+    
+    def self.from_scope(session, scope, selector) #:nodoc:
+      new(session) do
+        @scope = scope
+        @selector = selector
+      end
+    end
+    
+    def initialize(session, &block) #:nodoc:
+      @session = session
+      instance_eval(&block) if block_given?
+    end
+    
+    # Verifies an input field or textarea exists on the current page, and stores a value for
+    # it which will be sent when the form is submitted.
+    #
+    # Examples:
+    #   fill_in "Email", :with => "user@example.com"
+    #   fill_in "user[email]", :with => "user@example.com"
+    #
+    # The field value is required, and must be specified in <tt>options[:with]</tt>.
+    # <tt>field</tt> can be either the value of a name attribute (i.e. <tt>user[email]</tt>)
+    # or the text inside a <tt><label></tt> element that points at the <tt><input></tt> field.
+    def fill_in(field_locator, options = {})
+      field = locate_field(field_locator, TextField, TextareaField, PasswordField)
+      field.raise_error_if_disabled
+      field.set(options[:with])
+    end
+
+    alias_method :fills_in, :fill_in
+    
+    # Verifies that an input checkbox exists on the current page and marks it
+    # as checked, so that the value will be submitted with the form.
+    #
+    # Example:
+    #   check 'Remember Me'
+    def check(field_locator)
+      locate_field(field_locator, CheckboxField).check
+    end
+
+    alias_method :checks, :check
+    
+    # Verifies that an input checkbox exists on the current page and marks it
+    # as unchecked, so that the value will not be submitted with the form.
+    #
+    # Example:
+    #   uncheck 'Remember Me'
+    def uncheck(field_locator)
+      locate_field(field_locator, CheckboxField).uncheck
+    end
+
+    alias_method :unchecks, :uncheck
+    
+    # Verifies that an input radio button exists on the current page and marks it
+    # as checked, so that the value will be submitted with the form.
+    #
+    # Example:
+    #   choose 'First Option'
+    def choose(field_locator)
+      locate_field(field_locator, RadioField).choose
+    end
+
+    alias_method :chooses, :choose
+    
+    # Verifies that a an option element exists on the current page with the specified
+    # text. You can optionally restrict the search to a specific select list by
+    # assigning <tt>options[:from]</tt> the value of the select list's name or
+    # a label. Stores the option's value to be sent when the form is submitted.
+    #
+    # Examples:
+    #   selects "January"
+    #   selects "February", :from => "event_month"
+    #   selects "February", :from => "Event Month"
+    def selects(option_text, options = {})
+      find_select_option(option_text, options[:from]).choose
+    end
+
+    alias_method :select, :selects
+    
+    # Verifies that an input file field exists on the current page and sets
+    # its value to the given +file+, so that the file will be uploaded
+    # along with the form. An optional <tt>content_type</tt> may be given.
+    #
+    # Example:
+    #   attaches_file "Resume", "/path/to/the/resume.txt"
+    #   attaches_file "Photo", "/path/to/the/image.png", "image/png"
+    def attach_file(field_locator, path, content_type = nil)
+      locate_field(field_locator, FileField).set(path, content_type)
+    end
+
+    alias_method :attaches_file, :attach_file
+    
+    def click_area(area_name)
+      find_area(area_name).click
+    end
+    
+    alias_method :clicks_area, :click_area
+    
+    # Issues a request for the URL pointed to by a link on the current page,
+    # follows any redirects, and verifies the final page load was successful.
+    # 
+    # click_link has very basic support for detecting Rails-generated 
+    # JavaScript onclick handlers for PUT, POST and DELETE links, as well as
+    # CSRF authenticity tokens if they are present.
+    #
+    # Javascript imitation can be disabled by passing the option :javascript => false
+    #
+    # Passing a :method in the options hash overrides the HTTP method used
+    # for making the link request
+    # 
+    # Example:
+    #   click_link "Sign up"
+    #
+    #   click_link "Sign up", :javascript => false
+    # 
+    #   click_link "Sign up", :method => :put
+    def click_link(link_text, options = {})
+      find_link(link_text).click(options)
+    end
+
+    alias_method :clicks_link, :click_link
+    
+    # Verifies that a submit button exists for the form, then submits the form, follows
+    # any redirects, and verifies the final page was successful.
+    #
+    # Example:
+    #   click_button "Login"
+    #   click_button
+    #
+    # The URL and HTTP method for the form submission are automatically read from the
+    # <tt>action</tt> and <tt>method</tt> attributes of the <tt><form></tt> element.
+    def click_button(value = nil)
+      find_button(value).click
+    end
+
+    alias_method :clicks_button, :click_button
+    
+    def dom # :nodoc:
+      return @dom if @dom
+      
+      if @selector
+        @dom = scoped_dom
+      else
+        @dom = page_dom
+      end
+      
+      return @dom
+    end
+    
+  protected
+  
+    def page_dom #:nodoc:
+      return @response.dom if @response.respond_to?(:dom)
+      dom = Webrat.nokogiri_document(@response_body)
+      Webrat.define_dom_method(@response, dom)
+      return dom
+    end
+    
+    def scoped_dom #:nodoc:
+      Webrat.nokogiri_document(@scope.dom.search(@selector).first.to_html)
+    end
+    
+    def locate_field(field_locator, *field_types) #:nodoc:
+      if field_locator.is_a?(Field)
+        field_locator
+      else
+        field(field_locator, *field_types)
+      end
+    end
+    
+    def areas #:nodoc:
+      dom.search("area").map do |element| 
+        Area.new(@session, element)
+      end
+    end
+    
+    def links #:nodoc:
+      dom.search("a[@href]").map do |link_element|
+        Link.new(@session, link_element)
+      end
+    end
+    
+    def forms #:nodoc:
+      return @forms if @forms
+      
+      @forms = dom.search("form").map do |form_element|
+        Form.new(@session, form_element)
+      end
+    end
+    
+  end
+end

data/lib/webrat/core/select_option.rb

@@ -0,0 +1,29 @@
+module Webrat
+  class SelectOption #:nodoc:
+    
+    def initialize(select, element)
+      @select = select
+      @element = element
+    end
+    
+    def matches_text?(text)
+      if text.is_a?(Regexp)
+        @element.inner_html =~ text
+      else
+        @element.inner_html == text.to_s
+      end
+    end
+    
+    def choose
+      @select.raise_error_if_disabled
+      @select.set(value)
+    end
+    
+  protected
+  
+    def value
+      @element["value"] || @element.inner_html
+    end
+    
+  end
+end

data/lib/webrat/core/session.rb

@@ -0,0 +1,188 @@
+require "forwardable"
+require "ostruct"
+
+require "webrat/core/mime"
+
+module Webrat
+  class Session
+    extend Forwardable
+    include Logging
+    include Flunk
+    
+    attr_reader :current_url
+    
+    def initialize #:nodoc:
+      @http_method     = :get
+      @data            = {}
+      @default_headers = {}
+      @custom_headers  = {}
+    end
+
+    # Saves the page out to RAILS_ROOT/tmp/ and opens it in the default
+    # web browser if on OS X. Useful for debugging.
+    # 
+    # Example:
+    #   save_and_open_page
+    def save_and_open_page
+      return unless File.exist?(saved_page_dir)
+
+      filename = "#{saved_page_dir}/webrat-#{Time.now.to_i}.html"
+      
+      File.open(filename, "w") do |f|
+        f.write rewrite_css_and_image_references(response_body)
+      end
+
+      open_in_browser(filename)
+    end
+    
+    def current_dom #:nodoc:
+      current_scope.dom
+    end
+    
+    # For backwards compatibility -- removing in 1.0
+    def current_page #:nodoc:
+      page = OpenStruct.new
+      page.url = @current_url
+      page.http_method = @http_method
+      page.data = @data
+      page
+    end
+    
+    def doc_root #:nodoc:
+      nil
+    end
+    
+    def saved_page_dir #:nodoc:
+      File.expand_path(".")
+    end
+
+    def header(key, value)
+      @custom_headers[key] = value
+    end
+
+    def http_accept(mime_type)
+      header('Accept', Webrat::MIME.mime_type(mime_type))
+    end
+    
+    def basic_auth(user, pass)
+      encoded_login = ["#{user}:#{pass}"].pack("m*")
+      header('HTTP_AUTHORIZATION', "Basic #{encoded_login}")
+    end
+
+    def headers #:nodoc:
+      @default_headers.dup.merge(@custom_headers.dup)
+    end
+
+    def request_page(url, http_method, data) #:nodoc:
+      h = headers
+      h['HTTP_REFERER'] = @current_url if @current_url
+
+      debug_log "REQUESTING PAGE: #{http_method.to_s.upcase} #{url} with #{data.inspect} and HTTP headers #{h.inspect}"
+      if h.empty?
+        send "#{http_method}", url, data || {}
+      else
+        send "#{http_method}", url, data || {}, h
+      end
+
+      save_and_open_page if exception_caught?
+      flunk("Page load was not successful (Code: #{response_code.inspect}):\n#{formatted_error}") unless success_code?
+      
+      @_scopes      = nil
+      @_page_scope  = nil
+      @current_url  = url
+      @http_method  = http_method
+      @data         = data
+      
+      return response
+    end
+    
+    def success_code? #:nodoc:
+      (200..499).include?(response_code)
+    end
+    
+    def exception_caught? #:nodoc:
+      response_body =~ /Exception caught/
+    end
+    
+    def current_scope #:nodoc:
+      scopes.last || page_scope
+    end
+    
+    # Reloads the last page requested. Note that this will resubmit forms
+    # and their data.
+    #
+    # Example:
+    #   reloads
+    def reloads
+      request_page(@current_url, @http_method, @data)
+    end
+
+    alias_method :reload, :reloads
+      
+    
+    # Works like click_link, but only looks for the link text within a given selector
+    # 
+    # Example:
+    #   click_link_within "#user_12", "Vote"
+    def click_link_within(selector, link_text)
+      within(selector) do
+        click_link(link_text)
+      end
+    end
+
+    alias_method :clicks_link_within, :click_link_within
+    
+    def within(selector)
+      scopes.push(Scope.from_scope(self, current_scope, selector))
+      ret = yield(current_scope)
+      scopes.pop
+      return ret
+    end
+    
+    # Issues a GET request for a page, follows any redirects, and verifies the final page
+    # load was successful.
+    #
+    # Example:
+    #   visit "/"
+    def visit(url = nil, http_method = :get, data = {})
+      request_page(url, http_method, data)
+    end
+    
+    alias_method :visits, :visit
+    
+    def open_in_browser(path) #:nodoc
+      `open #{path}`
+    end
+    
+    def rewrite_css_and_image_references(response_html) #:nodoc
+      return response_html unless doc_root
+      response_html.gsub(/"\/(stylesheets|images)/, doc_root + '/\1')
+    end
+
+    # Subclasses can override this to show error messages without html
+    def formatted_error #:nodoc:
+      response_body
+    end
+
+    def scopes #:nodoc:
+      @_scopes ||= []
+    end
+
+    def page_scope #:nodoc:
+      @_page_scope ||= Scope.from_page(self, response, response_body)
+    end
+    
+    def_delegators :current_scope, :fill_in,            :fills_in
+    def_delegators :current_scope, :check,              :checks
+    def_delegators :current_scope, :uncheck,            :unchecks
+    def_delegators :current_scope, :choose,             :chooses
+    def_delegators :current_scope, :select,             :selects
+    def_delegators :current_scope, :attach_file,        :attaches_file
+    def_delegators :current_scope, :click_area,         :clicks_area
+    def_delegators :current_scope, :click_link,         :clicks_link
+    def_delegators :current_scope, :click_button,       :clicks_button
+    def_delegators :current_scope, :should_see
+    def_delegators :current_scope, :should_not_see
+    def_delegators :current_scope, :field_labeled
+  end
+end