akephalos2 2.0.0

data/lib/akephalos/client.rb

@@ -0,0 +1,192 @@
+require 'akephalos/configuration'
+
+if RUBY_PLATFORM != "java"
+  require 'akephalos/remote_client'
+  Akephalos::Client = Akephalos::RemoteClient
+else
+  require 'akephalos/htmlunit'
+  require 'akephalos/htmlunit/ext/http_method'
+  require 'akephalos/htmlunit/ext/confirm_handler'
+
+  require 'akephalos/page'
+  require 'akephalos/node'
+
+  require 'akephalos/client/cookies'
+  require 'akephalos/client/filter'
+
+  module Akephalos
+
+    # Akephalos::Client wraps HtmlUnit's WebClient class. It is the main entry
+    # point for all interaction with the browser, exposing its current page and
+    # allowing navigation.
+    class Client
+
+      # @return [Akephalos::Page] the current page
+      attr_reader :page
+
+      # @return [HtmlUnit::BrowserVersion] the configured browser version
+      attr_reader :browser_version
+
+      # @return [true/false] whether to raise errors on javascript failures
+      attr_reader :validate_scripts
+
+      # @return [true/false] whether to ignore insecure ssl certificates
+      attr_reader :use_insecure_ssl
+
+      # @return ["trace" / "debug" / "info" / "warn" / "error" or "fatal"] which points the htmlunit log level
+      attr_reader :htmlunit_log_level
+
+      # The default configuration options for a new Client.
+      DEFAULT_OPTIONS = {
+        :browser => :firefox_3_6,
+        :validate_scripts => true,
+        :use_insecure_ssl => false,
+        :htmlunit_log_level => 'fatal'
+      }
+
+      # Map of browser version symbols to their HtmlUnit::BrowserVersion
+      # instances.
+      BROWSER_VERSIONS = {
+        :ie6         => HtmlUnit::BrowserVersion::INTERNET_EXPLORER_6,
+        :ie7         => HtmlUnit::BrowserVersion::INTERNET_EXPLORER_7,
+        :ie8         => HtmlUnit::BrowserVersion::INTERNET_EXPLORER_8,
+        :firefox_3   => HtmlUnit::BrowserVersion::FIREFOX_3,
+        :firefox_3_6 => HtmlUnit::BrowserVersion::FIREFOX_3_6
+      }
+
+      # @param [Hash] options the configuration options for this client
+      #
+      # @option options [Symbol] :browser (:firefox_3_6) the browser version (
+      #   see BROWSER_VERSIONS)
+      #
+      # @option options [true, false] :validate_scripts (true) whether to raise
+      #   errors on javascript errors
+      def initialize(options = {})
+        process_options!(options)
+
+        @_client = java.util.concurrent.FutureTask.new do
+
+          if @http_proxy.nil? or @http_proxy_port.nil?
+            client = HtmlUnit::WebClient.new(browser_version)
+          else
+            client = HtmlUnit::WebClient.new(browser_version, @http_proxy, @http_proxy_port)
+          end
+
+          client.setThrowExceptionOnFailingStatusCode(false)
+          client.setAjaxController(HtmlUnit::NicelyResynchronizingAjaxController.new)
+          client.setCssErrorHandler(HtmlUnit::SilentCssErrorHandler.new)
+          client.setThrowExceptionOnScriptError(validate_scripts)
+          client.setUseInsecureSSL(use_insecure_ssl)
+
+          Filter.new(client)
+          client
+        end
+        Thread.new { @_client.run }
+      end
+
+      # Visit the requested URL and return the page.
+      #
+      # @param [String] url the URL to load
+      # @return [Page] the loaded page
+      def visit(url)
+        begin
+          client.getPage(url)
+        rescue Exception => e
+          raise e unless e.message == 'java.lang.NullPointerException: null'
+        end
+        page
+      end
+
+      # @return [Cookies] the cookies for this session
+      def cookies
+        @cookies ||= Cookies.new(client.getCookieManager)
+      end
+
+      # @return [String] the current user agent string
+      def user_agent
+        @user_agent || client.getBrowserVersion.getUserAgent
+      end
+
+      # Set the User-Agent header for this session. If :default is given, the
+      # User-Agent header will be reset to the default browser's user agent.
+      #
+      # @param [:default] user_agent the default user agent
+      # @param [String] user_agent the user agent string to use
+      def user_agent=(user_agent)
+        if user_agent == :default
+          @user_agent = nil
+          client.removeRequestHeader("User-Agent")
+        else
+          @user_agent = user_agent
+          client.addRequestHeader("User-Agent", user_agent)
+        end
+      end
+
+      # @return [Page] the current page
+      def page
+        self.page = client.getCurrentWindow.getTopWindow.getEnclosedPage
+        @page
+      end
+
+      # Update the current page.
+      #
+      # @param [HtmlUnit::HtmlPage] _page the new page
+      # @return [Page] the new page
+      def page=(_page)
+        if @page != _page
+          @page = Page.new(_page)
+        end
+        @page
+      end
+
+      # @return [true, false] whether javascript errors will raise exceptions
+      def validate_scripts?
+        !!validate_scripts
+      end
+
+      # @return [true, false] whether to ignore insecure ssl certificates
+      def use_insecure_ssl?
+        !!use_insecure_ssl
+      end
+
+      # Merges the DEFAULT_OPTIONS with those provided to initialize the Client
+      # state, namely, its browser version, whether it should
+      # validate scripts, and htmlunit log level.
+      #
+      # @param [Hash] options the options to process
+      def process_options!(options)
+        options = DEFAULT_OPTIONS.merge(options)
+
+        @browser_version  = BROWSER_VERSIONS.fetch(options.delete(:browser))
+        @validate_scripts = options.delete(:validate_scripts)
+        @use_insecure_ssl = options.delete(:use_insecure_ssl)
+        @htmlunit_log_level = options.delete(:htmlunit_log_level)
+        @http_proxy = options.delete(:http_proxy)
+        @http_proxy_port = options.delete(:http_proxy_port)
+
+        java.lang.System.setProperty("org.apache.commons.logging.simplelog.defaultlog", @htmlunit_log_level)
+      end
+
+      # Confirm or cancel the dialog, returning the text of the dialog
+      def confirm_dialog(confirm = true, &block)
+        handler = HtmlUnit::ConfirmHandler.new
+        handler.handleConfirmValue = confirm
+        client.setConfirmHandler(handler)
+        yield if block_given?
+        return handler.text
+      end
+
+      private
+
+      # Call the future set up in #initialize and return the WebCLient
+      # instance.
+      #
+      # @return [HtmlUnit::WebClient] the WebClient instance
+      def client
+        @client ||= @_client.get.tap do |client|
+          client.getCurrentWindow.getHistory.ignoreNewPages_.set(true)
+        end
+      end
+    end
+  end
+end

data/lib/akephalos/configuration.rb

@@ -0,0 +1,49 @@
+module Akephalos
+
+  @configuration = {}
+
+  class << self
+    # @return [Hash] the configuration
+    attr_accessor :configuration
+  end
+
+  module Filters
+    # @return [Array] all defined filters
+    def filters
+      configuration[:filters] ||= []
+    end
+
+    # Defines a new filter to be tested by Akephalos::Filter when executing
+    # page requests. An HTTP method and a regex or string to match against the
+    # URL are required for defining a filter.
+    #
+    # You can additionally pass the following options to define how the
+    # filtered request should respond:
+    #
+    #   :status       (defaults to 200)
+    #   :body         (defaults to "")
+    #   :headers      (defaults to {})
+    #
+    # If we define a filter with no additional options, then, we will get an
+    # empty HTML response:
+    #
+    #   Akephalos.filter :post, "http://example.com"
+    #   Akephalos.filter :any, %r{http://.*\.com}
+    #
+    # If you instead, say, wanted to simulate a failure in an external system,
+    # you could do this:
+    #
+    #   Akephalos.filter :post, "http://example.com",
+    #     :status => 500, :body => "Something went wrong"
+    #
+    # @param [Symbol] method the HTTP method to match
+    # @param [RegExp, String] regex URL matcher
+    # @param [Hash] options response values
+    def filter(method, regex, options = {})
+      regex = Regexp.new(Regexp.escape(regex)) if regex.is_a?(String)
+      filters << {:method => method, :filter => regex, :status => 200, :body => "", :headers => {}}.merge!(options)
+    end
+  end
+
+  extend Filters
+end

data/lib/akephalos/console.rb

@@ -0,0 +1,32 @@
+# Begin a new Capybara session, by default connecting to localhost on port
+# 3000.
+def session
+  Capybara.app_host ||= "http://localhost:3000"
+  @session ||= Capybara::Session.new(:akephalos)
+end
+alias page session
+
+module Akephalos
+  # Simple class for starting an IRB session.
+  class Console
+
+    # Start an IRB session. Tries to load irb/completion, and also loads a
+    # .irbrc file if it exists.
+    def self.start
+      require 'irb'
+
+      begin
+        require 'irb/completion'
+      rescue Exception
+        # No readline available, proceed anyway.
+      end
+
+      if ::File.exists? ".irbrc"
+        ENV['IRBRC'] = ".irbrc"
+      end
+
+      IRB.start
+    end
+
+  end
+end

data/lib/akephalos/cucumber.rb

@@ -0,0 +1,6 @@
+require 'capybara/cucumber'
+
+Before('@akephalos') do
+  Capybara.current_driver = :akephalos
+end
+

data/lib/akephalos/htmlunit/ext/confirm_handler.rb

@@ -0,0 +1,18 @@
+# Reopen com.gargoylesoftware.htmlunit.ConfirmHandler to provide an interface to
+# confirm a dialog and capture its message
+module HtmlUnit
+  module ConfirmHandler
+
+    # Boolean - true for ok, false for cancel
+    attr_accessor :handleConfirmValue
+
+    # last confirmation's message
+    attr_reader   :text
+
+    # handleConfirm will be called by htmlunit on a confirm, so store the message.
+    def handleConfirm(page, message)
+      @text = message
+      return handleConfirmValue.nil? ? true : handleConfirmValue
+    end
+  end
+end

data/lib/akephalos/htmlunit/ext/http_method.rb

@@ -0,0 +1,30 @@
+module HtmlUnit
+  # Reopen HtmlUnit's HttpMethod class to add convenience methods.
+  class HttpMethod
+
+    # Loosely compare HttpMethod with another object, accepting either an
+    # HttpMethod instance or a symbol describing the method. Note that :any is a
+    # special symbol which will always return true.
+    #
+    # @param [HttpMethod] other an HtmlUnit HttpMethod object
+    # @param [Symbol] other a symbolized representation of an http method
+    # @return [true/false]
+    def ===(other)
+      case other
+      when HttpMethod
+        super
+      when :any
+        true
+      when :get
+        self == self.class::GET
+      when :post
+        self == self.class::POST
+      when :put
+        self == self.class::PUT
+      when :delete
+        self == self.class::DELETE
+      end
+    end
+
+  end
+end

data/lib/akephalos/htmlunit.rb

@@ -0,0 +1,36 @@
+require "pathname"
+require "java"
+
+dependency_directory = $:.detect { |path| Dir[File.join(path, 'html-unit/htmlunit-*.jar')].any? }
+
+raise "Could not find htmlunit/htmlunit-VERSION.jar in load path:\n  [ #{$:.join(",\n    ")}\n  ]" unless dependency_directory
+
+Dir[File.join(dependency_directory, "html-unit/*.jar")].each do |jar|
+  require jar
+end
+
+java.lang.System.setProperty("org.apache.commons.logging.Log", "org.apache.commons.logging.impl.SimpleLog")
+java.lang.System.setProperty("org.apache.commons.logging.simplelog.defaultlog", "fatal")
+java.lang.System.setProperty("org.apache.commons.logging.simplelog.showdatetime", "true")
+
+# Container module for com.gargoylesoftware.htmlunit namespace.
+module HtmlUnit
+  java_import "com.gargoylesoftware.htmlunit.BrowserVersion"
+  java_import "com.gargoylesoftware.htmlunit.History"
+  java_import "com.gargoylesoftware.htmlunit.HttpMethod"
+  java_import 'com.gargoylesoftware.htmlunit.ConfirmHandler'
+  java_import "com.gargoylesoftware.htmlunit.NicelyResynchronizingAjaxController"
+  java_import "com.gargoylesoftware.htmlunit.SilentCssErrorHandler"
+  java_import "com.gargoylesoftware.htmlunit.WebClient"
+  java_import "com.gargoylesoftware.htmlunit.WebResponseData"
+  java_import "com.gargoylesoftware.htmlunit.WebResponseImpl"
+
+  # Container module for com.gargoylesoftware.htmlunit.util namespace.
+  module Util
+    java_import "com.gargoylesoftware.htmlunit.util.NameValuePair"
+    java_import "com.gargoylesoftware.htmlunit.util.WebConnectionWrapper"
+  end
+
+  # Disable history tracking
+  History.field_reader :ignoreNewPages_
+end

data/lib/akephalos/node.rb

@@ -0,0 +1,192 @@
+module Akephalos
+
+  # Akephalos::Node wraps HtmlUnit's DOMNode class, providing a simple API for
+  # interacting with an element on the page.
+  class Node
+    # @param [HtmlUnit::DOMNode] node
+    def initialize(node)
+      @nodes = []
+      @_node = node
+    end
+
+    # @return [true, false] whether the element is checked
+    def checked?
+      if @_node.respond_to?(:isChecked)
+        @_node.isChecked
+      else
+        !! self[:checked]
+      end
+    end
+
+    # @return [String] inner text of the node
+    # Returns a textual representation of this element that represents what would
+    # be visible to the user if this page was shown in a web browser.
+    # For example, a single-selection select element would return the currently
+    # selected value as text.
+    # Note: This will cleanup/reduce whitespace
+     def text
+       @_node.asText
+     end
+
+    # Returns the raw text content of this node and its descendants...
+    def text_content
+      @_node.getTextContent
+    end
+
+    # Returns a string representation of the XML document from this element and
+    # all it's children (recursively). The charset used is the current page encoding.
+    def xml
+      @_node.asXml
+    end
+
+    # Return the value of the node's attribute.
+    #
+    # @param [String] name attribute on node
+    # @return [String] the value of the named attribute
+    # @return [nil] when the node does not have the named attribute
+    def [](name)
+      @_node.hasAttribute(name.to_s) ? @_node.getAttribute(name.to_s) : nil
+    end
+
+    # Return the value of a form element. If the element is a select box and
+    # has "multiple" declared as an attribute, then all selected options will
+    # be returned as an array.
+    #
+    # @return [String, Array<String>] the node's value
+    def value
+      case tag_name
+      when "select"
+        if self[:multiple]
+          selected_options.map { |option| option.value }
+        else
+          selected_option = @_node.selected_options.first
+          selected_option ? Node.new(selected_option).value : nil
+        end
+      when "option"
+        self[:value] || text
+      when "textarea"
+        @_node.getText
+      else
+        self[:value]
+      end
+    end
+
+    # Set the value of the form input.
+    #
+    # @param [String] value
+    def value=(value)
+      case tag_name
+      when "textarea"
+        @_node.setText("")
+        type(value)
+      when "input"
+        if file_input?
+          @_node.setValueAttribute(value)
+        else
+          @_node.setValueAttribute("")
+          type(value)
+        end
+      end
+    end
+
+    # Types each character into a text or input field.
+    #
+    # @param [String] value the string to type
+    def type(value)
+      value.each_char do |c|
+        @_node.type(c)
+      end
+    end
+
+    # @return [true, false] whether the node allows multiple-option selection (if the node is a select).
+    def multiple_select?
+      !self[:multiple].nil?
+    end
+
+    # @return [true, false] whether the node is a file input
+    def file_input?
+      tag_name == "input" && @_node.getAttribute("type") == "file"
+    end
+
+
+    # Unselect an option.
+    #
+    # @return [true, false] whether the unselection was successful
+    def unselect
+      @_node.setSelected(false)
+    end
+
+    # Return the option elements for a select box.
+    #
+    # @return [Array<Node>] the options
+    def options
+      @_node.getOptions.map { |node| Node.new(node) }
+    end
+
+    # Return the selected option elements for a select box.
+    #
+    # @return [Array<Node>] the selected options
+    def selected_options
+      @_node.getSelectedOptions.map { |node| Node.new(node) }
+    end
+
+    # Fire a JavaScript event on the current node. Note that you should not
+    # prefix event names with "on", so:
+    #
+    #   link.fire_event('mousedown')
+    #
+    # @param [String] JavaScript event name
+    def fire_event(name)
+      @_node.fireEvent(name)
+    end
+
+    # @return [String] the node's tag name
+    def tag_name
+      @_node.getNodeName
+    end
+
+    # @return [true, false] whether the node is visible to the user accounting
+    # for CSS.
+    def visible?
+      @_node.isDisplayed
+    end
+
+    # @return [true, false] whether the node is selected to the user accounting
+    # for CSS.
+    def selected?
+      if @_node.respond_to?(:isSelected)
+        @_node.isSelected
+      else
+        !! self[:selected]
+      end
+    end
+
+    # Click the node and then wait for any triggered JavaScript callbacks to
+    # fire.
+    def click
+      begin
+        @_node.click
+        @_node.getPage.getEnclosingWindow.getJobManager.waitForJobs(1000)
+        @_node.getPage.getEnclosingWindow.getJobManager.waitForJobsStartingBefore(1000)
+      rescue Exception => e
+        raise e unless e.message == 'java.lang.NullPointerException: null'
+      end
+    end
+
+    # Search for child nodes which match the given XPath selector.
+    #
+    # @param [String] selector an XPath selector
+    # @return [Array<Node>] the matched nodes
+    def find(selector)
+      nodes = @_node.getByXPath(selector).map { |node| Node.new(node) }
+      @nodes << nodes
+      nodes
+    end
+
+    # @return [String] the XPath expression for this node
+    def xpath
+      @_node.getCanonicalXPath
+    end
+  end
+
+end

data/lib/akephalos/page.rb

@@ -0,0 +1,113 @@
+module Akephalos
+
+  # Akephalos::Page wraps HtmlUnit's HtmlPage class, exposing an API for
+  # interacting with a page in the browser.
+  class Page
+    # @param [HtmlUnit::HtmlPage] page
+    def initialize(page)
+      @nodes = []
+      @_page = page
+    end
+
+    # Search for nodes which match the given XPath selector.
+    #
+    # @param [String] selector an XPath selector
+    # @return [Array<Node>] the matched nodes
+    def find(selector)
+      nodes = current_frame.getByXPath(selector).map { |node| Node.new(node) }
+      @nodes << nodes
+      nodes
+    end
+
+    # Return the page's source, including any JavaScript-triggered DOM changes.
+    #
+    # @return [String] the page's modified source
+    def modified_source
+      current_frame.asXml
+    end
+
+    # Return the page's source as returned by the web server.
+    #
+    # @return [String] the page's original source
+    def source
+      current_frame.getWebResponse.getContentAsString
+    end
+
+    # @return [Hash{String => String}] the page's response headers
+    def response_headers
+      headers = current_frame.getWebResponse.getResponseHeaders.map do |header|
+        [header.getName, header.getValue]
+      end
+      Hash[*headers.flatten]
+    end
+
+    # @return [Integer] the response's status code
+    def status_code
+      current_frame.getWebResponse.getStatusCode
+    end
+
+    # Execute the given block in the context of the frame specified.
+    #
+    # @param [String] frame_id the frame's id
+    # @return [true] if the frame is found
+    # @return [nil] if the frame is not found
+    def within_frame(frame_id)
+      return unless @current_frame = find_frame(frame_id)
+      yield
+      true
+    ensure
+      @current_frame = nil
+    end
+
+    # @return [String] the current page's URL.
+    def current_url
+      current_frame.getWebResponse.getRequestSettings.getUrl.toString
+    end
+
+    # Execute JavaScript against the current page, discarding any return value.
+    #
+    # @param [String] script the JavaScript to be executed
+    # @return [nil]
+    def execute_script(script)
+      current_frame.executeJavaScript(script)
+      nil
+    end
+
+    # Execute JavaScript against the current page and return the results.
+    #
+    # @param [String] script the JavaScript to be executed
+    # @return the result of the JavaScript
+    def evaluate_script(script)
+      current_frame.executeJavaScript(script).getJavaScriptResult
+    end
+
+    # Compare this page with an HtmlUnit page.
+    #
+    # @param [HtmlUnit::HtmlPage] other an HtmlUnit page
+    # @return [true, false]
+    def ==(other)
+      @_page == other
+    end
+
+    private
+
+    # Return the current frame. Usually just @_page, except when inside of the
+    # within_frame block.
+    #
+    # @return [HtmlUnit::HtmlPage] the current frame
+    def current_frame
+      @current_frame || @_page
+    end
+
+    # @param [String] id the frame's id
+    # @return [HtmlUnit::HtmlPage] the specified frame
+    # @return [nil] if no frame is found
+    def find_frame(id)
+      frame = @_page.getFrames.find do |frame|
+        frame.getFrameElement.getAttribute("id") == id
+      end
+      frame.getEnclosedPage if frame
+    end
+  end
+
+end