steam 0.0.2

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2009 Sven Fuchs <svenfuchs@artweb-design.de>
+
+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.textile

@@ -0,0 +1,91 @@
+<a name="readme"></a>
+
+h1. Steam
+
+Steam is a headless integration testing tool driving "HtmlUnit":http://htmlunit.sourceforge.net to enable testing JavaScript-driven web sites. In that it is similar to "Culerity":http://github.com/langalex/culerity which drives "Celerity":http://github.com/jarib/celerity (which also drives "HtmlUnit":http://htmlunit.sourceforge.net). See below for a "comparsion":#comparsion.
+
+<a name="installation"></a>
+
+h2. Installation
+
+Steam currently has the following dependencies:
+
+* Working Java Runtime
+* HtmlUnit (jar files)
+* RJB and Locator gems
+
+Installing Steam as as a gem will automatically install the required RJB and Locator gems:
+
+pre. $ gem install steam
+
+To install HtmlUnit you can download it from "Sourceforge":http://sourceforge.net/projects/htmlunit/files. 
+
+You then need to add HtmlUnit to your Java classpath. The following ways should both work:
+
+<pre># anywhere during startup, e.g. in features/support/env.rb
+ENV['CLASSPATH'] = Dir["path/to/your/htmlunit/*.jar"].join(':')
+
+# after steam has been added to the load path, e.g. in features/support/env.rb
+Steam.config[:html_unit][:java_path] = 'path/to/your/htmlunit'</pre>
+
+If you're on Mac OS X then you also need to export the JAVA_HOME variable for RJB. See here for two solutions: "Installing RJB on Mac OS X":http://www.elctech.com/articles/sudo-java_home-and-mac-os-x. The visudo way worked for us. Don't forget to add yourself to the sudoers file, though.
+
+
+<a name="configuration"></a>
+
+h2. Configuration
+
+You should not need to configure anything. If you do need though have a look at "Steam.config":http://github.com/svenfuchs/steam/blob/master/lib/steam.rb
+
+E.g. in order to tweak the Java load params you can
+
+pre. Steam.config[:java_load_params] = "-Xmx2048M"
+
+
+<a name="usage"></a>
+
+h2. Usage
+
+You can use Steam by itself as well as with Cucumber. You can find an example for a Cucumber setup in examples/cucumber/env.rb.
+
+Steam is widely compatible with Webrat - many actions are implemented and take the same or very similar parameters as their Webrat equivalent. You even might be able to use the default webrat_steps.rb that ships with Cucumber, *but his file is meant as an example and might be out of date.*
+
+
+<a name="demo"></a>
+
+h2. Demo
+
+You can find a demo application here: "http://github.com/clemens/steam-demo":http://github.com/clemens/steam-demo
+
+
+<a name="comparsion"></a>
+
+h2. Comparsion to others
+
+Steam's advantages over Culerity/Celerity:
+
+* runs in Ruby MRI and does not require an entire JRuby environment.
+* Steam can have the HtmlUnit browser running in the same stack as your tests, thus making the whole thing less complex and hard to debug
+* Steam does not build on Celerity which is a quite heavy-weight Ruby wrapper around HtmlUnit adding a lot of unnecessary code
+* Steam uses "Locator":http://github.com/svenfuchs/locator
+
+Culerity/Celerity's advantages over Steam:
+
+* RJB can't resolve the mismatch of Ruby vs Java threads which makes fancy setups impossible to solve
+* Celerity implements a *lot* of stuff, maybe it contains something you need (e.g. maybe you want to test pop-down windows opening in the background?)
+* Steam still is in its infancy
+
+
+<a name="acknowledgements"></a>
+
+h2. Acknowledgements
+
+Kudos to "Alexander Lang":http://github.com/langalex for writing "Culerity":http://github.com/langalex/culerity which pioneered full-stack AJAX-enabled integration testing in Rails.
+
+
+<a name="developers"></a>
+
+h2. Developers
+
+* "Sven Fuchs":http://github.com/svenfuchs
+* "Clemens Kofler"::http://github.com/clemens

data/Rakefile

@@ -0,0 +1,23 @@
+$: << File.expand_path('../lib', __FILE__)
+
+require 'rake/testtask'
+require 'steam/version'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |s|
+    s.name = 'steam'
+    s.version = Steam::VERSION
+    s.summary = 'Headless integration testing w/ HtmlUnit: enables testing JavaScript-driven web sites '
+    s.email = 'svenfuchs@artweb-design.de'
+    s.homepage = 'http://github.com/svenfuchs/steam'
+    s.description = 'Steam is a headless integration testing tool driving HtmlUnit to enable testing JavaScript-driven web sites.'
+    s.authors = ['Sven Fuchs', 'Clemens Kofler']
+    s.files =  FileList['[A-Z]*', 'lib/steam.rb', 'lib/{core_ext,steam}/**/*']
+
+    s.add_dependency 'rjb', '>= 1.2.0'
+    s.add_dependency 'locator', '>= 0.0.4'
+  end
+rescue LoadError
+  puts 'Jeweler, or one of its dependencies, is not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com'
+end

data/TODO

@@ -0,0 +1,7 @@
+http://htmlunit.sourceforge.net/logging.html
+
+http://htmlunit.sourceforge.net/faq.html#MemoryLeak
+HtmlUnit appears to be leaking memory; what's the deal?
+Make sure (a) that you are using the latest version of HtmlUnit, and (b) that you are calling WebClient.closeAllWindows() when you are finished with your WebClient instance.
+
+

data/lib/core_ext/ruby/array/flatten_once.rb

@@ -0,0 +1,9 @@
+class Array
+  def flatten_once
+    result = []
+    for element in self # a little faster than each
+      result.push(*element)
+    end
+    result
+  end
+end unless Array.method_defined?(:flatten_once)

data/lib/core_ext/ruby/hash/except.rb

@@ -0,0 +1,11 @@
+class Hash
+  def except!(*keys)
+    keys.map! { |key| convert_key(key) } if respond_to?(:convert_key)
+    keys.each { |key| delete(key) }
+    self
+  end
+  
+  def except(*keys)
+    dup.except!(*keys)
+  end
+end unless Hash.method_defined?(:slice)

data/lib/core_ext/ruby/hash/slice.rb

@@ -0,0 +1,14 @@
+class Hash
+  def slice!(*keys)
+    omit = slice(*self.keys - keys)
+    hash = slice(*keys)
+    replace(hash)
+    omit
+  end
+
+  def slice(*keys)
+    hash = self.class.new
+    keys.each { |k| hash[k] = self[k] if has_key?(k) }
+    hash
+  end
+end unless Hash.method_defined?(:slice)

data/lib/core_ext/ruby/kernel/silence_warnings.rb

@@ -0,0 +1,8 @@
+module Kernel
+  def silence_warnings
+    old_verbose, $VERBOSE = $VERBOSE, nil
+    yield
+  ensure
+    $VERBOSE = old_verbose
+  end
+end unless Kernel.method_defined?(:silence_warnings)

data/lib/core_ext/ruby/process/daemon.rb

@@ -0,0 +1,23 @@
+module Process
+  def self.daemon(nochdir = nil, noclose = nil)
+    exit if fork                     # Parent exits, child continues.
+    Process.setsid                   # Become session leader.
+    exit if fork                     # Zap session leader. See [1].
+
+    unless nochdir
+      Dir.chdir "/"                  # Release old working directory.
+    end
+
+    File.umask 0000                  # Ensure sensible umask. Adjust as needed.
+
+    unless noclose
+      STDIN.reopen "/dev/null"       # Free file descriptors and
+      STDOUT.reopen "/dev/null", "a" # point them somewhere sensible.
+      STDERR.reopen '/dev/null', 'a'
+    end
+
+    trap("TERM") { exit }
+
+    return 0
+  end unless respond_to?(:daemon)
+end

data/lib/core_ext/ruby/string/camelize.rb

@@ -0,0 +1,5 @@
+class String
+  def camelize
+    split(/[^a-z0-9]/i).map { |w| w.capitalize }.join
+  end
+end unless String.method_defined?(:camelize)

data/lib/core_ext/ruby/string/underscore.rb

@@ -0,0 +1,5 @@
+class String
+  def underscore
+    self[0, 1].downcase + self[1..-1].gsub(/[A-Z]/) { |c| "_#{c.downcase}" }
+  end
+end unless String.method_defined?(:underscore)

data/lib/steam.rb

@@ -0,0 +1,43 @@
+require 'rack'
+
+module Steam
+  autoload :Browser,    'steam/browser'
+  autoload :Connection, 'steam/connection'
+  autoload :Java,       'steam/java'
+  autoload :Process,    'steam/process'
+  autoload :Request,    'steam/request'
+  autoload :Response,   'steam/response'
+  autoload :Session,    'steam/session'
+
+  class << self
+    def config
+      @@config ||= {
+        :request_url       => 'http://localhost',
+        :server_name       => 'localhost',
+        :server_port       => '3000',
+        :url_scheme        => 'http',
+        :charset           => 'utf-8',
+        :java_load_params  => '-Xmx1024M',
+        :drb_uri           => 'druby://127.0.0.1:9000',
+        :html_unit => {
+          :java_path         => File.expand_path("../../vendor/htmlunit-2.6/", __FILE__),
+          :browser_version   => :FIREFOX_3,
+          :css               => true,
+          :javascript        => true,
+          :resynchronize     => true,
+          :js_timeout        => 5000,
+          :log_level         => :warning,
+          :log_incorrectness => false,
+          :on_error_status   => nil, # set to :raise to raise an exception on error status, :print to print content
+          :on_script_error   => nil  # set to :raise to raise an exception on javascript exceptions
+        }
+      }
+    end
+  end
+
+  class ElementNotFound < StandardError
+    def initialize(*args)
+      super "could not find element: #{args.map { |arg| arg.inspect }.join(', ') }"
+    end
+  end
+end

data/lib/steam/browser.rb

@@ -0,0 +1,24 @@
+# We currently only implement HtmlUnit as a browser. Maybe at some point
+# Webdriver might be an interesting alternative.
+
+require 'core_ext/ruby/string/camelize'
+
+module Steam
+  module Browser
+    autoload :HtmlUnit, 'steam/browser/html_unit'
+    
+    class << self
+      def create(*args)
+        options    = args.last.is_a?(Hash) ? args.pop : {}
+        type       = args.shift if args.first.is_a?(Symbol)
+        connection = args.pop
+        
+        type ||= :html_unit
+        type = const_get(type.to_s.camelize)
+        type = type.const_get('Drb') if options[:daemon]
+
+        type.new(connection, :daemon => true)
+      end
+    end
+  end
+end

data/lib/steam/browser/html_unit.rb

@@ -0,0 +1,87 @@
+# Browser implementation using HtmlUnit. Steam::Session delegates here, so this
+# interface is available in your Cucumber environment. Also see HtmlUnit::Actions
+# which is included here.
+
+require 'locator'
+require 'core_ext/ruby/kernel/silence_warnings'
+
+module Steam
+  module Browser
+    class HtmlUnit
+      autoload :Actions,     'steam/browser/html_unit/actions'
+      autoload :Client,      'steam/browser/html_unit/client'
+      autoload :Drb,         'steam/browser/html_unit/drb'
+      autoload :Forker,      'steam/browser/html_unit/forker'
+      autoload :Connection,  'steam/browser/html_unit/connection'
+      autoload :Matchers,    'steam/browser/html_unit/matchers'
+      autoload :Page,        'steam/browser/html_unit/page'
+      autoload :WebResponse, 'steam/browser/html_unit/web_response'
+
+      include Actions # Matchers
+
+      attr_accessor :client, :page, :connection, :request, :response
+
+      def initialize(*args)
+        @client = Client.new(*args)
+      end
+
+      def close
+        @client.closeAllWindows
+      end
+
+      def request(url)
+        call Request.env_for(url)
+      end
+      alias :visit :request
+
+      def call(env)
+        respond_to do
+          @request = Rack::Request.new(env)
+          client.request(@request.url)
+        end.to_a
+      end
+
+      def execute(javascript)
+        page.execute(javascript) # FIXME does execute return a page so we need to respond?
+      end
+
+      def locate(*args, &block)
+        Locator.locate(dom, *args, &block) || raise(ElementNotFound.new(*args))
+      end
+
+      def locate_in_browser(*args, &block)
+        if args.first.respond_to?(:_classname)     # native HtmlUnit element
+          args.first
+        elsif args.first.respond_to?(:xpath)       # Locator element
+          silence_warnings { page.getFirstByXPath(args.first.xpath) }
+        else
+          locate_in_browser(locate(*args, &block)) # something else
+        end
+      end
+
+      def within(*args, &block)
+        Locator.within(*args, &block)
+      end
+
+      protected
+
+        def respond_to
+          result = yield || raise('Block did not yield a dom.gargoylesoftware.htmlunit.html.HtmlPage.')
+          @page = Page.new(result)
+          client.wait_for_javascript(Steam.config[:html_unit][:js_timeout])
+          @response = Response.new(*page.to_a)
+        end
+
+        def dom
+          case Locator::Dom.adapter.name # yuck
+          when /Nokogiri/
+            response.body
+          when /Htmlunit/
+            @page.page
+          else
+            raise 'incompatible Locator::Dom adapter'
+          end
+        end
+    end
+  end
+end

data/lib/steam/browser/html_unit/actions.rb

@@ -0,0 +1,176 @@
+# Convenience dsl for executing typical actions on the web browser and current
+# page. Mimicks the well-known Webrat API but adds stuff like drag/drop support.
+
+require 'core_ext/ruby/hash/slice'
+
+module Steam
+  module Browser
+    class HtmlUnit
+      module Actions
+        def click_on(*args)
+          respond_to { locate_in_browser(*args).click }
+        end
+
+        def click_link(element, options = {})
+          respond_to { locate_in_browser(:link, element, options).click }
+        end
+        
+        def click_button(element, options = {})
+          respond_to { locate_in_browser(:button, element, options).click }
+        end
+        
+        def click_area(element, options = {})
+          respond_to { locate_in_browser(:area, element, options).click }
+        end
+        
+        def fill_in(element, options = {})
+          respond_to do
+            value = options.delete(:with)
+            element = locate_in_browser(:field, element, options)
+            result = element.setText(value) rescue element.setValueAttribute(value)
+            # TODO - submit a bug: element.setText returns nil, textarea.setValueAttribute returns a page
+            result || page
+          end
+        end
+        
+        def check(element, options = {})
+          respond_to { locate_in_browser(:check_box, element, options).setChecked(true) }
+        end
+        
+        def uncheck(element, options = {})
+          respond_to { locate_in_browser(:check_box, element, options).setChecked(false) }
+        end
+        
+        def choose(element, options = {})
+          respond_to { locate_in_browser(:radio_button, element, options).setChecked(true) }
+        end
+        
+        def select(element, options = {})
+          options.update(:within => [:select, options.delete(:from)])
+          respond_to { locate_in_browser(:select_option, element, options).setSelected(true) }
+        end
+        
+        def set_hidden_field(element, options = {})
+          respond_to do
+            value = options.delete(:to)
+            locate_in_browser(:hidden_field, element, options).setValueAttribute(value)
+          end
+        end
+        
+        # TODO implement a way to supply content_type
+        def attach_file(element, path, options = {})
+          fill_in(element, options.merge(:with => path))
+        end
+        
+        def submit_form(element, options = {})
+          respond_to do
+            scope = [:form, element, options]
+            locate_in_browser(:input, :type => 'submit', :within => scope).click
+          end
+        end
+        
+        def drag_and_drop(element, options = {})
+          drag(element, options)
+          drop
+        end
+        
+        def drag(element, options = {})
+          respond_to do
+            target  = extract_drop_target!(options, [:to, :onto, :over, :target])
+            element = locate_in_browser(element, options)
+            if target
+              element.mouseDown
+              @_drop_target = locate_in_browser(target)
+              @_drop_target.mouseMove
+            else
+              element.mouseDown
+            end
+          end
+        end
+        
+        def drop(element = nil, options = {})
+          respond_to do
+            element = @_drop_target || locate_in_browser(element, options)
+            element.mouseMove unless @_drop_target
+            @_drop_target = nil
+            element.mouseUp
+          end
+        end
+        
+        def hover(element, options = {})
+          respond_to { locate_in_browser(element, options).mouseOver }
+        end
+        
+        def blur(element, options = {})
+          respond_to do
+            locate_in_browser(element, options).blur
+            @page # blur seems to return nil
+          end
+        end
+        
+        def focus(element, options = {})
+          respond_to do
+            locate_in_browser(element, options).focus
+            @page # focus seems to return nil
+          end
+        end
+        
+        def double_click(element, options = {})
+          respond_to { locate_in_browser(element, options).dblClick }
+        end
+        
+        # Rails specific respond_tos
+        DATE_TIME_CODE = {
+          :year   => '1i',
+          :month  => '2i',
+          :day    => '3i',
+          :hour   => '4i',
+          :minute => '5i',
+          :second => '6i'
+        }
+        
+        def select_date(date, options = {})
+          date = date.respond_to?(:strftime) ? date : Date.parse(date)
+          prefix = locate_id_prefix(options)
+        
+          # FIXME .to_s chould be done somewhere inside the locator
+          select(date.year.to_s,      :from => "#{prefix}_#{DATE_TIME_CODE[:year]}")
+          select(date.strftime('%B'), :from => "#{prefix}_#{DATE_TIME_CODE[:month]}")
+          select(date.day.to_s,       :from => "#{prefix}_#{DATE_TIME_CODE[:day]}")
+        end
+        
+        def select_datetime(datetime, options = {})
+          select_date(datetime)
+          select_time(datetime)
+        end
+        
+        def select_time(time, options = {})
+          time = time.respond_to?(:strftime) ? time : DateTime.parse(time)
+          prefix = locate_id_prefix(options)
+        
+          select(time.hour.to_s.rjust(2,'0'), :from => "#{prefix}_#{DATE_TIME_CODE[:hour]}")
+          select(time.min.to_s.rjust(2,'0'),  :from => "#{prefix}_#{DATE_TIME_CODE[:minute]}")
+          # second?
+        end
+        
+        protected
+        
+          # inspired by Webrat
+          def locate_id_prefix(options)
+            options[:id_prefix] ? options[:id_prefix] : locate_id_prefix_label(options).attribute('for')
+          end
+          
+          def locate_id_prefix_label(options)
+            locate_in_browser(:label, options[:from]) rescue locate_in_browser(:label, :for => options[:from])
+          end
+        
+          def extract_drop_target!(targets, keys)
+            rest   = targets.slice!(*keys)
+            target = targets.values.compact.first
+            targets.replace(rest)
+            target
+          end
+      end
+    end
+  end
+end