celerity 0.0.6 → 0.0.7

data/History.txt

@@ -1,3 +1,39 @@
+== 0.0.7 2009-09-04
+* :firefox (Firefox 2) is now the default browser, :firefox3 support added.
+* Avoid huge Java backtraces on FailingHttpStatusCodeException
+* Browser#log_level= sets the log level for more HtmlUnit packages
+* Default log level is now :off
+* ClickableElement#click_and_attach inherits options from parent browser
+* Allow searching by XPath in frames.
+* Fix bug with scripts in body onload.
+* Nicer API for Browser#debug_web_connection
+* Fix bug in Browser#element_by_xpath(s) and Element#method_missing
+* Fix bug when selecting empty SelectList options
+* Fix issue when using multiple attributes to locate elements on a page with non-unique IDs.
+* Nicer #inspect methods on some objects
+* Improved IPC with viewers
+* Methods added:
+  - Browser#clear_cache
+  - Browser#confirm
+  - Browser#css=
+  - Browser#ignore_pattern=
+  - Browser#javascript_excepetion=
+  - Browser#secure_ssl=
+  - Browser#status
+  - Browser#status_code
+  - Browser#status_code_exceptions=
+  - Celerity.index_offset=
+  - ClickableElement#download
+  - Element#fire_event
+  - Element#javascript_object
+* New constructor options:
+  - :javascript_enabled => true, false
+  - :viewer             => true, false, String
+  - :refresh_handler    => :immediate, :waiting, :threaded
+* Features removed:
+  - Celerity::MethodGenerator
+* Most of the spec suite moved to the WatirSpec project
+
 == 0.0.6 2009-03-19
 * Support for meta, strong, dl, dt, dd, and em HTML elements.
 * Update to HtmlUnit 2.5-SNAPSHOT.

data/Manifest.txt

@@ -0,0 +1,82 @@
+History.txt
+License.txt
+Manifest.txt
+README.rdoc
+Rakefile
+celerity.gemspec
+lib/celerity.rb
+lib/celerity/browser.rb
+lib/celerity/clickable_element.rb
+lib/celerity/collections.rb
+lib/celerity/container.rb
+lib/celerity/default_viewer.rb
+lib/celerity/disabled_element.rb
+lib/celerity/element.rb
+lib/celerity/element_collection.rb
+lib/celerity/element_locator.rb
+lib/celerity/elements/button.rb
+lib/celerity/elements/file_field.rb
+lib/celerity/elements/form.rb
+lib/celerity/elements/frame.rb
+lib/celerity/elements/image.rb
+lib/celerity/elements/label.rb
+lib/celerity/elements/link.rb
+lib/celerity/elements/meta.rb
+lib/celerity/elements/non_control_elements.rb
+lib/celerity/elements/option.rb
+lib/celerity/elements/radio_check.rb
+lib/celerity/elements/select_list.rb
+lib/celerity/elements/table.rb
+lib/celerity/elements/table_cell.rb
+lib/celerity/elements/table_elements.rb
+lib/celerity/elements/table_row.rb
+lib/celerity/elements/text_field.rb
+lib/celerity/exception.rb
+lib/celerity/htmlunit.rb
+lib/celerity/htmlunit/commons-codec-1.4.jar
+lib/celerity/htmlunit/commons-collections-3.2.1.jar
+lib/celerity/htmlunit/commons-httpclient-3.1.jar
+lib/celerity/htmlunit/commons-io-1.4.jar
+lib/celerity/htmlunit/commons-lang-2.4.jar
+lib/celerity/htmlunit/commons-logging-1.1.1.jar
+lib/celerity/htmlunit/cssparser-0.9.5.jar
+lib/celerity/htmlunit/htmlunit-2.6.jar
+lib/celerity/htmlunit/htmlunit-core-js-2.6.jar
+lib/celerity/htmlunit/nekohtml-1.9.13.jar
+lib/celerity/htmlunit/sac-1.3.jar
+lib/celerity/htmlunit/serializer-2.7.1.jar
+lib/celerity/htmlunit/xalan-2.7.1.jar
+lib/celerity/htmlunit/xercesImpl-2.9.1.jar
+lib/celerity/htmlunit/xml-apis-1.3.04.jar
+lib/celerity/identifier.rb
+lib/celerity/ignoring_web_connection.rb
+lib/celerity/input_element.rb
+lib/celerity/listener.rb
+lib/celerity/resources/no_viewer.png
+lib/celerity/short_inspect.rb
+lib/celerity/util.rb
+lib/celerity/version.rb
+lib/celerity/viewer_connection.rb
+lib/celerity/watir_compatibility.rb
+lib/celerity/xpath_support.rb
+spec/browser_authentication_spec.rb
+spec/browser_spec.rb
+spec/clickable_element_spec.rb
+spec/default_viewer_spec.rb
+spec/element_spec.rb
+spec/filefield_spec.rb
+spec/htmlunit_spec.rb
+spec/index_offset_spec.rb
+spec/listener_spec.rb
+spec/spec_helper.rb
+tasks/benchmark.rake
+tasks/deployment.rake
+tasks/environment.rake
+tasks/fix.rake
+tasks/jar.rake
+tasks/rdoc.rake
+tasks/rspec.rake
+tasks/simple_ci.rake
+tasks/snapshot.rake
+tasks/website.rake
+tasks/yard.rake

data/README.rdoc

@@ -0,0 +1,78 @@
+= Celerity
+
+* http://celerity.rubyforge.org/
+
+== Description
+
+Celerity is a JRuby library for easy and fast functional test automation for web applications.
+
+It is a JRuby wrapper around HtmlUnit – a headless Java browser with 
+JavaScript support. It provides a simple API for programmatic navigation through
+web applications. Celerity aims at being API compatible with Watir.
+
+== Features
+
+* *Fast*: No time-consuming GUI rendering or unessential downloads
+* *Scalable*: Java threads lets you run tests in parallel
+* *Easy to use*: Simple API
+* *Portable*: Cross-platform thanks to the JVM
+* *Unintrusive*: No browser window interrupting your workflow (runs in background)
+	
+== Requirements
+
+* JRuby 1.2.0 or higher
+* Java 6
+
+== Install
+
+    jruby -S gem install celerity
+  
+or from GitHub (updated frequently)
+  
+    jruby -S gem install jarib-celerity
+  
+  
+== Example
+
+    require "rubygems"
+    require "celerity" 
+
+    browser = Celerity::Browser.new
+    browser.goto('http://www.google.com')
+    browser.text_field(:name, 'q').value = 'Celerity'
+    browser.button(:name, 'btnG').click
+
+    puts "yay" if browser.text.include? 'celerity.rubyforge.org'
+  
+== Source
+
+The source code is available on [GitHub](http://github.com/jarib/celerity/tree/master).
+
+
+== Wiki & Bug Tracker
+
+* [Wiki](http://github.com/jarib/celerity/wikis)
+* [Bug Tracker](http://github.com/jarib/celerity/issues)
+
+== Related projects
+
+* [WatirSpec](http://github.com/jarib/watirspec/tree/master)
+* [Celerity Viewers](http://github.com/jarib/celerity-viewers)
+
+== License
+
+Celerity - JRuby wrapper for HtmlUnit
+Copyright (c) 2008-2009 FINN.no AS
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.

data/Rakefile

@@ -1,12 +1,27 @@
-$:.unshift("#{File.dirname(__FILE__)}/lib")
-
-if File.exist?('config') # are we in a git clone
-  require 'config/requirements'
-  require 'config/hoe' # setup Hoe + all gem configuration
-  Dir['tasks/**/*.rake'].each { |rake| load rake }
-else # in gem dir
-  load 'tasks/jar.rake'
-  load 'tasks/rdoc.rake'
-end
+require 'rubygems'
+gem 'hoe', '>= 2.3.0'
+require 'hoe'
+%w[fileutils rubigen].each { |f| require f }
+
+require "lib/celerity/version"
 
+Hoe.plugin :newgem # newgem 1.5.2+
+Hoe.plugin :website
 
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+Hoe.spec 'celerity' do
+  author         << "Jari Bakken" << "T. Alexander Lystad" << "Knut Johannes Dahle"
+  email          << "jari.bakken@finn.no"
+  extra_dev_deps << ['sinatra', '>= 0.9.4']
+  version         = Celerity::VERSION
+end
+
+Dir['tasks/**/*.rake'].each do |rake|
+  begin
+    load rake
+  rescue LoadError
+  end
+end
+# load 'tasks/jar.rake'
+# load 'tasks/rdoc.rake'

data/celerity.gemspec

@@ -0,0 +1,40 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{celerity}
+  s.version = "0.0.7"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Jari Bakken", "T. Alexander Lystad", "Knut Johannes Dahle"]
+  s.date = %q{2009-09-04}
+  s.description = %q{Celerity is a JRuby library for easy and fast functional test automation for web applications.
+
+It is a JRuby wrapper around HtmlUnit – a headless Java browser with 
+JavaScript support. It provides a simple API for programmatic navigation through
+web applications. Celerity aims at being API compatible with Watir.}
+  s.email = ["jari.bakken@finn.no"]
+  s.extra_rdoc_files = ["History.txt", "License.txt", "Manifest.txt"]
+  s.files = ["History.txt", "License.txt", "Manifest.txt", "README.rdoc", "Rakefile", "celerity.gemspec", "lib/celerity.rb", "lib/celerity/browser.rb", "lib/celerity/clickable_element.rb", "lib/celerity/collections.rb", "lib/celerity/container.rb", "lib/celerity/default_viewer.rb", "lib/celerity/disabled_element.rb", "lib/celerity/element.rb", "lib/celerity/element_collection.rb", "lib/celerity/element_locator.rb", "lib/celerity/elements/button.rb", "lib/celerity/elements/file_field.rb", "lib/celerity/elements/form.rb", "lib/celerity/elements/frame.rb", "lib/celerity/elements/image.rb", "lib/celerity/elements/label.rb", "lib/celerity/elements/link.rb", "lib/celerity/elements/meta.rb", "lib/celerity/elements/non_control_elements.rb", "lib/celerity/elements/option.rb", "lib/celerity/elements/radio_check.rb", "lib/celerity/elements/select_list.rb", "lib/celerity/elements/table.rb", "lib/celerity/elements/table_cell.rb", "lib/celerity/elements/table_elements.rb", "lib/celerity/elements/table_row.rb", "lib/celerity/elements/text_field.rb", "lib/celerity/exception.rb", "lib/celerity/htmlunit.rb", "lib/celerity/htmlunit/commons-codec-1.4.jar", "lib/celerity/htmlunit/commons-collections-3.2.1.jar", "lib/celerity/htmlunit/commons-httpclient-3.1.jar", "lib/celerity/htmlunit/commons-io-1.4.jar", "lib/celerity/htmlunit/commons-lang-2.4.jar", "lib/celerity/htmlunit/commons-logging-1.1.1.jar", "lib/celerity/htmlunit/cssparser-0.9.5.jar", "lib/celerity/htmlunit/htmlunit-2.6.jar", "lib/celerity/htmlunit/htmlunit-core-js-2.6.jar", "lib/celerity/htmlunit/nekohtml-1.9.13.jar", "lib/celerity/htmlunit/sac-1.3.jar", "lib/celerity/htmlunit/serializer-2.7.1.jar", "lib/celerity/htmlunit/xalan-2.7.1.jar", "lib/celerity/htmlunit/xercesImpl-2.9.1.jar", "lib/celerity/htmlunit/xml-apis-1.3.04.jar", "lib/celerity/identifier.rb", "lib/celerity/ignoring_web_connection.rb", "lib/celerity/input_element.rb", "lib/celerity/listener.rb", "lib/celerity/resources/no_viewer.png", "lib/celerity/short_inspect.rb", "lib/celerity/util.rb", "lib/celerity/version.rb", "lib/celerity/viewer_connection.rb", "lib/celerity/watir_compatibility.rb", "lib/celerity/xpath_support.rb", "spec/browser_authentication_spec.rb", "spec/browser_spec.rb", "spec/clickable_element_spec.rb", "spec/default_viewer_spec.rb", "spec/element_spec.rb", "spec/filefield_spec.rb", "spec/htmlunit_spec.rb", "spec/index_offset_spec.rb", "spec/listener_spec.rb", "spec/spec_helper.rb", "tasks/benchmark.rake", "tasks/deployment.rake", "tasks/environment.rake", "tasks/fix.rake", "tasks/jar.rake", "tasks/rdoc.rake", "tasks/rspec.rake", "tasks/simple_ci.rake", "tasks/snapshot.rake", "tasks/website.rake", "tasks/yard.rake"]
+  s.homepage = %q{http://celerity.rubyforge.org/}
+  s.rdoc_options = ["--main", "README.rdoc"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{celerity}
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{Celerity is a JRuby library for easy and fast functional test automation for web applications}
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<sinatra>, [">= 0.9.4"])
+      s.add_development_dependency(%q<hoe>, [">= 2.3.3"])
+    else
+      s.add_dependency(%q<sinatra>, [">= 0.9.4"])
+      s.add_dependency(%q<hoe>, [">= 2.3.3"])
+    end
+  else
+    s.add_dependency(%q<sinatra>, [">= 0.9.4"])
+    s.add_dependency(%q<hoe>, [">= 2.3.3"])
+  end
+end

data/lib/celerity.rb

@@ -2,13 +2,13 @@ $:.unshift(File.dirname(__FILE__)) unless $:.include?(File.dirname(__FILE__)) ||
 
 raise "Celerity only works on JRuby at the moment." unless RUBY_PLATFORM =~ /java/
 
-require 'java'
+require "java"
 require "logger"
 require "uri"
 require "pp"
 require "timeout"
 require "time"
-require 'drb'
+require "socket"
 require "fileutils"
 require "thread"
 
@@ -16,12 +16,24 @@ module Celerity
   Log = Logger.new($DEBUG ? $stderr : nil)
   Log.level = Logger::DEBUG
 
-  INDEX_OFFSET = 1
+  @index_offset = 1
+  class << self
+
+    #
+    # This index_offset attribute controls the indexing used when locating
+    # elements by :index or fetching from Celerity::ElementCollections.
+    #
+    # By default it is set to 1 for Watir compatibility, but users who use
+    # Celerity exlusively may want it set to 0 to make Celerity more consistent with Ruby.
+    #
+    attr_accessor :index_offset
+  end
+
   DIR = File.expand_path(File.dirname(__FILE__) + "/celerity")
 end
 
-require "celerity/htmlunit"
 require "celerity/version"
+require "celerity/htmlunit"
 require "celerity/exception"
 require "celerity/clickable_element"
 require "celerity/disabled_element"
@@ -29,29 +41,33 @@ require "celerity/element_collection"
 require "celerity/collections"
 require "celerity/element_locator"
 require "celerity/identifier"
+require "celerity/short_inspect"
 require "celerity/container"
+require "celerity/xpath_support"
 require "celerity/element"
 require "celerity/input_element"
 require "celerity/elements/non_control_elements"
-require "celerity/elements/button.rb"
-require "celerity/elements/file_field.rb"
-require "celerity/elements/form.rb"
-require "celerity/elements/frame.rb"
-require "celerity/elements/image.rb"
-require "celerity/elements/label.rb"
-require "celerity/elements/link.rb"
-require "celerity/elements/meta.rb"
-require "celerity/elements/option.rb"
-require "celerity/elements/radio_check.rb"
-require "celerity/elements/select_list.rb"
-require "celerity/elements/table.rb"
-require "celerity/elements/table_elements.rb"
-require "celerity/elements/table_cell.rb"
-require "celerity/elements/table_row.rb"
-require "celerity/elements/text_field.rb"
+require "celerity/elements/button"
+require "celerity/elements/file_field"
+require "celerity/elements/form"
+require "celerity/elements/frame"
+require "celerity/elements/image"
+require "celerity/elements/label"
+require "celerity/elements/link"
+require "celerity/elements/meta"
+require "celerity/elements/option"
+require "celerity/elements/radio_check"
+require "celerity/elements/select_list"
+require "celerity/elements/table"
+require "celerity/elements/table_elements"
+require "celerity/elements/table_cell"
+require "celerity/elements/table_row"
+require "celerity/elements/text_field"
 require "celerity/util"
 require "celerity/default_viewer"
 require "celerity/listener"
+require "celerity/ignoring_web_connection"
+require "celerity/viewer_connection"
 require "celerity/browser"
 require "celerity/watir_compatibility"
 

data/lib/celerity/browser.rb

@@ -1,16 +1,17 @@
 module Celerity
   class Browser
     include Container
+    include XpathSupport
 
     attr_accessor :page, :object, :charset
-    attr_reader :webclient, :viewer
+    attr_reader :webclient, :viewer, :options
 
     #
     # Initialize a browser and go to the given URL
-    # 
+    #
     # @param [String] uri The URL to go to.
     # @return [Celerity::Browser] instance.
-    # 
+    #
 
     def self.start(uri)
       browser = new
@@ -26,27 +27,26 @@ module Celerity
       raise NotImplementedError, "use ClickableElement#click_and_attach instead"
     end
 
-    def inspect
-      vars = (instance_variables - %w[@webclient @browser @object])
-      vars = vars.map { |var| "#{var}=#{instance_variable_get(var).inspect}" }.join(" ")
-      '#<%s:0x%s %s>' % [self.class.name, self.hash.to_s(16), vars]
-    end
-
     #
     # Creates a browser object.
     #
     # @see Celerity::Container for an introduction to the main API.
     #
-    # @option opts :log_level [Symbol] (:warning) @see log_level=
-    # @option opts :browser [:firefox, :internet_explorer] (:internet_explorer) Set the BrowserVersion used by HtmlUnit. Defaults to Internet Explorer.
+    # @option opts :browser [:internet_explorer, :firefox, :firefox3] (:firefox) Set the BrowserVersion used by HtmlUnit. Defaults to Firefox 2.
+    # @option opts :charset [String] ("UTF-8") Specify the charset that webclient will use for requests, and those where texts are getting gibberished, like Browser#html.
     # @option opts :css [Boolean] (false) Enable CSS.  Disabled by default.
-    # @option opts :secure_ssl [Boolean] (true)  Disable secure SSL. Enabled by default.
-    # @option opts :resynchronize [Boolean] (false) Use HtmlUnit::NicelyResynchronizingAjaxController to resynchronize Ajax calls.
+    # @option opts :ignore_pattern [Regexp] See Browser#ignore_pattern=
+    # @option opts :javascript_enabled [Boolean] (true)  Enable/disable JavaScript evaluation. Enabled by default.
     # @option opts :javascript_exceptions [Boolean] (false) Raise exceptions on script errors. Disabled by default.
-    # @option opts :status_code_exceptions [Boolean] (false) Raise exceptions on failing status codes (404 etc.). Disabled by default.
-    # @option opts :render [:html, :xml] (:html) What DOM representation to send to connected viewers.
-    # @option opts :charset [String] ("UTF-8") Specify the charset that webclient will use by default.
+    # @option opts :log_level [Symbol] (:warning) @see log_level=
     # @option opts :proxy [String] (nil) Proxy server to use, in address:port format.
+    # @option opts :refresh_handler [:immediate, :waiting, :threaded] (:immediate) Set HtmlUnit's refresh handler.
+    # @option opts :render [:html, :xml] (:html) What DOM representation to send to connected viewers.
+    # @option opts :resynchronize [Boolean] (false) Use HtmlUnit::NicelyResynchronizingAjaxController to resynchronize Ajax calls.
+    # @option opts :secure_ssl [Boolean] (true)  Enable/disable secure SSL. Enabled by default.
+    # @option opts :status_code_exceptions [Boolean] (false) Raise exceptions on failing status codes (404 etc.). Disabled by default.
+    # @option opts :user_agent [String] Override the User-Agent set by the :browser option
+    # @option opts :viewer [Boolean] (true) Connect to a CelerityViewer on port 6429 if available.
     #
     # @return [Celerity::Browser]     An instance of the browser.
     #
@@ -58,22 +58,29 @@ module Celerity
         raise TypeError, "wrong argument type #{opts.class}, expected Hash"
       end
 
-      unless (render_types = [:html, :xml, nil]).include?(opts[:render])
+      unless (render_types = [:html, :xml, nil, 'html', 'xml']).include?(opts[:render])
         raise ArgumentError, "expected one of #{render_types.inspect} for key :render"
       end
 
+      opts     = opts.dup # we'll delete from opts, so dup to avoid side effects
+      @options = opts.dup # keep the unmodified version around as well
+
       @render_type   = opts.delete(:render)    || :html
       @charset       = opts.delete(:charset)   || "UTF-8"
-      self.log_level = opts.delete(:log_level) || :warning
+      self.log_level = opts.delete(:log_level) || :off
 
-      @last_url, @page = nil
-      @error_checkers  = []
-      @browser         = self # for Container#browser
+      @page           = nil
+      @error_checkers = []
+      @browser        = self # for Container#browser
+
+      setup_webclient opts
+      setup_viewer opts.delete(:viewer)
 
-      setup_webclient(opts)
-      
       raise ArgumentError, "unknown option #{opts.inspect}" unless opts.empty?
-      find_viewer
+    end
+
+    def inspect
+      short_inspect :exclude => %w[@webclient @browser @object @options @listener @event_listener]
     end
 
     #
@@ -89,7 +96,9 @@ module Celerity
       request = HtmlUnit::WebRequestSettings.new(::Java::JavaNet::URL.new(uri))
       request.setCharset(@charset)
 
-      self.page = @webclient.getPage(request)
+      rescue_status_code_exception do
+        self.page = @webclient.getPage(request)
+      end
 
       url()
     end
@@ -117,11 +126,12 @@ module Celerity
     def close
       @page = nil
       @webclient.closeAllWindows
+      @viewer.close
     end
 
     #
     # @return [String] the URL of the current page
-    # 
+    #
 
     def url
       assert_exists
@@ -136,18 +146,26 @@ module Celerity
       @page ? @page.getTitleText : ''
     end
 
+    #
+    # @return [String] the value of window.status
+    #
+
+    def status
+      execute_script "window.status" # avoid the listener overhead
+    end
+
     #
     # @return [String] the HTML content of the current page
     #
-    
+
     def html
-      @page ? @page.getWebResponse.getContentAsString : ''
+      @page ? @page.getWebResponse.getContentAsString(@charset) : ''
     end
-    
+
     #
     # @return [String] the XML representation of the DOM
     #
-    
+
     def xml
       return '' unless @page
       return @page.asXml if @page.respond_to?(:asXml)
@@ -157,14 +175,16 @@ module Celerity
     #
     # @return [String] a text representation of the current page
     #
-    
+
     def text
       return '' unless @page
 
       if @page.respond_to?("getContent")
         string = @page.getContent.strip
-      else
+      elsif @page.documentElement
         string = @page.documentElement.asText.strip
+      else
+        string = ''
       end
 
       # Celerity::Util.normalize_text(string)
@@ -177,27 +197,35 @@ module Celerity
 
     def response_headers
       return {} unless @page
-      
+
       Hash[*@page.getWebResponse.getResponseHeaders.map { |obj| [obj.name, obj.value] }.flatten]
     end
 
+    #
+    # @return [Fixnum] status code of the last request
+    #
+
+    def status_code
+      @page.getWebResponse.getStatusCode
+    end
+
     #
     # @return [String] content-type as in 'text/html'
     #
 
     def content_type
       return '' unless @page
-      
+
       @page.getWebResponse.getContentType
     end
 
     #
     # @return [IO, nil] page contents as an IO, returns nil if no page is loaded.
-    # 
-    
+    #
+
     def io
       return nil unless @page
-      
+
       @page.getWebResponse.getContentAsStream.to_io
     end
 
@@ -207,7 +235,7 @@ module Celerity
     # @param  [String, Regexp] expected_text The text to look for.
     # @return [Numeric, nil]  The index of the matched text, or nil if it isn't found.
     # @raise  [TypeError]
-    # 
+    #
 
     def contains_text(expected_text)
       return nil unless exist?
@@ -215,131 +243,128 @@ module Celerity
     end
 
     #
-    # Get the first element found matching the given XPath.
-    #
-    # @param [String] xpath
-    # @return [Celerity::Element] An element subclass (or Element if none is found)
+    # @return [HtmlUnit::HtmlHtml] the underlying HtmlUnit document.
     #
-    
-    def element_by_xpath(xpath)
-      assert_exists
-      obj = @page.getFirstByXPath(xpath)
-      element_from_dom_node(obj)
+
+    def document
+      @object
     end
 
     #
-    # Get all the elements matching the given XPath.
-    #
-    # @param [String] xpath
-    # @return [Array<Celerity::Element>] array of elements
+    # Goto back one history item
+    # @return [String] The url of the resulting page.
     #
-    
-    def elements_by_xpath(xpath)
-      assert_exists
-      objects = @page.getByXPath(xpath)
-      # should use an ElementCollection here?
-      objects.map { |o| element_from_dom_node(o) }.compact
-    end
 
-    #
-    # @return [HtmlUnit::HtmlHtml] the underlying HtmlUnit document.
-    # 
-    
-    def document
-      @object
+    def back
+      @webclient.getCurrentWindow.getHistory.back
+      refresh_page_from_window
+
+      url
     end
 
     #
-    # Goto the last url - HtmlUnit doesn't have a 'back' functionality, so we only have 1 history item :)
-    # @return [String, nil] The url of the resulting page, or nil if none was stored.
-    # 
+    # Go forward one history item
+    # @return [String] The url of the resulting page.
+    #
 
-    def back
-      # TODO: this is naive, need capability from HtmlUnit
-      goto(@last_url) if @last_url
+    def forward
+      @webclient.getCurrentWindow.getHistory.forward
+      refresh_page_from_window
+
+      url
     end
 
     #
     # Wait for javascript jobs to finish
-    # 
+    #
 
     def wait
       assert_exists
-      @page.getEnclosingWindow.getJobManager.waitForAllJobsToFinish(10000)
+      @webclient.waitForBackgroundJavaScript(10000);
     end
 
     #
     # Refresh the current page
-    # 
+    #
 
     def refresh
       assert_exists
-      self.page = @page.refresh
+      @page.refresh
     end
 
     #
     # Clears all cookies. (Celerity only)
-    # 
+    #
 
     def clear_cookies
       @webclient.getCookieManager.clearCookies
     end
 
+    #
+    # Clears the cache of "compiled JavaScript files and parsed CSS snippets"
+    #
+
+    def clear_cache
+      @webclient.cache.clear
+    end
+
     #
     # Get the cookies for this session. (Celerity only)
-    # 
-    # @return [Hash<domain, Hash<name, value>>] 
+    #
+    # @return [Hash<domain, Hash<name, value>>]
     #
 
     def cookies
       result = Hash.new { |hash, key| hash[key] = {} }
-      
+
       cookies = @webclient.getCookieManager.getCookies
       cookies.each do |cookie|
         result[cookie.getDomain][cookie.getName] = cookie.getValue
       end
-      
+
       result
     end
-    
+
     #
     # Add a cookie with the given parameters (Celerity only)
-    # 
+    #
     # @param [String] domain
     # @param [String] name
     # @param [String] value
     #
-    # @option opts :path    [String]  ("/") A path 
+    # @option opts :path    [String]  ("/") A path
     # @option opts :max_age [Fixnum]  (??) A max age
-    # @option opts :secure  [Boolean] (false) 
+    # @option opts :secure  [Boolean] (false)
     #
-    
+
     def add_cookie(domain, name, value, opts = {})
       path    = opts.delete(:path) || "/"
       max_age = opts.delete(:max_age) || (Time.now + 60*60*24) # not sure if this is correct
       secure  = opts.delete(:secure) || false
 
-      raise "unknown option: #{opts.inspect}" unless opts.empty?
+      raise(ArgumentError, "unknown option: #{opts.inspect}") unless opts.empty?
 
       cookie = Cookie.new(domain, name, value, path, max_age, secure)
       @webclient.getCookieManager.addCookie(cookie)
     end
-    
+
     #
     # Remove the cookie with the given domain and name (Celerity only)
     #
     # @param [String] domain
     # @param [String] name
     #
-    
+    # @raise [CookieNotFoundError] if the cookie doesn't exist
+    #
+
     def remove_cookie(domain, name)
       cm = @webclient.getCookieManager
       cookie = cm.getCookies.find { |c| c.getDomain == domain && c.getName == name }
-      
+
       if cookie.nil?
-        raise "no cookie with domain #{domain.inspect} and name #{name.inspect}"
+        raise CookieNotFoundError, "no cookie with domain #{domain.inspect} and name #{name.inspect}"
       end
-      
+
       cm.removeCookie(cookie)
     end
 
@@ -376,14 +401,18 @@ module Celerity
     # @yieldparam [Celerity::Browser] browser The browser instance.
     # @see Celerity::Browser#resynchronized
     #
-    
+
     def wait_until(timeout = 30, &block)
+      returned = nil
+
       Timeout.timeout(timeout) do
-        until yield(self)
+        until returned = yield(self)
           refresh_page_from_window
           sleep 0.1
         end
       end
+
+      returned
     end
 
     #
@@ -392,19 +421,24 @@ module Celerity
     # @param [Fixnum] timeout Number of seconds to wait before timing out (default: 30).
     # @yieldparam [Celerity::Browser] browser The browser instance.
     # @see Celerity::Browser#resynchronized
-    # 
+    #
 
     def wait_while(timeout = 30, &block)
+      returned = nil
+
       Timeout.timeout(timeout) do
-        while yield(self)
+        while returned = yield(self)
           refresh_page_from_window
           sleep 0.1
         end
       end
+
+      returned
     end
 
     #
-    # Allows you to temporarily switch to HtmlUnit's NicelyResynchronizingAjaxController to resynchronize ajax calls.
+    # Allows you to temporarily switch to HtmlUnit's NicelyResynchronizingAjaxController
+    # to resynchronize ajax calls.
     #
     #   @browser.resynchronized do |b|
     #     b.link(:id, 'trigger_ajax_call').click
@@ -420,15 +454,16 @@ module Celerity
       yield self
       @webclient.setAjaxController(old_controller)
     end
-    
+
+    #
+    # Allows you to temporarliy switch to HtmlUnit's default AjaxController, so
+    # ajax calls are performed asynchronously. This is useful if you have created
+    # the Browser with :resynchronize => true, but want to switch it off temporarily.
     #
-    # Allows you to temporarliy switch to HtmlUnit's default AjaxController, so ajax calls are performed asynchronously.
-    # This is useful if you have created the Browser with :resynchronize => true, but want to switch it off temporarily.
-    # 
     # @yieldparam [Celerity::Browser] browser The current browser object.
     # @see Celerity::Browser#new
     #
-    
+
     def asynchronized(&block)
       old_controller = @webclient.ajaxController
       @webclient.setAjaxController(::HtmlUnit::AjaxController.new)
@@ -440,21 +475,18 @@ module Celerity
     # Start or stop HtmlUnit's DebuggingWebConnection. (Celerity only)
     # The output will go to /tmp/«name»
     #
-    # @param [Boolean] bool start or stop
-    # @param [String]  name required if bool is true
-    # 
-
-    def debug_web_connection(bool, name = nil)
-      if bool
-        raise "no name given" unless name
-        @old_webconnection = @webclient.getWebConnection
-        dwc = HtmlUnit::Util::DebuggingWebConnection.new(@old_webconnection, name)
-        @webclient.setWebConnection(dwc)
-        $stderr.puts "debug-webconnection on"
-      else
-        @webclient.setWebConnection(@old_webconnection) if @old_webconnection
-        $stderr.puts "debug-webconnection off"
-      end
+    # @param [String]  name directory name
+    # @param [block]   blk block to execute
+    #
+
+    def debug_web_connection(name, &blk)
+      old_wc = @webclient.getWebConnection
+
+      @webclient.setWebConnection HtmlUnit::Util::DebuggingWebConnection.new(old_wc, name)
+      res = yield
+      @webclient.setWebConnection old_wc
+
+      res
     end
 
     #
@@ -469,23 +501,54 @@ module Celerity
     #   :confirm          => ConfirmHandler ( window.confirm() )
     #   :prompt           => PromptHandler ( window.prompt() )
     #
+    # Examples:
+    #
+    #   browser.add_listener(:status) { |page, message| ... }
+    #   browser.add_listener(:alert) { |page, message| ... }
+    #   browser.add_listener(:web_window_event) { |web_window_event| ... }
+    #   browser.add_listener(:html_parser) { |message, url, line, column, key| ... }
+    #   browser.add_listener(:incorrectness) { |message, origin| ... }
+    #   browser.add_listener(:confirm) { |page, message| ...; true }
+    #   browser.add_listener(:prompt) { |page, message| ... }
+    #
     #
     # @param [Symbol] type One of the above symbols.
     # @param [Proc] block A block to be executed for events of this type.
-    # 
+    #
 
     def add_listener(type, &block)
-      @listener ||= Celerity::Listener.new(@webclient)
-      @listener.add_listener(type, &block)
+      listener.add_listener(type, &block)
+    end
+
+    def remove_listener(type, &block)
+      listener.remove_listener(type, &block)
     end
-    
+
+    #
+    # Specify a boolean value to click either 'OK' or 'Cancel' in any confirm
+    # dialogs that might show up during the duration of the given block.
+    #
+    # (Celerity only)
+    #
+    # @param [Boolean] bool true to click 'OK', false to click 'cancel'
+    # @param [Proc] block A block that will trigger the confirm() call(s).
+    #
+
+    def confirm(bool, &block)
+      blk = lambda { bool }
+
+      listener.add_listener(:confirm, &blk)
+      yield
+      listener.remove_listener(:confirm, blk)
+    end
+
     #
     # Add a 'checker' proc that will be run on every page load
     #
     # @param [Proc] checker The proc to be run (can also be given as a block)
     # @yieldparam [Celerity::Browser] browser The current browser object.
     # @raise [ArgumentError] if no Proc or block was given.
-    # 
+    #
 
     def add_checker(checker = nil, &block)
       if block_given?
@@ -500,7 +563,7 @@ module Celerity
     #
     # Remove the given checker from the list of checkers
     # @param [Proc] checker The Proc to disable.
-    # 
+    #
 
     def disable_checker(checker)
       @error_checkers.delete(checker)
@@ -508,22 +571,45 @@ module Celerity
 
     #
     # :finest, :finer, :fine, :config, :info, :warning, :severe, or :off, :all
-    # 
+    #
     # @return [Symbol] the current log level
-    # 
+    #
 
     def log_level
-      java.util.logging.Logger.getLogger('com.gargoylesoftware.htmlunit').level.to_s.downcase.to_sym
+      Celerity::Util.logger_for('com.gargoylesoftware.htmlunit').level.to_s.downcase.to_sym
     end
 
     #
-    # Set Java log level (default is :warning)
+    # Set Java log level (default is :warning, can be any of :all, :finest, :finer, :fine, :config, :info, :warning, :severe, :off)
+    #
+    # @param [Symbol] level The new log level.
     #
-    # @param [Symbol] level :finest, :finer, :fine, :config, :info, :warning, :severe, or :off, :all
-    # 
 
     def log_level=(level)
-      java.util.logging.Logger.getLogger('com.gargoylesoftware.htmlunit').level = java.util.logging.Level.const_get(level.to_s.upcase)
+      log_level = java.util.logging.Level.const_get(level.to_s.upcase)
+
+      [ 'com.gargoylesoftware.htmlunit',
+        'com.gargoylesoftware.htmlunit.html',
+        'com.gargoylesoftware.htmlunit.javascript',
+        'org.apache.commons.httpclient'
+      ].each { |package| Celerity::Util.logger_for(package).level = log_level }
+
+      level
+    end
+
+    #
+    # If a request is made to an URL that matches the pattern set here, Celerity
+    # will ignore the request and return an empty page with content type "text/html" instead.
+    #
+    # This is useful to block unwanted requests (like ads/banners).
+    #
+
+    def ignore_pattern=(regexp)
+      unless regexp.kind_of?(Regexp)
+        raise TypeError, "expected Regexp, got #{regexp.inspect}:#{regexp.class}"
+      end
+
+      Celerity::IgnoringWebConnection.new(@webclient, regexp)
     end
 
     #
@@ -536,6 +622,91 @@ module Celerity
     end
     alias_method :exists?, :exist?
 
+    #
+    # Turn on/off javascript exceptions
+    #
+    # @param [Bool]
+    #
+
+    def javascript_exceptions=(bool)
+      @webclient.throwExceptionOnScriptError = bool
+    end
+
+    def javascript_exceptions
+      @webclient.throwExceptionOnScriptError
+    end
+
+    #
+    # Turn on/off status code exceptions
+    #
+    # @param [Bool]
+    #
+
+    def status_code_exceptions=(bool)
+      @webclient.throwExceptionOnFailingStatusCode = bool
+    end
+
+    def status_code_exceptions
+      @webclient.throwExceptionOnFailingStatusCode
+    end
+
+    #
+    # Turn on/off CSS loading
+    #
+    # @param [Bool]
+    #
+
+    def css=(bool)
+      @webclient.cssEnabled = bool
+    end
+
+    def css
+      @webclient.cssEnabled
+    end
+
+    def refresh_handler=(symbol)
+      handler = case symbol
+                when :waiting
+                  HtmlUnit::WaitingRefreshHandler.new
+                when :threaded
+                  HtmlUnit::ThreadedRefreshHandler.new
+                when :immediate
+                  HtmlUnit::ImmediateRefreshHandler.new
+                else
+                  raise ArgumentError, "expected :waiting, :threaded or :immediate"
+                end
+
+      @webclient.setRefreshHandler handler
+    end
+
+    #
+    # Turn on/off secure SSL
+    #
+    # @param [Bool]
+    #
+
+    def secure_ssl=(bool)
+      @webclient.useInsecureSSL = !bool
+    end
+
+    def secure_ssl
+      !@webclient.useInsecureSSL
+    end
+
+    #
+    # Turn on/off JavaScript execution
+    #
+    # @param [Bool]
+    #
+
+    def javascript_enabled=(bool)
+      @webclient.setJavaScriptEnabled(bool)
+    end
+
+    def javascript_enabled
+      @webclient.isJavaScriptEnabled
+    end
+
     #
     # Sets the current page object for the browser
     #
@@ -544,11 +715,11 @@ module Celerity
     #
 
     def page=(value)
-      @last_url = url() if exist?
+      return if @page == value
       @page = value
 
       if @page.respond_to?("getDocumentElement")
-        @object = @page.getDocumentElement
+        @object = @page.getDocumentElement || @object
       elsif @page.is_a? HtmlUnit::UnexpectedPage
         raise UnexpectedPageException, @page.getWebResponse.getContentType
       end
@@ -562,21 +733,52 @@ module Celerity
     #
     # Check that we have a @page object.
     #
-    # @raise [Celerity::Exception::UnknownObjectException] if no page is loaded.
+    # @raise [UnknownObjectException] if no page is loaded.
     # @api private
-    # 
-    
+    #
+
     def assert_exists
       raise UnknownObjectException, "no page loaded" unless exist?
     end
-    
+
     #
     # Returns the element that currently has the focus (Celerity only)
     #
 
     def focused_element
       element_from_dom_node(page.getFocusedElement())
-    end    
+    end
+
+    #
+    # Enable Celerity's internal WebWindowEventListener
+    #
+    # @api private
+    #
+
+    def enable_event_listener
+      @event_listener ||= lambda do |event|
+        self.page = @page ? @page.getEnclosingWindow.getEnclosedPage : event.getNewPage
+      end
+
+      listener.add_listener(:web_window_event, &@event_listener)
+    end
+
+    #
+    # Disable Celerity's internal WebWindowEventListener
+    #
+    # @api private
+    #
+
+    def disable_event_listener
+      listener.remove_listener(:web_window_event, @event_listener)
+
+      if block_given?
+        result = yield
+        enable_event_listener
+
+        result
+      end
+    end
 
     private
 
@@ -585,49 +787,78 @@ module Celerity
     #
     # @see add_checker
     # @api private
-    # 
-    
+    #
+
     def run_error_checks
       @error_checkers.each { |e| e[self] }
     end
-    
+
     #
     # Configure the webclient according to the options given to #new.
     # @see initialize
     #
 
     def setup_webclient(opts)
-      browser = (opts.delete(:browser) || :internet_explorer).to_sym
+      browser = (opts.delete(:browser) || :firefox).to_sym
+
+      browser_version = case browser
+                        when :firefox, :ff, :ff2
+                          ::HtmlUnit::BrowserVersion::FIREFOX_2
+                        when :firefox3, :ff3
+                          ::HtmlUnit::BrowserVersion::FIREFOX_3
+                        when :internet_explorer, :ie
+                          ::HtmlUnit::BrowserVersion::INTERNET_EXPLORER_7
+                        else
+                          raise ArgumentError, "unknown browser: #{browser.inspect}"
+                        end
+
+      if ua = opts.delete(:user_agent)
+        browser_version.setUserAgent(ua)
+      end
 
-      case browser
-      when :firefox
-        browser_version = ::HtmlUnit::BrowserVersion::FIREFOX_2
-      when :internet_explorer, :ie
-        browser_version = ::HtmlUnit::BrowserVersion::INTERNET_EXPLORER_7_0
-      else
-        raise ArgumentError, "unknown browser: #{browser.inspect}"
+      @webclient = if proxy = opts.delete(:proxy)
+                     phost, pport = proxy.split(":")
+                     ::HtmlUnit::WebClient.new(browser_version, phost, pport.to_i)
+                   else
+                     ::HtmlUnit::WebClient.new(browser_version)
+                   end
+
+      self.javascript_exceptions  = false unless opts.delete(:javascript_exceptions)
+      self.status_code_exceptions = false unless opts.delete(:status_code_exceptions)
+      self.css                    = false unless opts.delete(:css)
+      self.javascript_enabled     = opts.delete(:javascript_enabled) != false
+      self.secure_ssl             = opts.delete(:secure_ssl) == false
+      self.ignore_pattern         = opts.delete(:ignore_pattern) if opts[:ignore_pattern]
+      self.refresh_handler        = opts.delete(:refresh_handler) if opts[:refresh_handler]
+
+      if opts.delete(:resynchronize)
+        controller = ::HtmlUnit::NicelyResynchronizingAjaxController.new
+        @webclient.setAjaxController controller
       end
 
-      if proxy = opts.delete(:proxy)
-        phost, pport = proxy.split(":")
-        @webclient = ::HtmlUnit::WebClient.new(browser_version, phost, pport.to_i)
-      else
-        @webclient = ::HtmlUnit::WebClient.new(browser_version)  
+      enable_event_listener
+    end
+
+    def setup_viewer(option)
+      @viewer = DefaultViewer
+      return if option == false
+
+      host_string = option.kind_of?(String) ? option : "127.0.0.1:6429"
+      host, port  = host_string.split(":")
+
+      if viewer = ViewerConnection.create(host, port.to_i)
+        @viewer = viewer
       end
-      
-      @webclient.throwExceptionOnScriptError = false unless opts.delete(:javascript_exceptions)
-      @webclient.throwExceptionOnFailingStatusCode = false unless opts.delete(:status_code_exceptions)
-      @webclient.cssEnabled = false unless opts.delete(:css)
-      @webclient.useInsecureSSL = opts.delete(:secure_ssl) == false
-      @webclient.setAjaxController(::HtmlUnit::NicelyResynchronizingAjaxController.new) if opts.delete(:resynchronize)
+    rescue Errno::ECONNREFUSED => e
+      nil
     end
 
     #
     # This *should* be unneccessary, but sometimes the page we get from the
     # window is different (ie. a different object) from our current @page
     # (Used by #wait_while and #wait_until)
-    # 
-    
+    #
+
     def refresh_page_from_window
       new_page = @page.getEnclosingWindow.getEnclosedPage
 
@@ -637,44 +868,20 @@ module Celerity
         Log.debug "unneccessary refresh"
       end
     end
-    
+
     #
-    # Render the current page on the viewer.
+    # Render the current page on the connected viewer.
     # @api private
-    # 
+    #
 
     def render
       @viewer.render_html(self.send(@render_type), url)
-    rescue DRb::DRbConnError, Errno::ECONNREFUSED => e
+    rescue Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EPIPE
       @viewer = DefaultViewer
     end
 
-    #
-    # Check if we have a viewer available on druby://127.0.0.1:6429
-    # @api private
-    # 
-
-    def find_viewer
-      viewer = DRbObject.new_with_uri("druby://127.0.0.1:6429")
-      if viewer.respond_to?(:render_html)
-        @viewer = viewer
-      else
-        @viewer = DefaultViewer
-      end
-    rescue DRb::DRbConnError, Errno::ECONNREFUSED
-      @viewer = DefaultViewer
-    end
-
-    # 
-    # Convert the given HtmlUnit object to a Celerity object
-    # 
-    
-    def element_from_dom_node(obj)
-      if element_class = Celerity::Util.htmlunit2celerity(obj.class)
-        element_class.new(self, :object, obj)
-      else
-        Element.new(self, :object, nil)
-      end
+    def listener
+      @listener ||= Celerity::Listener.new(@webclient)
     end
 
   end # Browser