polonium 0.1.0

data/CHANGES

@@ -0,0 +1,10 @@
+* Renamed to Polonium
+* Methods renamed to match Test::Unit assertions
+* Page and Element delegate to Driver [Paired with Jeff Whitmore]
+
+0.0.2
+* Supports multiple sessions by instantiating multiple SeleniumDrivers
+* Added SeleniumDriver which holds most of the polling methods
+
+0.0.1
+* Initial Release. More documentation to come.

data/README

@@ -0,0 +1,38 @@
+== Introduction
+
+Welcome to Polonium!
+
+This plugin is designed to let you use Polonium to write Selenium tests in Ruby, using a simple series of
+Rake tasks.
+
+== Installation
+
+The current version of this plugin can be found at: http://rubyforge.org/var/svn/pivotalrb/polonium/trunk
+
+You may install the plugin with the following command:
+
+  script/plugin install svn://rubyforge.org/var/svn/pivotalrb/polonium/trunk
+
+== Usage
+The polonium plugin assumes you have a test/selenium directory with a selenium_suite.rb file in
+it.  A sample selenium_suite.rb and selenium_helper.rb can be copied into your test/selenium directory.
+
+You'll get the following tasks:
+  - selenium:test - starts a Selenium RC server, runs selenium tests, and shuts the server down
+     when they're done
+
+and lower level tasks as well:
+  - selenium:server starts up a Selenium RC server
+  - selenium:test_with_server_started  runs Selenium tests off of an existing server
+
+== Future Enhancements
+
+There are a few things we'd like to improve, but we wanted to get this out now.  Check the tracker in the pivotal.rb RubyForge project for details.
+
+== License
+
+Polonium is distributed under the MIT license. Copyright © 2007 Pivotal Labs, Inc.
+
+== Contributing
+
+Contributions to this plugin are welcome.  Contributions should be accompanied by tests.  See http://pivotalrb.rubyforge.org for more details.

data/Rakefile

@@ -0,0 +1,68 @@
+require "rake"
+require 'rake/gempackagetask'
+require 'rake/contrib/rubyforgepublisher'
+require 'rake/clean'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc "Runs the Rspec suite"
+task(:default) do
+  run_suite
+end
+
+desc "Runs the Rspec suite"
+task(:spec) do
+  run_suite
+end
+
+desc "Copies the trunk to a tag with the name of the current release"
+task(:tag_release) do
+  tag_release
+end
+
+def run_suite
+  dir = File.dirname(__FILE__)
+  system("ruby #{dir}/spec/spec_suite.rb") || raise("Example Suite failed")
+end
+
+PKG_NAME = "polonium"
+PKG_VERSION = "0.1.0"
+PKG_FILES = FileList[
+  '[A-Z]*',
+  '*.rb',
+  'lib/**/*.rb',
+  'spec/**/*.rb'
+]
+
+spec = Gem::Specification.new do |s|
+  s.name = PKG_NAME
+  s.version = PKG_VERSION
+  s.summary = "Selenium RC with enhanced assertions that also runs your rails app."
+  s.test_files = "spec/spec_suite.rb"
+  s.description = s.summary
+
+  s.files = PKG_FILES.to_a
+  s.require_path = 'lib'
+
+  s.has_rdoc = true
+  s.extra_rdoc_files = [ "README", "CHANGES" ]
+  s.rdoc_options = ["--main", "README", "--inline-source", "--line-numbers"]
+
+  s.test_files = Dir.glob('spec/*_spec.rb')
+  s.require_path = 'lib'
+  s.author = "Pivotal Labs"
+  s.email = "opensource@pivotallabs.com"
+  s.homepage = "http://pivotallabs.com"
+  s.rubyforge_project = "pivotalrb"
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.need_zip = true
+  pkg.need_tar = true
+end
+
+def tag_release
+  dashed_version = PKG_VERSION.gsub('.', '-')
+  svn_user_prefix = "#{ENV['SVN_USER']}@" if ENV['SVN_USER']
+  `svn cp svn+ssh://#{svn_user_prefix}rubyforge.org/var/svn/pivotalrb/polonium/trunk svn+ssh://#{svn_user_prefix}rubyforge.org/var/svn/pivotalrb/polonium/tags/REL-#{dashed_version} -m 'Version #{PKG_VERSION}'`
+end

data/lib/polonium.rb

@@ -0,0 +1,28 @@
+require 'socket'
+require 'logger'
+require "stringio"
+
+require "active_record"
+
+require 'net/http'
+require 'test/unit'
+require 'test/unit/testresult'
+require 'test/unit/ui/testrunnermediator'
+
+require "selenium"
+require "polonium/extensions/module"
+require "polonium/extensions/testrunnermediator"
+require "polonium/wait_for"
+require "polonium/driver"
+require "polonium/server_runner"
+require "polonium/mongrel_selenium_server_runner"
+require "polonium/webrick_selenium_server_runner"
+require "polonium/dsl/selenium_dsl"
+require "polonium/dsl/test_unit_dsl"
+require "polonium/configuration"
+require "polonium/page"
+require "polonium/element"
+require "polonium/test_case"
+require "polonium/tasks/selenium_test_task"
+
+require 'webrick_server' if self.class.const_defined? :RAILS_ROOT

data/lib/polonium/configuration.rb

@@ -0,0 +1,271 @@
+module Polonium
+  # The configuration interface. This Configuration acts as a singleton to a SeleniumContext.
+  # You can access the Configuration object by calling
+  #   Polonium::Configuration.instance
+  class Configuration
+    module BrowserMode
+      Suite = "suite" unless const_defined? :Suite
+      Test = "test" unless const_defined? :Test
+    end
+    FIREFOX = "firefox" unless const_defined? :FIREFOX
+    IEXPLORE = "iexplore" unless const_defined? :IEXPLORE
+
+    class << self
+      # The instance of the Singleton Configuration. On its initial call, the initial configuration is set.
+      # The initial configuration is based on Environment variables and defaults.
+      # The environment variables are:
+      # * RAILS_ENV - The Rails environment (defaults: test)
+      # * selenium_server_host - The host name for the Selenium RC server (default: localhost)
+      # * selenium_server_port - The port for the Selenium RC server (default: 4444)
+      # * webrick_host - The host name that the application server will start under (default: localhost)
+      # * webrick_port - The port that the application server will start under (default: 4000)
+      # * app_server_engine - The type of server the application will be run with (webrick or mongrel)
+      # * internal_app_server_host - The host name for the Application server that the Browser will access (default: localhost)
+      # * internal_app_server_host - The port for the Application server that the Browser will access (default: 4000)
+      # * keep_browser_open_on_failure - If there is a failure in the test suite, keep the browser window open (default: false)
+      # * verify_remote_app_server_is_running - Raise an exception if the Application Server is not running (default: true)
+      def instance
+        return @instance if @instance
+        @instance = new
+        @instance.env = ENV
+
+        @instance.browser = FIREFOX
+        @instance.selenium_server_host = "localhost"     # address of selenium RC server (java)
+        @instance.selenium_server_port = 4444
+        @instance.app_server_engine = :webrick
+        @instance.internal_app_server_host = "0.0.0.0"    # internal address of app server (webrick or mongrel)
+        @instance.internal_app_server_port = 4000
+        @instance.external_app_server_host = "localhost"             # external address of app server (webrick or mongrel)
+        @instance.external_app_server_port = 4000
+        @instance.server_engine = :webrick
+        @instance.keep_browser_open_on_failure = false
+        @instance.browser_mode = BrowserMode::Suite
+        @instance.verify_remote_app_server_is_running = true
+
+        establish_environment
+        @instance
+      end
+      attr_writer :instance
+
+      private
+      def establish_environment
+        @instance.rails_env = env['RAILS_ENV'] if env.include?('RAILS_ENV')
+        @instance.rails_root = Object.const_get(:RAILS_ROOT) if Object.const_defined?(:RAILS_ROOT)
+        [
+          'selenium_server_host',
+          'selenium_server_port',
+          'internal_app_server_port',
+          'internal_app_server_host',
+          'app_server_engine',
+          'external_app_server_host',
+          'external_app_server_port'
+        ].each do |env_key|
+          if env.include?(env_key)
+            @instance.send("#{env_key}=", env[env_key])
+          end
+        end
+        [
+          'keep_browser_open_on_failure',
+          'verify_remote_app_server_is_running'
+        ].each do |env_key|
+          if env.include?(env_key)
+            @instance.send("#{env_key}=", env[env_key].to_s != false.to_s)
+          end
+        end
+        @instance.browser = env['browser'] if env.include?('browser')
+      end
+
+      def env
+        @instance.env
+      end
+    end
+
+        attr_accessor :configuration,
+                  :env,
+                  :rails_env,
+                  :rails_root,
+                  :browser,
+                  :driver,
+                  :browser_mode,
+                  :selenium_server_host,
+                  :selenium_server_port,
+                  :app_server_engine,
+                  :internal_app_server_host,
+                  :internal_app_server_port,
+                  :external_app_server_host,
+                  :external_app_server_port,
+                  :server_engine,
+                  :keep_browser_open_on_failure,
+                  :verify_remote_app_server_is_running,
+                  :app_server_initialization
+
+    def initialize
+      self.verify_remote_app_server_is_running = true
+      @after_driver_started_listeners = []
+      @app_server_initialization = proc {}
+      @failure_has_occurred = false
+    end
+
+    # A callback hook that gets run after the Selenese Interpreter is started.
+    def after_driver_started(&block)
+      @after_driver_started_listeners << block
+    end
+
+    # Notify all after_driver_started callbacks.
+    def notify_after_driver_started(driver)
+      for listener in @after_driver_started_listeners
+        listener.call(driver)
+      end
+    end
+
+    # The browser formatted for the Selenese driver.
+    def formatted_browser
+      return "*#{@browser}"
+    end
+
+    # Has a failure occurred in the tests?
+    def failure_has_occurred?
+      @failure_has_occurred = true
+    end
+
+    # The http host name and port to be entered into the browser address bar
+    def browser_url
+      "http://#{external_app_server_host}:#{external_app_server_port}"
+    end
+
+    # The root directory (public) of the Rails application
+    def server_root
+      File.expand_path("#{rails_root}/public/")
+    end
+
+    # Sets the Test Suite to open a new browser instance for each TestCase
+    def test_browser_mode
+      @browser_mode = Configuration::BrowserMode::Test
+    end
+
+    # Are we going to open a new browser instance for each TestCase?
+    def test_browser_mode?
+      @browser_mode == Configuration::BrowserMode::Test
+    end
+
+    # Sets the Test Suite to use one browser instance
+    def suite_browser_mode
+      @browser_mode = Configuration::BrowserMode::Suite
+    end
+
+    # Does the Test Suite to use one browser instance?
+    def suite_browser_mode?
+      @browser_mode == Configuration::BrowserMode::Suite
+    end
+
+    # The Driver object, which sublcasses the Driver provided by the Selenium RC (http://openqa.org/selenium-rc/) project.
+    def driver
+      return nil unless suite_browser_mode?
+      @driver ||= create_and_initialize_driver
+    end
+
+    def stop_driver_if_necessary(suite_passed) # nodoc
+      failure_has_occurred unless suite_passed
+      if @driver && stop_driver?(suite_passed)
+        @driver.stop
+        @driver = nil
+      end
+    end
+
+    def stop_driver?(passed) # nodoc
+      return true if passed
+      return !keep_browser_open_on_failure
+    end
+
+    def create_and_initialize_driver # nodoc
+      driver = create_driver
+      driver.start
+      notify_after_driver_started(driver)
+      driver
+    end
+
+    def create_driver # nodoc
+      return ::Polonium::Driver.new(
+        selenium_server_host,
+        selenium_server_port,
+        formatted_browser,
+        browser_url,
+        15000
+      )
+    end
+
+    def create_server_runner # nodoc
+      case @app_server_engine.to_sym
+      when :mongrel
+        create_mongrel_runner
+      when :webrick
+        create_webrick_runner
+      else
+        raise "Invalid server type: #{selenium_configuration.app_server_type}"
+      end
+    end
+
+    def create_webrick_runner # nodoc
+      require 'webrick_server'
+      runner = WebrickSeleniumServerRunner.new
+      runner.configuration = self
+      runner.thread_class = Thread
+      runner.socket = Socket
+      runner.dispatch_servlet = DispatchServlet
+      runner.environment_path = File.expand_path("#{@rails_root}/config/environment")
+      runner
+    end
+
+    def create_webrick_server # nodoc
+      WEBrick::HTTPServer.new({
+        :Port => @internal_app_server_port,
+        :BindAddress => @internal_app_server_host,
+        :ServerType  => WEBrick::SimpleServer,
+        :MimeTypes => WEBrick::HTTPUtils::DefaultMimeTypes,
+        :Logger => new_logger,
+        :AccessLog => []
+      })
+    end
+
+    def new_logger
+      Logger.new(StringIO.new)
+    end
+
+    def create_mongrel_runner # nodoc
+      runner = MongrelSeleniumServerRunner.new
+      runner.configuration = self
+      runner.thread_class = Thread
+      runner
+    end
+
+    def create_mongrel_configurator # nodoc
+      dir = File.dirname(__FILE__)
+      require 'mongrel/rails'
+      settings = {
+        :host => internal_app_server_host,
+        :port => internal_app_server_port,
+        :cwd => @rails_root,
+        :log_file => "#{@rails_root}/log/mongrel.log",
+        :pid_file => "#{@rails_root}/log/mongrel.pid",
+        :environment => @rails_env,
+        :docroot => "#{@rails_root}/public",
+        :mime_map => nil,
+        :daemon => false,
+        :debug => false,
+        :includes => ["mongrel"],
+        :config_script => nil
+      }
+
+      configurator = Mongrel::Rails::RailsConfigurator.new(settings) do
+        log "Starting Mongrel in #{defaults[:environment]} mode at #{defaults[:host]}:#{defaults[:port]}"
+      end
+      configurator
+    end
+
+    protected
+    # Sets the failure state to true
+    def failure_has_occurred
+      @failure_has_occurred = true
+    end
+  end
+end

data/lib/polonium/driver.rb

@@ -0,0 +1,155 @@
+module Polonium
+  class Driver < ::Selenium::SeleniumDriver
+    include WaitFor
+    attr_reader :server_host, :server_port
+
+    def browser_start_command
+      @browserStartCommand
+    end
+
+    def browser_url
+      @browserURL
+    end
+
+    def timeout_in_milliseconds
+      @timeout
+    end
+
+    def insert_javascript_file(uri)
+      js = <<-USEREXTENSIONS
+      var headTag = document.getElementsByTagName("head").item(0);
+      var scriptTag = document.createElement("script");
+      scriptTag.src = "#{uri}";
+      headTag.appendChild( scriptTag );
+      USEREXTENSIONS
+      get_eval(js)
+    end
+
+    def insert_user_extensions
+      insert_javascript_file("/selenium/user-extensions.js")
+    end
+
+    def element(locator)
+      Element.new(self, locator)
+    end
+
+    def page
+      Page.new(self)
+    end
+
+    #--------- Commands
+    alias_method :confirm, :get_confirmation
+
+    # Type text into a page element
+    def type(locator, value)
+      wait_for_is_element_present(locator)
+      super
+    end
+
+    # Reload the current page that the browser is on.
+    def reload
+      get_eval("selenium.browserbot.getCurrentWindow().location.reload()")
+    end
+
+    def click(locator)
+      wait_for_is_element_present(locator)
+      super
+    end
+    alias_method :wait_for_and_click, :click
+
+    def select(select_locator, option_locator)
+      wait_for_is_element_present(select_locator)
+      super
+    end
+    
+    # Click a link and wait for the page to load.
+    def click_and_wait(locator, wait_for = default_timeout)
+      click locator
+      wait_for_page_to_load(wait_for)
+    end
+    alias_method :click_and_wait_for_page_to_load, :click_and_wait
+
+    # Click the back button and wait for the page to load.
+    def go_back_and_wait
+      go_back
+      wait_for_page_to_load
+    end
+
+    # Open the home page of the Application and wait for the page to load.
+    def open(url)
+      super
+      wait_for_page_to_load
+    end
+    alias_method :open_and_wait, :open
+
+    # Get the inner html of the located element.
+    def get_inner_html(locator)
+      get_eval(inner_html_js(locator))
+    end
+
+    # Does the element at locator contain the text?
+    def element_contains_text(locator, text)
+      is_element_present(locator) && element(locator).contains?(text)
+    end
+
+    # Does the element at locator not contain the text?
+    def element_does_not_contain_text(locator, text)
+      return true unless is_element_present(locator)
+      return !element(locator).contains?(text)
+    end
+
+    #----- Waiting for conditions
+    def wait_for_is_element_present(locator, params={})
+      params = {
+        :message => "Expected element '#{locator}' to be present, but it was not"
+      }.merge(params)
+      wait_for(params) do
+        is_element_present(locator)
+      end
+    end
+
+    def wait_for_is_element_not_present(locator, params={})
+      params = {
+        :message => "Expected element '#{locator}' to be absent, but it was not"
+      }.merge(params)
+      wait_for(:message => params[:message]) do
+        !is_element_present(locator)
+      end
+    end
+
+    def wait_for_page_to_load(timeout=default_timeout)
+      super
+      if get_title.include?("Exception caught")
+        flunk "We got a new page, but it was an application exception page.\n\n#{get_html_source}"
+      end
+    end
+
+    def wait_for_element_to_contain(locator, text, message=nil, timeout=default_wait_for_time)
+      wait_for(:message => message, :timeout => timeout) do
+        element_contains_text(locator, text)
+      end
+    end
+    alias_method :wait_for_element_to_contain_text, :wait_for_element_to_contain
+
+    # Open the log window on the browser. This is useful to diagnose issues with Selenium Core.
+    def show_log(log_level = "debug")
+      get_eval "LOG.setLogLevelThreshold('#{log_level}')"
+    end
+
+    # Slow down each Selenese step after this method is called.
+    def slow_mode
+      get_eval "slowMode = true"
+      get_eval 'window.document.getElementsByName("FASTMODE")[0].checked = true'
+    end
+
+    # Speeds up each Selenese step to normal speed after this method is called.
+    def fast_mode
+      get_eval "slowMode = false"
+      get_eval 'window.document.getElementsByName("FASTMODE")[0].checked = false'
+    end
+
+    def inner_html_js(locator)
+      %Q|this.page().findElement("#{locator}").innerHTML|
+    end
+  end
+end