rsel 0.1.1 → 0.1.2

data/lib/rsel/study_html.rb

@@ -0,0 +1,198 @@
+require 'rubygems'
+require 'nokogiri'
+require 'rsel/support'
+
+module Rsel
+  # Class to study a web page: Parses it with Nokogiri, and allows searching and simplifying Selenium-like expressions.
+  class StudyHtml
+
+    include Support
+
+    # A large sentinel for @dirties.
+    NO_PAGE_LOADED = 1000000
+
+    def initialize(first_page=nil)
+      @sections_kept_clean = []
+      if first_page
+        study(first_page)
+      else
+        @studied_page = nil
+        # Invariant: @dirties == 0 while @keep_clean is true.
+        @keep_clean = false
+        # No page is loaded.  Set a large sentinel value so it's never tested.
+        @dirties = NO_PAGE_LOADED
+      end
+    end
+
+    # Load a page to study.
+    #
+    # @param [String] page
+    #   Any argument that works for Nokogiri::HTML.  Often HTML in a string, or a path to a file.
+    # @param [Boolean] keep
+    #   Sets {#keep_clean} with this argument.  Default is false, so study(), by default, turns off keep_clean.
+    def study(page, keep=false)
+      @sections_kept_clean = []
+      begin
+        @studied_page = Nokogiri::HTML(page)
+        @dirties = 0
+      rescue => e
+        @keep_clean = false
+        @dirties = NO_PAGE_LOADED
+        @studied_page = nil
+        raise e
+      end
+      @keep_clean = keep
+    end
+
+    # "Dirty" the studied page, marking one (potential) change since the page was studied.
+    # This can be undone: see {#undo_last_dirty}
+    # Does nothing if {#keep_clean} has been called with true, which may occur from {#study}
+    def dirty
+      @dirties += 1 unless @keep_clean
+    end
+
+    # Try to un-{#dirty} the studied page by marking one (potential) change since the page was studied not actually a change.
+    # This may or may not be enough to resume using the studied page.  Cannot be used preemptively.
+    def undo_last_dirty
+      @dirties -= 1 unless @dirties <= 0
+    end
+
+    # Try to un-{#dirty} the studied page.  Returns true on success or false if there was no page to clean.
+    def undo_all_dirties
+      if @studied_page != nil
+        @dirties = 0
+      else
+        @keep_clean = false
+        @dirties = NO_PAGE_LOADED
+      end
+      return @dirties == 0
+    end
+
+    # Return whether the studied page is clean and ready for analysis.  Not a verb - does not {#undo_all_dirties}.
+    def clean?
+      return @dirties == 0
+    end
+    #alias_method :clean, :clean?
+
+    # Turn on or off maintenance of clean status.  True prevents {#dirty} from having any effect.
+    # Also cleans all dirties (with {#undo_all_dirties}) if true, or dirties the page (with {#dirty}) if false.
+    def keep_clean(switch)
+      if switch
+        if undo_all_dirties
+          @keep_clean = true
+          return true
+        else
+          return false
+        end
+      else
+        @keep_clean = false
+        dirty
+        return true
+      end
+    end
+
+    # Return whether keep_clean is on or not.  Useful if you want to start keeping clean and then return to your previous state.
+    # Invariant: clean? == true if keeping_clean? == true.
+    def keeping_clean?
+      return @keep_clean
+    end
+
+    # Store the current keep_clean status, and begin forcing study use until the
+    # next {#end_section}.  
+    # A semi-optional block argument returns the first argument to give to {#study}.
+    # It's not required if {#clean?}, but otherwise if it's not present an exception
+    # will be thrown.
+    def begin_section
+      last_keep_clean = @keep_clean
+      if clean?
+        @keep_clean = true
+      else
+        # This will erase all prior sections.
+        study(yield, true)
+      end
+      @sections_kept_clean.push(last_keep_clean)
+    end
+
+    # Restore the keep_clean status from before the last {#begin_section}.
+    # Also marks the page dirty unless the last keep_clean was true.
+    # It's fine to call this more than you call begin_section.  It will act just
+    # like keep_clean(false) if it runs out of stack parameters.
+    def end_section
+      # Can't just assign - what if nil is popped?
+      if @sections_kept_clean.pop
+        @keep_clean = true
+      else
+        @keep_clean = false
+        dirty
+      end
+      return true
+    end
+
+    # Simplify a Selenium-like locator (xpath or a css path), based on the studied page
+    # 
+    # @param [Boolean] x
+    # @param [Boolean] tocss
+    #   Return a css= path as a last resort?  Defaults to true.
+    def simplify_locator(locator, tocss=true)
+      return locator if @dirties > 0
+
+      # We need a locator using either a css= or locator= expression.
+      if locator[0,4] == 'css='
+        studied_node = @studied_page.at_css(locator[4,locator.length])
+        # If we're already using a css path, don't bother simplifying it to another css path.
+        tocss = false
+      elsif locator[0,6] == 'xpath=' || locator[0,2] == '//'
+        locator = 'xpath='+locator if locator[0,2] == '//'
+        studied_node = @studied_page.at_xpath(locator[6,locator.length])
+      else
+        # Some other kind of locator.  Just return it.
+        return locator
+      end
+      # If the path wasn't found, just return the locator; maybe the browser will
+      # have better luck.  (Or return a better error message!)
+      return locator if studied_node == nil
+
+      # Now let's try simplified locators.  First, id.
+      return "id=#{studied_node['id']}" if(studied_node['id'] &&
+                                           @studied_page.at_xpath("//*[@id='#{studied_node['id']}']") == studied_node)
+      # Next, name.  Same pattern.
+      return "name=#{studied_node['name']}" if(studied_node['name'] &&
+                                               @studied_page.at_xpath("//*[@name='#{studied_node['name']}']") == studied_node)
+
+      # Link, perhaps?
+      return "link=#{studied_node.inner_text}" if(studied_node.node_name.downcase == 'a' && 
+                                               @studied_page.at_xpath("//a[text()='#{studied_node.inner_text}']") == studied_node)
+
+      # Finally, try a CSS path.  Make that a simple xpath, since nth-of-type doesn't work.  But give up if we were told not to convert to CSS.
+      return locator unless tocss
+      return "xpath=#{studied_node.path}"
+    end
+
+    # Find a studied node by almost any type of Selenium locator.  Returns a Nokogiri::Node, or nil if not found.
+    def get_node(locator)
+      return nil if @dirties > 0
+      case locator
+      when /^id=/, /^name=/
+        locator = locator.gsub("'","\\\\'").gsub(/([a-z]+)=([^ ]*) */, "[@\\1='\\2']")
+        locator = locator.sub(/\]([^ ]+) */, "][@value='\\1']")
+        return @studied_page.at_xpath("//*#{locator}")
+      when /^link=/
+        # Parse the link through loc (which may simplify it to an id or something).
+        # Then try get_studied_node again.  It should not return to this spot.
+        return get_node(loc(locator[5,locator.length], 'link'))
+      when /^css=/
+        return @studied_page.at_css(locator[4,locator.length])
+      when /^xpath=/, /^\/\//
+        return @studied_page.at_xpath(locator.sub(/^xpath=/,''))
+      when /^dom=/, /^document\./
+        # Can't parse dom=
+        return nil
+      else
+        locator = locator.sub(/^id(entifier)?=/,'')
+        retval = @studied_page.at_xpath("//*[@id='#{locator}']")
+        retval = @studied_page.at_xpath("//*[@name='#{locator}']") unless retval
+        return retval
+      end
+    end
+  end
+end

data/lib/rsel/support.rb

@@ -36,7 +36,11 @@ module Rsel
       elsif locator =~ /^(id=|name=|dom=|xpath=|link=|css=)/
         return locator
       else
-        return xpath(kind, locator, scope)
+        if kind.empty?
+          raise ArgumentError, "kind is required for Rsel-style locators"
+        else
+          return xpath(kind, locator, scope)
+        end
       end
     end
 
@@ -171,6 +175,8 @@ module Rsel
     # Normalize the given hash of name => locator mappings.
     # Converts all keys to lowercase and calls {#escape_for_hash} on them.
     #
+    # @since 0.1.1
+    #
     def normalize_ids(ids)
       ids = {} unless ids.is_a? Hash
       ids.keys.each do |key|
@@ -198,10 +204,11 @@ module Rsel
       return text.gsub(/<\/?[^>]*>/, '')
     end
 
-    # This module defines helper methods for building XPath expressions
-    # copied from Kelp::XPaths
     # Return an XPath for any table row containing all strings in `texts`,
     # within the current context.
+    #
+    # @since 0.1.1
+    #
     def xpath_row_containing(texts)
       texts = [texts] if texts.class == String
       conditions = texts.collect do |text|
@@ -218,6 +225,8 @@ module Rsel
     #   xpath_sanitize("Bob's")
     #   # => concat('Bob', "'", 's')
     #
+    # @since 0.1.1
+    #
     def xpath_sanitize(text)
       # If there's nothing to escape, just wrap text in single-quotes
       if !text.include?("'")
@@ -230,6 +239,7 @@ module Rsel
 
     # Convert a string like "yes", "true", "1", etc.
     # Values currently recognized as true, case-insensitive:
+    #
     # * [empty string]
     # * 1
     # * Check
@@ -239,17 +249,22 @@ module Rsel
     # * Selected
     # * True
     # * Yes
+    #
+    # @since 0.1.1
+    #
     def string_is_true?(s)
       return /^(?:yes|true|on|(?:check|select)(?:ed)?|1|)$/i === s
     end
 
     # Compare values like Selenium does, with regexpi? and globs.
+    #
     # @param [String] text
     #   A string.
-    #
     # @param [String] expected
     #   Another string.  This one may have glob:, regexp:, etc.
     #
+    # @since 0.1.1
+    #
     def selenium_compare(text, expected)
       if expected.sub!(/^regexp:/, '')
         return /#{expected}/ === text
@@ -263,6 +278,92 @@ module Rsel
         return File.fnmatch(expected, text)
       end
     end
+
+    # Return `text` with glob markers `*` on each end, unless the text
+    # begins with `exact:`, `regexp:`, or `regexpi:`. This effectively
+    # allows normal text to match as a "contains" search instead of
+    # matching the entire string.
+    #
+    # @param [String] text
+    #   Text to globify
+    #
+    # @since 0.1.2
+    #
+    def globify(text)
+      if /^(exact|regexpi?):/ === text
+        return text
+      else
+        return text.sub(/^(glob:)?\*?/, '*').sub(/\*?$/, '*')
+      end
+    end
+
+
+    # Ensure that a given block gets a result within a timeout.
+    #
+    # This executes the given block statement once per second, until it returns
+    # a value that evaluates as true (meaning anything other than `false` or
+    # `nil`), or until the `seconds` timeout is reached. If the block evaluates
+    # as true within the timeout, return the block result. Otherwise, return
+    # `nil`.
+    #
+    # If the block never returns a value other than `false` or `nil`, then
+    # return `nil`. If the block raises an exception (*any* exception), that's
+    # considered a false result, and the block will be retried until a true
+    # result is returned, or the `seconds` timeout is reached.
+    #
+    # @param [Integer, String] seconds
+    #   Integer number of seconds to keep retrying the block
+    # @param [Block] block
+    #   Any block of code that might evaluate to a non-false value
+    #
+    # @return
+    #   Result of the block if it evaluated true-ish within the timeout, nil
+    #   if the block always evaluated as false or raised an exception.
+    #
+    # @since 0.1.2
+    #
+    # TODO: Return false if the block takes too long to execute (and exceeds
+    # the timeout)
+    #
+    def result_within(seconds, &block)
+      (seconds.to_i + 1).times do
+        result = yield rescue nil
+        return result if result
+        sleep 1
+      end
+      return nil
+    end
+
+
+    # Ensure that a given block fails within a timeout.
+    #
+    # This is a kind of counterpart to {#result_within}
+    #
+    # @param [Integer, String] seconds
+    #   Integer number of seconds to keep retrying the block
+    # @param [Block] block
+    #   Any block of code that might evaluate to a false value,
+    #   or raise an exception, within the timeout.
+    #
+    # @return [Boolean]
+    #   true if the block failed (returned false/nil or raised an exception)
+    #   within the timeout, false if the block never failed within the timeout.
+    #
+    # @since 0.1.2
+    #
+    def failed_within(seconds, &block)
+      (seconds.to_i + 1).times do
+        begin
+          result = yield
+        rescue
+          return true
+        else
+          return true if !result
+        end
+        sleep 1
+      end
+      return false
+    end
   end
 end
 

data/rsel.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = "rsel"
-  s.version = "0.1.1"
+  s.version = "0.1.2"
   s.summary = "Runs Selenium tests from FitNesse"
   s.description = <<-EOS
     Rsel provides a Slim fixture for running Selenium tests, with

data/spec/spec_helper.rb

@@ -1,32 +1,14 @@
+# This file includes RSpec configuration that is needed for all spec testing.
+
 require 'rspec'
+require 'rspec/autorun' # needed for RSpec 2.6.x
 require 'rsel'
 require 'selenium/client'
 
 require File.expand_path(File.join(File.dirname(__FILE__), '..', 'test', 'app'))
 
 RSpec.configure do |config|
+  config.color_enabled = true
   config.include Rsel
   config.include Rsel::Support
 end
-
-
-# Monkeypatch the Selenium::Client::Protocol module,
-# to prevent http_post from spewing out a bunch of `puts`es on failure.
-# (It's really distracting when running spec tests)
-module Selenium
-  module Client
-    module Protocol
-      def http_post(data)
-        start = Time.now
-        called_from = caller.detect{|line| line !~ /(selenium-client|vendor|usr\/lib\/ruby|\(eval\))/i}
-        http = Net::HTTP.new(@host, @port)
-        http.open_timeout = default_timeout_in_seconds
-        http.read_timeout = default_timeout_in_seconds
-        response = http.post('/selenium-server/driver/', data, HTTP_HEADERS)
-        # <-- Here is where all the puts statements were -->
-        [ response.body[0..1], response.body ]
-      end
-    end
-  end
-end
-

data/spec/st_alerts.rb

@@ -0,0 +1,48 @@
+require 'spec/st_spec_helper'
+
+describe 'alerts' do
+  describe "#see_alert_within_seconds" do
+    before(:each) do
+      @st.visit("/alert").should be_true
+    end
+
+    context "passes when" do
+      it "sees a generic alert" do
+        @st.click("Alert me now")
+        @st.see_alert_within_seconds.should be_true
+      end
+      it "sees a generic alert in time" do
+        @st.click("Alert me now")
+        @st.see_alert_within_seconds(10).should be_true
+      end
+      it "sees the specific alert" do
+        @st.click("Alert me now")
+        @st.see_alert_within_seconds("Ruby alert! Automate your workstations!").should be_true
+      end
+      it "sees the specific alert in time" do
+        @st.click("Alert me soon")
+        @st.see_alert_within_seconds("Ruby alert! Automate your workstations!", 10).should be_true
+      end
+    end
+
+    context "fails when" do
+      it "does not see a generic alert in time" do
+        @st.click("Alert me soon")
+        @st.see_alert_within_seconds(1).should be_false
+        # Clean up the alert, to avoid random errors later.
+        #@st.see_alert_within_seconds("Ruby alert! Automate your workstations!", 10).should be_true
+      end
+      it "does not see the specific alert in time" do
+        @st.click("Alert me soon")
+        @st.see_alert_within_seconds("Ruby alert! Automate your workstations!", 1).should be_false
+        # Clean up the alert, to avoid random errors later.
+        #@st.see_alert_within_seconds("Ruby alert! Automate your workstations!", 10).should be_true
+      end
+      it "sees a different alert message" do
+        @st.click("Alert me now")
+        @st.see_alert_within_seconds("Ruby alert! Man your workstations!", 10).should be_false
+      end
+    end
+
+  end
+end