polonium 0.1.1 → 0.2.0

data/CHANGES

@@ -1,3 +1,10 @@
+0.2.0
+* Added ExternalServerRunner.
+* Removed mysql specific setup logic.
+
+0.1.1
+* Rspec support
+
 0.1.0
 * Renamed to Polonium
 * Methods renamed to match Test::Unit assertions

data/README

@@ -2,10 +2,12 @@
 
 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.
+Polonium is a wrapper for Selenium that lets your write cleaner Selenium tests
+in ruby, and run them with a simple set of rake tasks.
 
 == Installation
+Polonium depends on the Selenium gem. To install this dependency, run:
+  sudo gem install Selenium
 
 The current version of this plugin can be found at: http://rubyforge.org/var/svn/pivotalrb/polonium/trunk
 
@@ -13,17 +15,30 @@ 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 may also use Polonium as a gem:
 
-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
+  sudo gem install polonium
 
-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
+== Getting Started
+The polonium plugin rake tasks assumes you have a test/selenium directory with a selenium_suite.rb file in
+it.  To get started, copy examples/selenium_suite.rb, examples/selenium_helper.rb, and examples/example_test.rb
+into your test/selenium directory.
+
+To start the selenium server, run the command:
+  selenium
+The selenium command was installed with the Selenium Gem.
+
+You can run Polonium tests using rspec or test/unit through the rake tasks.
+  rake selenium:test
+  # or
+  rake selenium:spec
+
+[TODO: this doesn't seem to work on a vanilla project that is using Polonium as a gem & the code in
+the examples directory; @selenium_driver is nil.  Is there an extra step necessary to get this working?]
+
+You can also run individual tests straight ruby:
+
+ruby test/selenium/any_selenium_test.rb
 
 == Future Enhancements
 
@@ -31,7 +46,7 @@ There are a few things we'd like to improve, but we wanted to get this out now.
 
 == License
 
-Polonium is distributed under the MIT license. Copyright © 2007 Pivotal Labs, Inc.
+Polonium is distributed under the MIT license. Copyright © 2007-2008 Pivotal Labs, Inc.
 
 == Contributing
 

data/Rakefile

@@ -26,7 +26,7 @@ def run_suite
 end
 
 PKG_NAME = "polonium"
-PKG_VERSION = "0.1.1"
+PKG_VERSION = "0.2.0"
 PKG_FILES = FileList[
   '[A-Z]*',
   '*.rb',
@@ -37,7 +37,7 @@ PKG_FILES = FileList[
 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.summary = "Selenium RC with Rails integration and enhanced assertions."
   s.test_files = "spec/spec_suite.rb"
   s.description = s.summary
 

data/init.rb

@@ -0,0 +1,9 @@
+# Placeholder to satisfy Rails.
+#
+# Do NOT add any require statements to this file. Doing
+# so will cause Rails to load this plugin all of the time.
+#
+# Running 'ruby script/generate rspec' will
+# generate spec/spec_helper.rb, which includes the necessary
+# require statements and configuration. This file should
+# be required by all of your spec files.

data/lib/polonium/adapters/rspec.rb

@@ -1,21 +1,27 @@
 class Spec::Runner::Options
-  attr_accessor :selenium_configuration, :selenium_app_runner
-
-  def run_examples_with_selenium_runner(*args)
-    success = run_examples_without_selenium_runner(*args)
-    selenium_app_runner.stop
-    selenium_configuration.stop_driver_if_necessary(success)
+  def stop_selenium(success)
+    Polonium::Configuration.instance.app_server_runner.stop
+    Polonium::Configuration.instance.stop_driver_if_necessary(success)
     success
   end
-  alias_method_chain :run_examples, :selenium_runner
-end
 
-rspec_options.selenium_configuration = Polonium::Configuration.instance
-rspec_options.selenium_app_runner = nil
+  if instance_methods.include?('after_suite_parts')
+    Spec::Example::ExampleGroup.after(:suite) do |success|
+      rspec_options.stop_selenium success
+    end
+  else
+    def run_examples_with_selenium_runner(*args)
+      success = run_examples_without_selenium_runner(*args)
+      stop_selenium success
+      success
+    end
+    alias_method_chain :run_examples, :selenium_runner
+  end
+end
 
 Spec::Example::ExampleMethods.before(:all) do
-  unless rspec_options.selenium_app_runner
-    rspec_options.selenium_app_runner = rspec_options.selenium_configuration.create_server_runner
-    rspec_options.selenium_app_runner.start
+  unless Polonium::Configuration.instance.app_server_runner
+    app_server_runner = Polonium::Configuration.instance.create_app_server_runner
+    app_server_runner.start
   end
 end

data/lib/polonium/adapters/test_unit.rb

@@ -11,7 +11,7 @@ class Test::Unit::UI::TestRunnerMediator
   protected
   def start_app_server
     @selenium_driver = Polonium::Configuration.instance
-    @app_runner = @selenium_driver.create_server_runner
+    @app_runner = @selenium_driver.create_app_server_runner
     @app_runner.start
   end
 

data/lib/polonium/configuration.rb

@@ -9,6 +9,11 @@ module Polonium
     end
     FIREFOX = "firefox" unless const_defined? :FIREFOX
     IEXPLORE = "iexplore" unless const_defined? :IEXPLORE
+    SERVER_RUNNERS = {
+      :webrick => ServerRunners::WebrickServerRunner,
+      :mongrel => ServerRunners::MongrelServerRunner,
+      :external => ServerRunners::ExternalServerRunner
+    } unless const_defined? :SERVER_RUNNERS
 
     class << self
       # The instance of the Singleton Configuration. On its initial call, the initial configuration is set.
@@ -17,33 +22,34 @@ module Polonium
       # * 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)
+      # * external_app_server_host - The host name that the Rails application server will start under (default: localhost)
+      # * external_app_server_port - The port that the Rails 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
+        @instance ||= begin
+          @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
       end
       attr_writer :instance
 
@@ -81,7 +87,6 @@ module Polonium
     end
 
     attr_accessor(
-      :configuration,
       :env,
       :rails_env,
       :rails_root,
@@ -105,7 +110,6 @@ module Polonium
       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.
@@ -125,11 +129,6 @@ module Polonium
       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}"
@@ -167,7 +166,6 @@ module Polonium
     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
@@ -196,78 +194,15 @@ module Polonium
       )
     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 => []
-      })
+    attr_reader :app_server_runner
+    def create_app_server_runner #:nodoc:
+      app_server_type = SERVER_RUNNERS[@app_server_engine.to_sym]
+      raise "Invalid server engine #{@app_server_engine}" unless app_server_type
+      @app_server_runner = app_server_type.new(self)
     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

@@ -3,6 +3,11 @@ module Polonium
     include WaitFor
     attr_reader :server_host, :server_port
 
+    # The Configuration object.
+    def configuration
+      Configuration.instance
+    end    
+
     def browser_start_command
       @browserStartCommand
     end
@@ -37,48 +42,51 @@ module Polonium
       Page.new(self)
     end
 
+    # Open the home page of the Application and wait for the page to load.
+    def open_home_page
+      open(configuration.browser_url)
+    end
+
     #--------- Commands
     alias_method :confirm, :get_confirmation
 
     # Type text into a page element
     def type(locator, value)
-      wait_for_is_element_present(locator)
+      assert_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)
+      assert_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)
+      assert_element_present select_locator
       super
     end
-    
+
+    # Reload the current page that the browser is on.
+    def reload
+      get_eval("selenium.browserbot.getCurrentWindow().location.reload()")
+    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)
+      assert_page_loaded(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
+      assert_page_loaded
     end
 
     # Open the home page of the Application and wait for the page to load.
     def open(url)
       super
-      wait_for_page_to_load
+      assert_page_loaded
     end
     alias_method :open_and_wait, :open
 
@@ -87,11 +95,6 @@ module Polonium
       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)
@@ -99,7 +102,7 @@ module Polonium
     end
 
     #----- Waiting for conditions
-    def wait_for_is_element_present(locator, params={})
+    def assert_element_present(locator, params={})
       params = {
         :message => "Expected element '#{locator}' to be present, but it was not"
       }.merge(params)
@@ -108,7 +111,7 @@ module Polonium
       end
     end
 
-    def wait_for_is_element_not_present(locator, params={})
+    def assert_element_not_present(locator, params={})
       params = {
         :message => "Expected element '#{locator}' to be absent, but it was not"
       }.merge(params)
@@ -123,13 +126,7 @@ module Polonium
         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
+    alias_method :assert_page_loaded, :wait_for_page_to_load
 
     # Open the log window on the browser. This is useful to diagnose issues with Selenium Core.
     def show_log(log_level = "debug")

data/lib/polonium/dsl/selenium_dsl.rb

@@ -1,10 +1,66 @@
 module Polonium
   module SeleniumDsl
-    # The Configuration object.
-    def configuration
-      @configuration ||= Configuration.instance
+    class << self
+      def page_assertion(name)
+        module_eval(
+          "def assert_#{name}(value, params={})\n" +
+          "  page.assert_#{name}(value, params)\n" +
+          "end",
+          __FILE__,
+          __LINE__ - 4
+        )
+      end
+
+      def element_assertion(name)
+        module_eval(
+          "def assert_#{name}(locator, *args)\n" +
+          "  element(locator).assert_#{name}(*args)\n" +
+          "end",
+          __FILE__,
+          __LINE__ - 4
+        )
+      end
+    end
+    
+    page_assertion :title
+    page_assertion :text_present
+    page_assertion :text_not_present
+    page_assertion :location_ends_with
+    deprecate :assert_location_ends_in, :assert_location_ends_with
+
+    element_assertion :value
+    element_assertion :selected
+    element_assertion :checked
+    element_assertion :not_checked
+    element_assertion :text
+    element_assertion :element_present
+    element_assertion :element_not_present
+    element_assertion :next_sibling
+    element_assertion :contains_in_order
+    element_assertion :visible
+    element_assertion :not_visible
+
+    def assert_attribute(element_locator, attribute_name, expected_value)
+      element(element_locator).assert_attribute(attribute_name, expected_value)
+    end
+
+    # Assert and wait for locator element to contain text.
+    def assert_element_contains(locator, text, options = {})
+      element(locator).assert_contains(text, options)
+    end
+    alias_method :assert_element_contains_text, :assert_element_contains
+    
+    # Assert and wait for locator element to not contain text.
+    def assert_element_does_not_contain(locator, text, options={})
+      element(locator).assert_does_not_contain(text, options)
+    end
+    deprecate :assert_element_does_not_contain_text, :assert_element_does_not_contain
+
+    # Does the element at locator contain the text?
+    def element_contains_text(locator, text)
+      element(locator).assert_contains(text)
     end
-    attr_writer :configuration
+
     attr_accessor :selenium_driver  
     include WaitFor
 
@@ -15,14 +71,17 @@ module Polonium
       Net::HTTP.get(uri)
     end
 
-    # Open the home page of the Application and wait for the page to load.
-    def open_home_page
-      selenium_driver.open(configuration.browser_url)
+    def configuration
+      Polonium::Configuration.instance
     end
 
     protected
     def method_missing(method_name, *args, &block)
-      selenium_driver.__send__(method_name, *args, &block)
+      if selenium_driver.respond_to?(method_name)
+        selenium_driver.__send__(method_name, *args, &block)
+      else
+        super
+      end
     end
     delegate :open,
              :type,