yellowlab-akephalos 0.2.6

data/MIT_LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Bernerd Schaefer
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,109 @@
+# Akephalos
+Akephalos is a full-stack headless browser for integration testing with
+Capybara. It is built on top of [HtmlUnit](http://htmlunit.sourceforge.net),
+a GUI-less browser for the Java platform, but can be run on both JRuby and
+MRI with no need for JRuby to be installed on the system.
+
+## Installation
+
+    gem install akephalos
+
+## Setup
+
+Configuring akephalos is as simple as requiring it and setting Capybara's
+javascript driver:
+
+    require 'akephalos'
+    Capybara.javascript_driver = :akephalos
+
+## Basic Usage
+
+Akephalos provides a driver for Capybara, so using Akephalos is no
+different than using Selenium or Rack::Test. For a full usage guide, check
+out Capybara's DSL [documentation](http://github.com/jnicklas/capybara). It
+makes no assumptions about the testing framework being used, and works with
+RSpec, Cucumber, and Test::Unit.
+
+Here's some sample RSpec code:
+
+    describe "Home Page" do
+      before { visit "/" }
+      context "searching" do
+        before do
+          fill_in "Search", :with => "akephalos"
+          click_button "Go"
+        end
+        it "returns results" { page.should have_css("#results") }
+        it "includes the search term" { page.should have_content("akephalos") }
+      end
+    end
+
+## Configuration
+
+There are now a few configuration options available through Capybara's new
+`register_driver` API.
+
+### Using a different browser
+
+HtmlUnit supports a few browser implementations, and you can choose which
+browser you would like to use through Akephalos. By default, Akephalos uses
+Firefox 3.6.
+
+    Capybara.register_driver :akephalos do |app|
+      # available options:
+      #   :ie6, :ie7, :ie8, :firefox_3, :firefox_3_6
+      Capybara::Driver::Akephalos.new(app, :browser => :ie8)
+    end
+
+### Ignoring javascript errors
+
+By default HtmlUnit (and Akephalos) will raise an exception when an error
+is encountered in javascript files. This is generally desireable, except
+that certain libraries aren't supported by HtmlUnit. If possible, it's
+best to keep the default behavior, and use Filters (see below) to mock
+offending libraries. If needed, however, you can configure Akephalos to
+ignore javascript errors.
+
+    Capybara.register_driver :akephalos do |app|
+      Capybara::Driver::Akephalos.new(app, :validate_scripts => false)
+    end   
+
+### Setting the HtmlUnit log level
+
+By default it uses the 'fatal' level. You can change that like this:
+
+	Capybara.register_driver :akephalos do |app|  
+		# available options 
+		# "trace", "debug", "info", "warn", "error", or "fatal"
+		Capybara::Driver::Akephalos.new(app, :htmlunit_log_level => 'fatal')
+	end
+
+### Running Akephalos with Spork
+
+    Spork.prefork do
+      ...
+      Akephalos::RemoteClient.manager                                 
+    end
+
+    Spork.each_run do
+      Thread.current['DRb'] = { 'server' => DRb::DRbServer.new }
+    end
+
+More info at : [sporking-with-akephalos](http://spacevatican.org/2011/7/3/sporking-with-akephalos)
+
+## More
+
+* [bin/akephalos](http://bernerdschaefer.github.com/akephalos/akephalos-bin.html)
+  allows you to start an interactive shell or DRb server, as well as perform
+  other maintenance features.
+
+* [Filters](http://bernerdschaefer.github.com/akephalos/filters.html) allows
+  you to declare mock responses for external resources and services requested
+  by the browser.
+
+## Resources
+
+* [API Documentation](http://bernerdschaefer.github.com/akephalos/api)
+* [Source code](http://github.com/bernerdschaefer/akephalos) and
+  [issues](http://github.com/bernerdschaefer/akephalos/issues) are hosted on
+  github.

data/bin/akephalos

@@ -0,0 +1,88 @@
+#!/usr/bin/env ruby
+# vim:set filetype=ruby:
+
+require "pathname"
+require "optparse"
+
+options = { :interactive => false }
+
+parser = OptionParser.new do |opts|
+  opts.banner = "Usage: akephalos [--interactive, --use-htmlunit-snapshot] | [--server] <port>"
+  opts.on("-s", "--server", "Run in server mode (default)")
+  opts.on("-i", "--interactive", "Run in interactive mode") { options[:interactive] = true }
+  opts.on("--use-htmlunit-snapshot", "Use the snapshot of htmlunit") { options[:use_htmlunit_snapshot] = true }
+
+  opts.on_tail("-h", "--help", "Show this message") { puts opts; exit }
+end
+parser.parse!
+
+root = Pathname(__FILE__).expand_path.dirname.parent
+lib = root + 'lib'
+src = root + 'src'
+
+case
+when options[:use_htmlunit_snapshot]
+  require "fileutils"
+
+  FileUtils.mkdir_p("vendor/htmlunit")
+  Dir["vendor/htmlunit/*.jar"].each { |jar| File.unlink(jar) }
+
+  Dir.chdir("vendor") do
+    $stdout.print "Downloading latest snapshot... "
+    $stdout.flush
+    %x[curl -O http://build.canoo.com/htmlunit/artifacts/htmlunit-2.9-SNAPSHOT-with-dependencies.zip &> /dev/null]
+    puts "done"
+
+    $stdout.print "Extracting dependencies... "
+    $stdout.flush
+    %x[unzip -j -d htmlunit htmlunit-2.9-SNAPSHOT-with-dependencies.zip htmlunit-2.9-SNAPSHOT/lib htmlunit-2.9-SNAPSHOT/lib/* &> /dev/null]
+    puts "done"
+
+    File.unlink "htmlunit-2.9-SNAPSHOT-with-dependencies.zip"
+  end
+
+  $stdout.puts "="*40
+  $stdout.puts "The latest HtmlUnit snapshot has been extracted to vendor/htmlunit!"
+when options[:interactive]
+  $:.unshift('vendor', lib, src)
+  require 'rubygems'
+  require 'akephalos'
+  require 'akephalos/console'
+  Akephalos::Console.start
+else
+  unless port = ARGV[0]
+    puts parser.help
+    exit
+  end
+
+  if RUBY_PLATFORM == "java"
+    $:.unshift("vendor", lib, src)
+    require 'akephalos/server'
+    Akephalos::Server.start!(port)
+  else
+    require 'rubygems'
+    require 'jruby-jars'
+
+    jruby = JRubyJars.core_jar_path
+    jruby_stdlib = JRubyJars.stdlib_jar_path
+
+    java_args = [
+      "-Xmx512M",
+      "-cp", [JRubyJars.core_jar_path, JRubyJars.stdlib_jar_path].join(File::PATH_SEPARATOR),
+      "org.jruby.Main"
+    ]
+    ruby_args = [ 
+      "-Ku",
+      "-I", ["vendor", lib, src].join(File::PATH_SEPARATOR),
+      "-r", "akephalos/server",
+      "-e", "Akephalos::Server.start!(#{port.inspect})"
+    ]
+
+    # Bundler sets ENV["RUBYOPT"] to automatically load bundler/setup.rb, but
+    # since the akephalos server doesn't have any gem dependencies and is
+    # always executed with the same context, we clear RUBYOPT before running
+    # exec.
+    ENV["RUBYOPT"] = ""
+    exec("java", *(java_args + ruby_args))
+  end
+end

data/lib/akephalos.rb

@@ -0,0 +1,19 @@
+# **Akephalos** is a cross-platform Ruby interface for *HtmlUnit*, a headless
+# browser for the Java platform.
+#
+# The only requirement is that a Java runtime is available.
+#
+require 'java' if RUBY_PLATFORM == 'java'
+require 'pathname'
+
+module Akephalos
+  BIN_DIR = Pathname(__FILE__).expand_path.dirname.parent + 'bin'
+end
+
+require 'akephalos/client'
+require 'capybara'
+require 'akephalos/capybara'
+
+Capybara.register_driver :akephalos do |app|
+  Capybara::Driver::Akephalos.new(app)
+end

data/lib/akephalos/capybara.rb

@@ -0,0 +1,343 @@
+# Driver class exposed to Capybara. It implements Capybara's full driver API,
+# and is the entry point for interaction between the test suites and HtmlUnit.
+#
+# This class and +Capybara::Driver::Akephalos::Node+ are written to run on both
+# MRI and JRuby, and is agnostic whether the Akephalos::Client instance is used
+# directly or over DRb.
+class Capybara::Driver::Akephalos < Capybara::Driver::Base
+
+  # Akephalos-specific implementation for Capybara's Driver::Node class.
+  class Node < Capybara::Driver::Node
+
+    # @api capybara
+    # @return [String] the inner text of the node
+    def text
+      native.text
+    end
+
+    # @api capybara
+    # @param [String] name attribute name
+    # @return [String] the attribute value
+    def [](name)
+      name = name.to_s
+      case name
+      when 'checked'
+        native.checked?
+      else
+        native[name.to_s]
+      end
+    end
+
+    # @api capybara
+    # @return [String, Array<String>] the form element's value
+    def value
+      native.value
+    end
+
+    # Set the form element's value.
+    #
+    # @api capybara
+    # @param [String] value the form element's new value
+    def set(value)
+      if tag_name == 'textarea'
+        native.value = value.to_s
+      elsif tag_name == 'input' and type == 'radio'
+        click
+      elsif tag_name == 'input' and type == 'checkbox'
+        if value != self['checked']
+          click
+        end
+      elsif tag_name == 'input'
+        native.value = value.to_s
+      end
+    end
+
+    # @api capybara
+    def select_option
+      native.click
+    end
+
+    # Unselect an option from a select box.
+    #
+    # @api capybara
+    def unselect_option
+      unless select_node.multiple_select?
+        raise Capybara::UnselectNotAllowed, "Cannot unselect option from single select box."
+      end
+
+      native.unselect
+    end
+
+    # Click the element.
+    def click
+      native.click
+    end
+
+    # Drag the element on top of the target element.
+    #
+    # @api capybara
+    # @param [Node] element the target element
+    def drag_to(element)
+      trigger('mousedown')
+      element.trigger('mousemove')
+      element.trigger('mouseup')
+    end
+
+    # @api capybara
+    # @return [String] the element's tag name
+    def tag_name
+      native.tag_name
+    end
+
+    # @api capybara
+    # @return [true, false] the element's visiblity
+    def visible?
+      native.visible?
+    end
+
+    # @api capybara
+    # @return [true, false] the element's visiblity
+    def checked?
+      native.checked?
+    end
+
+    # @api capybara
+    # @return [true, false] the element's visiblity
+    def selected?
+      native.selected?
+    end
+
+    # @api capybara
+    # @return [String] the XPath to locate the node
+    def path
+      native.xpath
+    end
+
+    # Trigger an event on the element.
+    #
+    # @api capybara
+    # @param [String] event the event to trigger
+    def trigger(event)
+      native.fire_event(event.to_s)
+    end
+
+    # @api capybara
+    # @param [String] selector XPath query
+    # @return [Array<Node>] the matched nodes
+    def find(selector)
+      nodes = []
+      native.find(selector).each { |node| nodes << self.class.new(self, node) }
+      nodes
+    end
+
+    protected
+
+    # @return [true, false] whether the node allows multiple-option selection (if the node is a select).
+    def multiple_select?
+      tag_name == "select" && native.multiple_select?
+    end
+
+    private
+
+    # Return all child nodes which match the selector criteria.
+    #
+    # @api capybara
+    # @return [Array<Node>] the matched nodes
+    def all_unfiltered(selector)
+      nodes = []
+      native.find(selector).each { |node| nodes << self.class.new(driver, node) }
+      nodes
+    end
+
+    # @return [String] the node's type attribute
+    def type
+      native[:type]
+    end
+
+    # @return [Node] the select node, if this is an option node
+    def select_node
+      find('./ancestor::select').first
+    end
+  end
+
+  attr_reader :app, :rack_server, :options
+
+  # Creates a new instance of the Akephalos Driver for Capybara. The driver is
+  # registered with Capybara by a name, so that it can be chosen when
+  # Capybara's javascript_driver is changed. By default, Akephalos is
+  # registered like this:
+  #
+  #   Capybara.register_driver :akephalos do |app|
+  #     Capybara::Akephalos::Driver.new(
+  #       app,
+  #       :browser => :firefox_3_6,
+  #       :validate_scripts => true
+  #     )
+  #   end
+  #
+  # @param app the Rack application to run
+  # @param [Hash] options the Akephalos configuration options
+  # @option options [Symbol] :browser (:firefox_3_6) the browser
+  #   compatibility mode to run in. Available options:
+  #       :firefox_3_6
+  #       :firefox_3
+  #       :ie6
+  #       :ie7
+  #       :ie8
+  #
+  # @option options [true, false] :validate_scripts (true) whether to raise
+  #   exceptions on script errors
+  #
+  def initialize(app, options = {})
+    @app = app
+    @options = options
+    @rack_server = Capybara::Server.new(@app)
+    @rack_server.boot if Capybara.run_server
+  end
+
+  # Visit the given path in the browser.
+  #
+  # @param [String] path relative path to visit
+  def visit(path)
+    browser.visit(url(path))
+  end
+
+  # @return [String] the page's original source
+  def source
+    page.source
+  end
+
+  # @return [String] the page's modified source
+  # page.modified_source will return a string with
+  # html entities converted into the unicode equivalent
+  # but the string will be marked as ASCII-8BIT
+  # which causes conversion issues so we force the encoding
+  # to UTF-8 (ruby 1.9 only)
+  def body
+    body_source = page.modified_source
+
+    if body_source.respond_to?(:force_encoding)
+      body_source.force_encoding("UTF-8")
+    else
+      body_source
+    end
+  end
+
+  # @return [Hash{String => String}] the page's response headers
+  def response_headers
+    page.response_headers
+  end
+
+  # @return [Integer] the response's status code
+  def status_code
+    page.status_code
+  end
+
+  # Execute the given block within the context of a specified frame.
+  #
+  # @param [String] frame_id the frame's id
+  # @raise [Capybara::ElementNotFound] if the frame is not found
+  def within_frame(frame_id, &block)
+    unless page.within_frame(frame_id, &block)
+      raise Capybara::ElementNotFound, "Unable to find frame with id '#{frame_id}'"
+    end
+  end
+
+  # Clear all cookie session data.
+  # @deprecated This method is deprecated in Capybara's master branch. Use
+  #   {#reset!} instead.
+  def cleanup!
+    reset!
+  end
+
+  # Clear all cookie session data.
+  def reset!
+    cookies.clear
+  end
+
+  # Confirm or cancel the dialog, returning the text of the dialog
+  def confirm_dialog(confirm = true, &block)
+    browser.confirm_dialog(confirm, &block)
+  end
+
+  # @return [String] the page's current URL
+  def current_url
+    page.current_url
+  end
+
+  # Search for nodes which match the given XPath selector.
+  #
+  # @param [String] selector XPath query
+  # @return [Array<Node>] the matched nodes
+  def find(selector)
+    nodes = []
+    page.find(selector).each { |node| nodes << Node.new(self, node) }
+    nodes
+  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)
+    page.execute_script script
+  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)
+    page.evaluate_script script
+  end
+
+  # @return the current page
+  def page
+    browser.page
+  end
+
+  # @return the browser
+  def browser
+    @browser ||= Akephalos::Client.new(@options)
+  end
+
+  # @return the session cookies
+  def cookies
+    browser.cookies
+  end
+
+  # @return [String] the current user agent string
+  def user_agent
+    browser.user_agent
+  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)
+    browser.user_agent = user_agent
+  end
+
+  # Disable waiting in Capybara, since waiting is handled directly by
+  # Akephalos.
+  #
+  # @return [false]
+  def wait
+    false
+  end
+
+  private
+
+  # @param [String] path
+  # @return [String] the absolute URL for the given path
+  def url(path)
+    rack_server.url(path)
+  end
+
+end
+
+Capybara.register_driver :akephalos do |app|
+  Capybara::Driver::Akephalos.new(app)
+end