rsel 0.1.1 → 0.1.2

data/.gitignore

@@ -6,3 +6,4 @@ pkg/*
 *~
 coverage/*
 doc/*
+test/server/*.jar

data/Rakefile

@@ -5,9 +5,10 @@ require 'rspec/core/rake_task'
 
 ROOT_DIR = File.expand_path(File.dirname(__FILE__))
 TEST_APP = File.join(ROOT_DIR, 'test', 'app.rb')
-#SELENIUM_RC_JAR = File.join(ROOT_DIR, 'test', 'server', 'selenium-server-1.0.3-SNAPSHOT-standalone.jar')
-SELENIUM_RC_JAR = File.join(ROOT_DIR, 'test', 'server', 'selenium-server-standalone-2.4.0.jar')
-SELENIUM_RC_LOG = File.join(ROOT_DIR, 'selenium-rc.log')
+SELENIUM_JAR = 'selenium-server-standalone-2.20.0.jar'
+SELENIUM_DOWNLOAD_URL = 'http://selenium.googlecode.com/files/' + SELENIUM_JAR
+SELENIUM_JAR_PATH = File.join(ROOT_DIR, 'test', 'server', SELENIUM_JAR)
+SELENIUM_LOG_PATH = File.join(ROOT_DIR, 'selenium-rc.log')
 
 namespace 'testapp' do
   desc "Start the test webapp in the background"
@@ -28,13 +29,25 @@ namespace 'testapp' do
   end
 end
 
+namespace 'selenium' do
+  desc "Download the official selenium-server jar file"
+  task :download do
+    if File.exist?(SELENIUM_JAR_PATH)
+      puts "#{SELENIUM_JAR_PATH} already exists. Skipping download."
+    else
+      puts "Downloading #{SELENIUM_JAR_PATH} (this may take a minute)..."
+      system("wget #{SELENIUM_DOWNLOAD_URL} --output-document=#{SELENIUM_JAR_PATH}")
+    end
+  end
+end
+
 Selenium::Rake::RemoteControlStartTask.new do |rc|
-  rc.jar_file = SELENIUM_RC_JAR
+  rc.jar_file = SELENIUM_JAR_PATH
   rc.port = 4444
   rc.background = true
   rc.timeout_in_seconds = 60
   rc.wait_until_up_and_running = true
-  rc.log_to = SELENIUM_RC_LOG
+  rc.log_to = SELENIUM_LOG_PATH
 end
 
 Selenium::Rake::RemoteControlStopTask.new do |rc|
@@ -58,18 +71,18 @@ namespace 'rcov' do
     t.rcov = true
     t.rcov_opts = [
       '--exclude /.gem/,/gems/,spec',
-      '--include lib/**/*.rb',
+      '--include-file lib/**/*.rb',
     ]
   end
 
-  desc "Run support spec tests with coverage analysis"
+  desc "Run all spec tests with coverage analysis"
   RSpec::Core::RakeTask.new(:all) do |t|
     t.pattern = 'spec/**/*.rb'
     t.rspec_opts = ['--color', '--format doc']
     t.rcov = true
     t.rcov_opts = [
       '--exclude /.gem/,/gems/,spec',
-      '--include lib/**/*.rb',
+      '--include-file lib/**/*.rb',
       # Ensure the main .rb file gets included
       '--include-file lib/rsel/selenium_test.rb',
     ]
@@ -79,6 +92,7 @@ end
 namespace 'servers' do
   desc "Start the Selenium and testapp servers"
   task :start do
+    Rake::Task['selenium:download'].invoke
     Rake::Task['testapp:start'].invoke
     Rake::Task['selenium:rc:start'].invoke
   end

data/docs/development.md

@@ -39,6 +39,7 @@ gets broken. You can do this with a single `rake` command:
 
 This will do the following:
 
+- Download an official selenium-server `.jar` into `test/server` (if needed)
 - Start the Sinatra test application (code in `test/app.rb` and `test/views/*.erb`)
 - Start the Selenium server (the `.jar` file in `test/server`)
 - Run RSpec

data/docs/history.md

@@ -1,11 +1,21 @@
 Rsel History
 ============
 
+0.1.2
+-----
+
+- Studying: customizable optimization to improve performance
+- More scoping (see, do_not_see, see_within_seconds, do_not_see_within_seconds)
+- Alert verification (see_alert_within_seconds)
+- Glob and regex can now be used in more places (selenium_compare)
+
+
+
 0.1.1
 -----
 
 - Conditional expressions (if_is, if_i_see, if_parameter, otherwise, end_if)
-- Temporal visibility (see|do_not_see)_within_seconds
+- Temporal visibility (see_within_seconds, do_not_see_within_seconds)
 - Generic field equality (generic_field_equals)
 - Generic field fill-in (set_field, set_field_among)
 - Hash-based field fill-in (set_fields, sef_fields_among)

data/docs/index.md

@@ -10,6 +10,7 @@ Rsel is a [Selenium](http://seleniumhq.org) wrapper for
 - [FitNesse](fitnesse.md)
 - [Locators](locators.md)
 - [Scoping](scoping.md)
+- [Studying](studying.md)
 - [Examples](examples.md)
 - [Customization](custom.md)
 - [Scenarios](scenarios.md)

data/docs/scoping.md

@@ -141,5 +141,5 @@ have a use case that isn't covered by the existing scopes, please [submit an
 issue](http://github.com/a-e/rsel/issues), or better yet, implement it yourself
 and submit a pull request. See [Development](development.md) for more info.
 
-Next: [Examples](examples.md)
+Next: [Studying](studying.md)
 

data/docs/studying.md

@@ -0,0 +1,76 @@
+Studying
+========
+
+What is studying?
+-----------------
+Studying is looking at some material to recall it more easily later.  No,
+really!  In this case, studying refers to a process that sends the entire web
+page from the browser to the Rsel server for further analysis.  The name is
+based on Perl's `study` command.
+
+Why would I want to study?  (I'm not in school anymore!)
+--------------------------------------------------------
+The main reason for studying is that Internet Explorer works with pages, and
+xpaths in particular, very slowly.  It so happens that the xpaths sent by
+normal Rsel commands are particularly slow to process.  Studying can make your
+test run five times as fast or more!
+
+Wow!  What's the catch?
+-----------------------
+The catch is that when you study, you may not be aware of what's going on
+around you.  While studying, if the page changes on the web browser, you often
+won't see those changes.  This can lead to failed identification of controls,
+or worse, misidentifications.
+
+The other, minor catch is that you could wind up spending more time sending
+data (entire web pages) than you save by studying.
+
+Alright, I'll be careful.  How do I use studying?
+-------------------------------------------------
+There are two ways, the easy way and the efficient way.  The efficient way is
+to identify blocks where you are doing a lot of work on one page, but the HTML
+content of a page won't change.  Then place a `begin_study` call before the
+block, and an `end_study` call after it.
+
+What happens if I forget about end_study?
+-----------------------------------------
+Don't worry: studying is smart enough to notice certain commands that indicate
+major page changes, such as `page_loads_in_seconds_or_less` and
+`see_within_seconds`.  Of course, this could also lead to your study blocks
+ending before you expect them to, but such commands almost always mean a study
+block should end.
+
+That's nice, but adding all those blocks sounds like a pain.  What's the easy way?
+----------------------------------------------------------------------------------
+The easy way is to set a minimum number of fields which, when worked with at
+once, will be studied before the work starts.  You do this with either the
+`study` option when initializing Rsel or with the `set_fields_study_min`
+command within Rsel.  Zero, the default, means to never study.  Setting the
+value to 10, for instance, would mean that when one command works with 10 or
+more different fields at once, a study would happen before the work begins.
+Right now, only the `set_fields` and `fields_equal` classes of commands can
+work with so many different fields at once.
+
+What if I set set_fields_study_min to 1?  Does it...study for every command?
+----------------------------------------------------------------------------
+Almost.  Along with the set_fields and fields_equal commands mentioned above,
+every command that uses an xpath of 100 characters or more gets studied.  (This
+bit is currently hard-coded; I may modify it in future versions.)  Some
+commands are also known not to affect the page text, like `see` or `get_text`.
+These do not trigger re-studying for the next command.  Even if
+`set_fields_study_min` is greater than 1, commands after a `fields_equal` may
+also benefit from the studying done in that command.
+
+Too long; didn't read.  Can't I just say "go fast" or something?
+----------------------------------------------------------------
+Pretty much.  Add the `study:auto` value to the Rsel initialization hash.
+
+Sweet, most of my tests are fast on IE!  But some now fail.
+-----------------------------------------------------------
+Auto-studying works very hard to be transparent and invisible, but rarely it
+fails.  For sections like this, you can turn off studying with
+`set_fields_study_min(0)` or `set_fields_study_min('never')`.  You can later go
+back to what you set in the initialization with
+`set_fields_study_min('default')`.
+
+Next: [Examples](examples.md)

data/lib/rsel/selenium_test.rb

@@ -5,6 +5,7 @@ require 'xpath'
 require 'selenium/client'
 require 'rsel/support'
 require 'rsel/exceptions'
+require 'rsel/study_html'
 
 module Rsel
 
@@ -42,9 +43,16 @@ module Rsel
     # @option options [String, Boolean] :stop_on_failure
     #   `true` or `'true'` to abort the test when a failure occurs;
     #   `false` or `'false'` to continue execution when failure occurs.
+    # @option options [String, Integer] :study
+    #   How many steps have to be done at once to force studying.  Default
+    #   is `Never` (0).  Other accepted strings are `Always' (1), `Auto(matic)`
+    #   (10 for most browsers and 1 for Internet Explorer), or an integer.
+    #   Unrecognized strings result in the default.
     # @option options [String, Integer] :timeout
     #   Default timeout in seconds. This determines how long the `open` method
-    #   will wait for the page to load.
+    #   will wait for the page to load, as well as the default timeout for
+    #   methods like `see_within_seconds`, `do_not_see_within_seconds`, and
+    #   `see_alert_within_seconds`.
     #
     # @example
     #   | script | selenium test | http://site.to.test/ |
@@ -69,6 +77,14 @@ module Rsel
       end
       @found_failure = false
       @conditional_stack = [ true ]
+      # Study data
+      @study = StudyHtml.new()
+      # @fields_study_min: The minimum number of fields to set_fields or fields_equal at once before studying is invoked.
+      # To be on the safe side, studying is turned off by default, unless you set another value.
+      @fields_study_min = parse_fields_study_min(options[:study], 0)
+      @default_fields_study_min = @fields_study_min
+      # @xpath_study_length_min: The minimum number of characters in an xpath before studying is invoked when @fields_study_min == 1.
+      @xpath_study_length_min = 100
       # A list of error messages:
       @errors = []
     end
@@ -78,7 +94,7 @@ module Rsel
 
 
     # Start the session and open a browser to the URL defined at the start of
-    # the test.
+    # the test. If a browser session is already open, just return true.
     #
     # @example
     #   | Open browser |
@@ -86,6 +102,7 @@ module Rsel
     # @raise [StopTestCannotConnect] if Selenium connection cannot be made
     #
     def open_browser
+      return true if @browser.session_started?
       begin
         @browser.start_new_browser_session
       rescue
@@ -115,6 +132,13 @@ module Rsel
     #
     def close_browser(show_errors='')
       @browser.close_current_browser_session
+      end_study
+      if in_conditional?
+        # Note the lack of return.  This just adds an error to the stack if we're in a conditional.
+        failure "If without matching End if"
+        reset_conditionals
+      end
+
       # Show errors in an exception if requested.
       if (!(/not|without/i === show_errors) && @errors.length > 0)
         raise StopTestStepFailed, @errors.join("\n").gsub('<','&lt;')
@@ -136,6 +160,69 @@ module Rsel
       return current_errors.join("\n")
     end
 
+
+    # Study the current web page, for more efficient parsing and data retrieval
+    # on the Rsel side rather than the Selenium browser side.  Named for the
+    # Perl "study" command.  Like its namesake, begin_study takes some time.
+    #
+    # Warning: When you study, you can learn information more quickly, but you
+    # may not be aware of what's going on around you!  If any action you perform
+    # has side-effects on the web page, you may not notice them while studying
+    # is on.  This is why so many methods call {#end_study} automatically.  But
+    # many cases remain where you could get into trouble if you forget this.
+    #
+    # Note: Calling this twice in a row without an intervening end_study will
+    # result in the first end_study not actually ending studying.  Again, many
+    # methods call end_study, so this is a possible, but unlikely, problem.
+    def begin_study
+      return skip_status if skip_step?
+      fail_on_exception do
+        @study.begin_section { page_to_study }
+      end
+    end
+
+    # Turn off studying.  Several other methods call this, including:
+    #   * {#click_back}
+    #   * {#close_browser}
+    #   * {#end_scenario}
+    #   * {#page_loads_in_seconds_or_less}
+    #   * {#refresh_page}
+    #   * {#see_within_seconds}
+    #   * {#do_not_see_within_seconds}
+    #   * {#visit}
+    # Don't be afraid to call this method as many times as you need to!
+    def end_study
+      @study.end_section
+      return skip_status if skip_step?
+      return true
+    end
+
+    # If studying is turned off, a flag is set, but the page is not deleted.
+    # This method turns the flag back on, without reloading the web page.
+    # Useful if you called one of the methods that calls {#end_study}, but
+    # you expect that the page (or the relevant part of a page) didn't
+    # actually change.  (Or you just want to verify data on the old page.)
+    def continue_study
+      return skip_status if skip_step?
+      pass_if @study.keep_clean(true), "Unable to continue studying: no page has been studied!"
+    end
+
+    # Set the minimum number of fields that must appear in a set_fields
+    # before studying is invoked.  "Never", or 0, turns off studying.
+    # "Always", or 1, turns studying on whenever a long xpath is found.
+    # Any other non-integer string resumes the studying pattern set in
+    # the initial option.
+    #
+    # @param [String or Integer] level
+    #   A (parsable) integer
+    def set_fields_study_min(level=nil)
+      return skip_status if skip_step?
+      fail_on_exception do
+        @fields_study_min = parse_fields_study_min(level, @default_fields_study_min)
+        end_study if @fields_study_min == 0
+      end
+    end
+
     # Begin a new scenario, and forget about any previous failures.
     # This allows you to modularize your tests into standalone sections
     # that can run independently of previous scenarios, regardless of
@@ -162,6 +249,7 @@ module Rsel
     # @since 0.0.9
     #
     def end_scenario
+      end_study
       return true
     end
 
@@ -178,6 +266,7 @@ module Rsel
     #
     def visit(path_or_url)
       return skip_status if skip_step?
+      end_study
       fail_on_exception do
         @browser.open(strip_tags(path_or_url))
       end
@@ -191,6 +280,7 @@ module Rsel
     #
     def click_back
       return skip_status if skip_step?
+      end_study
       fail_on_exception do
         @browser.go_back
       end
@@ -204,6 +294,7 @@ module Rsel
     #
     def refresh_page
       return skip_status if skip_step?
+      end_study
       fail_on_exception do
         @browser.refresh
       end
@@ -226,12 +317,27 @@ module Rsel
     # @param [String] text
     #   Plain text that should be visible on the current page
     #
+    # @param [Hash] scope
+    #   Scoping keywords as understood by {#xpath}
+    #
     # @example
     #   | See | Welcome, Marcus |
     #
-    def see(text)
+    def see(text, scope=nil)
       return skip_status if skip_step?
-      pass_if @browser.text?(text)
+      if scope.nil?
+        # Can't do a Study workaround - it doesn't know what's visible.
+        return pass_if @browser.text?(text)
+      else
+        selector = loc("css=", '', scope).strip
+        @study.undo_last_dirty # This method does not modify the browser page contents.
+        # Can't do a Study workaround - it doesn't know what's visible.
+        fail_on_exception do
+          match = selenium_compare(@browser.get_text(selector), globify(text))
+          return pass_if match,
+            "'#{text}' not found in '#{@browser.get_text(selector)}'"
+        end
+      end
     end
 
 
@@ -240,12 +346,30 @@ module Rsel
     # @param [String] text
     #   Plain text that should not be visible on the current page
     #
+    # @param [Hash] scope
+    #   Scoping keywords as understood by {#xpath}
+    #
     # @example
     #   | Do not see | Take a hike |
     #
-    def do_not_see(text)
+    def do_not_see(text, scope=nil)
       return skip_status if skip_step?
-      pass_if !@browser.text?(text)
+      if scope.nil?
+        # Can't do a Study workaround - it doesn't know what's visible.
+        return pass_if !@browser.text?(text)
+      else
+        selector = loc("css=", '', scope).strip
+        @study.undo_last_dirty # This method does not modify the browser page contents.
+        begin
+          # Can't do a Study workaround - it doesn't know what's visible.
+          match = selenium_compare(@browser.get_text(selector), globify(text))
+          return pass_if !match,
+            "'#{text}' not expected, but found in '#{@browser.get_text(selector)}'"
+        rescue
+          # Do not see the selector, so do not see the text within it.
+          return true
+        end
+      end
     end
 
 
@@ -255,31 +379,50 @@ module Rsel
     #
     # @param [String] text
     #   Plain text that should be appear on or visible on the current page
-    # @param [String] seconds
-    #   Integer number of seconds to wait.
+    # @param [Integer, String] seconds
+    #   Integer number of seconds to wait, or `-1` to use the default timeout.
+    # @param [Hash] scope
+    #   Scoping keywords as understood by {#xpath}
+    #
     #
     # @example
     #   | Click | ajax_login | button |
     #   | See | Welcome back, Marcus | within | 10 | seconds |
     #   | Note | The following uses the Selenium default timeout: |
-    #   | See | How do you feel? | within seconds |
+    #   | See | How do you feel? | within seconds | !{within:terminal} |
     #
     # @since 0.1.1
     #
-    def see_within_seconds(text, seconds=-1)
+    def see_within_seconds(text, seconds=-1, scope=nil)
       return skip_status if skip_step?
+      end_study
+      if scope.nil? && (seconds.is_a? Hash)
+        scope = seconds
+        seconds = -1
+      end
       seconds = @browser.default_timeout_in_seconds if seconds == -1
-      pass_if !(Integer(seconds)+1).times{ break if (@browser.text?(text) rescue false); sleep 1 }
-      # This would be better if it worked:
-      # pass_if @browser.wait_for(:text => text, :timeout_in_seconds => seconds);
+      if scope.nil?
+        return pass_if result_within(seconds) {
+          @browser.text?(text)
+        }
+        # This would be better if it worked:
+        # pass_if @browser.wait_for(:text => text, :timeout_in_seconds => seconds);
+      else
+        selector = loc("css=", '', scope).strip
+        return pass_if result_within(seconds) {
+          selenium_compare(@browser.get_text(selector), globify(text))
+        }
+      end
     end
 
     # Ensure that the given text does not appear on the current page, eventually.
     #
     # @param [String] text
     #   Plain text that should disappear from or not be present on the current page
-    # @param [String] seconds
-    #   Integer number of seconds to wait.
+    # @param [Integer, String] seconds
+    #   Integer number of seconds to wait, or `-1` to use the default timeout.
+    # @param [Hash] scope
+    #   Scoping keywords as understood by {#xpath}
     #
     # @example
     #   | Click | close | button | !{within:popup_ad} |
@@ -287,12 +430,26 @@ module Rsel
     #
     # @since 0.1.1
     #
-    def do_not_see_within_seconds(text, seconds=-1)
+    def do_not_see_within_seconds(text, seconds=-1, scope=nil)
       return skip_status if skip_step?
+      end_study
+      if scope.nil? && (seconds.is_a? Hash)
+        scope = seconds
+        seconds = -1
+      end
       seconds = @browser.default_timeout_in_seconds if seconds == -1
-      pass_if !(Integer(seconds)+1).times{ break if (!@browser.text?(text) rescue false); sleep 1 }
-      # This would be better if it worked:
-      # pass_if @browser.wait_for(:no_text => text, :timeout_in_seconds => seconds);
+      if scope.nil?
+        return pass_if result_within(seconds) {
+          !@browser.text?(text)
+        }
+        # This would be better if it worked:
+        # pass_if @browser.wait_for(:no_text => text, :timeout_in_seconds => seconds);
+      else
+        selector = loc("css=", '', scope).strip
+        return pass_if failed_within(seconds) {
+          selenium_compare(@browser.get_text(selector), globify(text))
+        }
+      end
     end
 
 
@@ -307,7 +464,11 @@ module Rsel
     #
     def see_title(title)
       return skip_status if skip_step?
-      pass_if @browser.get_title == title, "Page title is '#{@browser.get_title}', not '#{title}'"
+      # Study workaround when possible.  (Probably won't happen a lot, but possible.)
+      bodynode = @study.get_node('xpath=/html/head/title')
+      return true if bodynode && bodynode.inner_text.strip == title
+      pass_if @browser.get_title == title,
+        "Page title is '#{@browser.get_title}', not '#{title}'"
     end
 
 
@@ -324,6 +485,49 @@ module Rsel
       pass_if !(@browser.get_title == title)
     end
 
+    # Ensure that an alert appears, optionally having the given text, within the
+    # given time or the default timeout.
+    #
+    # @param [String] text
+    #   Text of the alert that you expect to see
+    #
+    # @param [Integer, String] seconds
+    #   Integer number of seconds to wait, or `-1` to use the default timeout.
+    #
+    # @example
+    #   | see alert within seconds |
+    #     Validates any alert within the default timeout.
+    #
+    # @example
+    #   | see alert | Illegal operation! Authorities have been notified. | within | 15 | seconds |
+    #     Validates that the next alert that appears within the given timeout is as specified.
+    #
+    # @since 0.1.2
+    #
+    def see_alert_within_seconds(text=nil, seconds=-1)
+      return skip_status if skip_step?
+      # Handle the case of being given seconds, but not text.
+      if seconds == -1
+        begin
+          if Integer(text.to_s).to_s == text.to_s
+            seconds = text.to_s
+            text = nil
+          end
+        rescue
+        end
+      end
+      seconds = @browser.default_timeout_in_seconds if seconds == -1
+      alert_text = result_within(seconds) {
+        @browser.get_alert
+      }
+      if alert_text
+        return true if text.nil?
+        return pass_if selenium_compare(alert_text, text),
+          "Expected alert '#{text}', but got '#{alert_text}'!"
+      else
+        return failure
+      end
+    end
 
     # Ensure that a link exists on the page.
     #
@@ -340,7 +544,13 @@ module Rsel
     #
     def link_exists(locator, scope={})
       return skip_status if skip_step?
-      pass_if @browser.element?(loc(locator, 'link', scope))
+      locator = loc(locator, 'link', scope)
+      @study.undo_last_dirty # This method does not modify the browser page contents.
+
+      # Study workaround when possible.
+      bodynode = @study.get_node(locator)
+      return true if bodynode
+      pass_if @browser.element?(locator)
     end
 
 
@@ -359,7 +569,13 @@ module Rsel
     #
     def button_exists(locator, scope={})
       return skip_status if skip_step?
-      pass_if @browser.element?(loc(locator, 'button', scope))
+      locator = loc(locator, 'button', scope)
+      @study.undo_last_dirty # This method does not modify the browser page contents.
+
+      # Study workaround when possible.
+      bodynode = @study.get_node(locator)
+      return true if bodynode
+      pass_if @browser.element?(locator)
     end
 
 
@@ -378,7 +594,13 @@ module Rsel
     #
     def row_exists(cells)
       return skip_status if skip_step?
-      pass_if @browser.element?("xpath=#{xpath_row_containing(cells.split(/, */).map{|s| escape_for_hash(s)})}")
+      cells = cells.split(/, */).map { |s| escape_for_hash(s) }
+      locator = "xpath=#{xpath_row_containing(cells)}"
+
+      # Study workaround when possible.
+      bodynode = @study.get_node(locator)
+      return true if bodynode
+      pass_if @browser.element?(locator)
     end
 
     #
@@ -424,7 +646,6 @@ module Rsel
       type_into_field(text, locator, scope)
     end
 
-
     # Verify that a text field contains the given text. The field may include
     # additional text, as long as the expected value is in there somewhere.
     #
@@ -440,6 +661,7 @@ module Rsel
       return skip_status if skip_step?
       begin
         field = @browser.field(loc(locator, 'field', scope))
+        @study.undo_last_dirty # This method does not modify the browser page contents.
       rescue
         failure "Can't identify field #{locator}"
       else
@@ -464,6 +686,7 @@ module Rsel
       return skip_status if skip_step?
       begin
         field = @browser.field(loc(locator, 'field', scope))
+        @study.undo_last_dirty # This method does not modify the browser page contents.
       rescue
         failure "Can't identify field #{locator}"
       else
@@ -592,6 +815,7 @@ module Rsel
     def checkbox_is_enabled(locator, scope={})
       return skip_status if skip_step?
       xp = loc(locator, 'checkbox', scope)
+      @study.undo_last_dirty # This method does not modify the browser page contents.
       begin
         enabled = @browser.checked?(xp)
       rescue
@@ -618,6 +842,7 @@ module Rsel
     def radio_is_enabled(locator, scope={})
       return skip_status if skip_step?
       xp = loc(locator, 'radio_button', scope)
+      @study.undo_last_dirty # This method does not modify the browser page contents.
       begin
         enabled = @browser.checked?(xp)
       rescue
@@ -642,6 +867,7 @@ module Rsel
     def checkbox_is_disabled(locator, scope={})
       return skip_status if skip_step?
       xp = loc(locator, 'checkbox', scope)
+      @study.undo_last_dirty # This method does not modify the browser page contents.
       begin
         enabled = @browser.checked?(xp)
       rescue
@@ -668,6 +894,7 @@ module Rsel
     def radio_is_disabled(locator, scope={})
       return skip_status if skip_step?
       xp = loc(locator, 'radio_button', scope)
+      @study.undo_last_dirty # This method does not modify the browser page contents.
       begin
         enabled = @browser.checked?(xp)
       rescue
@@ -738,8 +965,11 @@ module Rsel
       # TODO: Apply scope
       dropdown = XPath::HTML.select(locator)
       opt = dropdown[XPath::HTML.option(option)]
-      opt_str = opt.to_s
-      pass_if @browser.element?("xpath=#{opt_str}")
+      opt_str = "xpath=#{opt.to_s}"
+      # Study workaround when possible.
+      bodynode = @study.get_node(opt_str)
+      return true if bodynode
+      pass_if @browser.element?(opt_str)
     end
 
 
@@ -759,6 +989,7 @@ module Rsel
       return skip_status if skip_step?
       begin
         selected = @browser.get_selected_label(loc(locator, 'select', scope))
+        @study.undo_last_dirty # This method does not modify the browser page contents.
       rescue
         failure "Can't identify dropdown #{locator}"
       else
@@ -794,6 +1025,7 @@ module Rsel
     #
     def page_loads_in_seconds_or_less(seconds)
       return skip_status if skip_step?
+      end_study
       fail_on_exception do
         @browser.wait_for_page_to_load(seconds)
       end
@@ -832,14 +1064,17 @@ module Rsel
     def set_field(locator, value='', scope={})
       return skip_status if skip_step?
       fail_on_exception do
-        # First, use Javascript to find out what the field is.
+        loceval = loc(locator, 'field', scope)
+        mytagname = ''
         begin
-          loceval = loc(locator, 'field', scope)
+          mytagname = tagname(loceval)
         rescue
           loceval = loc(locator, 'link_or_button', scope)
+          mytagname = tagname(loceval)
         end
-
-        case tagname(loceval)
+        #puts "My tag name is #{mytagname}\n"
+        #puts "My loceval is #{loceval}\n" #if /^id=/ === loceval
+        case mytagname
         when 'input.text', /^textarea\./
           return type_into_field(value, loceval)
         when 'input.radio'
@@ -855,7 +1090,6 @@ module Rsel
         when /^(a|button)\./,'input.button','input.submit','input.image','input.reset'
           return click(loceval)
         else
-          #raise ArgumentError, "Unidentified field #{locator}."
           return failure("Unidentified field #{locator}.")
         end
       end
@@ -906,13 +1140,23 @@ module Rsel
       return skip_status if skip_step?
       # FitNesse passes in "" for an empty field. Fix it.
       fields = {} if fields == ""
+
+      method_study = false
+      if @fields_study_min != 0 && @fields_study_min <= fields.length
+        method_study = true
+        # Then we want the page to be studied throughout this method.
+        begin_study
+      end
+
       fields.each do |key, value|
         key_esc = escape_for_hash(key.to_s)
         value_esc = escape_for_hash(value.to_s)
         unless set_field(key_esc, value_esc, scope)
+          end_study if method_study
           return failure "Failed to set field #{key_esc} to #{value_esc}"
         end
       end
+      end_study if method_study
       return true
     end
 
@@ -958,13 +1202,22 @@ module Rsel
       ids = {} if ids == ""
       fields = {} if fields == ""
 
+      method_study = false
+      if @fields_study_min != 0 && @fields_study_min <= fields.length
+        method_study = true
+        # Then we want the page to be studied throughout this method.
+        begin_study
+      end
+
       fields.each do |key, value|
         key_esc = escape_for_hash(key.to_s)
         value_esc = escape_for_hash(value.to_s)
         unless set_field_among(key_esc, value_esc, ids, scope)
+          end_study if method_study
           return failure("Failed to set #{key_esc} (#{ids[key_esc]}) to #{value_esc}")
         end
       end
+      end_study if method_study
       return true
     end
 
@@ -1000,13 +1253,8 @@ module Rsel
     def generic_field_equals(locator, value='', scope={})
       return skip_status if skip_step?
       fail_on_exception do
-        # First, use Javascript to find out what the field is.
-        begin
-          loceval = loc(locator, 'field', scope)
-        rescue
-          loceval = loc(locator, 'link_or_button', scope)
-        end
-
+        loceval = loc(locator, 'field', scope)
+        @study.undo_last_dirty # This method does not modify the browser page contents.
         case tagname(loceval)
         when 'input.text', /^textarea\./
           return field_equals(loceval, value)
@@ -1025,19 +1273,11 @@ module Rsel
         when /^select\./
           return dropdown_equals(loceval, value)
         else
-          #raise ArgumentError, "Unidentified field #{locator}."
           return failure("Unidentified field for comparison: #{locator}.")
         end
       end
     end
 
-
-    def tagname(loceval)
-      return @browser.get_eval(
-        'var loceval=this.browserbot.findElement("' +
-        loceval + '");loceval.tagName+"."+loceval.type').downcase
-    end
-
     # Check a value (with {#set_field}) in the named field, based on the given
     # name/value pairs. Uses {#escape_for_hash} to allow certain characters in
     # FitNesse.
@@ -1082,8 +1322,23 @@ module Rsel
       return skip_status if skip_step?
       # FitNesse passes in "" for an empty field. Fix it.
       fields = {} if fields == ""
+
+      method_study = false
+      if @fields_study_min != 0 && @fields_study_min <= fields.length
+        method_study = true
+        # Then we want the page to be studied throughout this method.
+        begin_study
+      end
+
       fields.keys.each do |field|
-        return failure unless generic_field_equals(escape_for_hash(field.to_s), escape_for_hash(fields[field]), scope)
+        unless generic_field_equals(escape_for_hash(field.to_s), escape_for_hash(fields[field]), scope)
+          end_study if method_study
+          return failure
+        end
+      end
+      if method_study
+        end_study
+        @study.undo_last_dirty
       end
       return true
     end
@@ -1131,8 +1386,22 @@ module Rsel
       ids = {} if ids == ""
       fields = {} if fields == ""
 
+      method_study = false
+      if @fields_study_min != 0 && @fields_study_min <= fields.length
+        method_study = true
+        # Then we want the page to be studied throughout this method.
+        begin_study
+      end
+
       fields.keys.each do |field|
-        return failure unless field_equals_among(escape_for_hash(field.to_s), escape_for_hash(fields[field]), ids, scope)
+        unless field_equals_among(escape_for_hash(field.to_s), escape_for_hash(fields[field]), ids, scope)
+          end_study if method_study
+          return failure
+        end
+      end
+      if method_study
+        end_study
+        @study.undo_last_dirty
       end
       return true
     end
@@ -1143,17 +1412,40 @@ module Rsel
     # instance can respond to that method. If so, that method is called
     # instead.
     #
+    # Prefixing a method with "check_" will verify the return string
+    # against the last argument.  This allows checking string values
+    # within an if block.
+    #
     # @since 0.0.6
     #
     def method_missing(method, *args, &block)
       return skip_status if skip_step?
+      do_check = false
+      if(/^check_/ === method.to_s)
+        # This emulates the FitNesse | Check | prefix, without the messy string return.
+        do_check = true
+        method = method.to_s.sub(/^check_/,'').to_sym
+        check_against = args.pop.to_s
+      end
+
+      # Allow methods like "Type" that have Ruby homonyms to be called with a "selenium" prefix.
+      method = method.to_s.sub(/^selenium_/,'').to_sym if /^selenium_/ === method.to_s
+
       if @browser.respond_to?(method)
+        # Most methods should dirty the study object.  These include get_eval and get_expression.
+        @study.dirty unless /^(get_(el|[^e])|is_)/ === method.to_s
         begin
           result = @browser.send(method, *args, &block)
         rescue
           failure "Method #{method} error"
         else
-          # The method call succeeded; did it return true or false?
+          # The method call succeeded
+          # Should we check this against another string?
+          if do_check
+            return pass_if selenium_compare(result.to_s, check_against),
+              "Expected '#{check_against}', but got '#{result.to_s}'"
+          end
+          # Did it return true or false?
           return failure if result == false
           # If a string, return that. We might Check or Show it.
           return result if result == true || (result.is_a? String)
@@ -1173,7 +1465,9 @@ module Rsel
     #
     # @since 0.0.6
     #
-    def respond_to?(method, include_private=false)
+    def respond_to?(orgmethod, include_private=false)
+      # Allow methods like "Type" that have Ruby homonyms to be called with a "selenium" prefix.
+      method = orgmethod.to_s.sub(/^(check_)?(selenium_)?/,'')
       if @browser.respond_to?(method)
         true
       else
@@ -1198,18 +1492,14 @@ module Rsel
     #
     def if_i_see(text)
       return false if aborted?
-      # If this if is inside a block that's not running, record that.
-      if !@conditional_stack.last
-        @conditional_stack.push nil
-        return nil
+      cond = false
+      begin
+        cond = @browser.text?(text)
+      rescue
+        # Something went wrong.  Therefore, I did not see the text.
+        cond = false
       end
-
-      # Test the condition.
-      @conditional_stack.push @browser.text?(text)
-
-      return true if @conditional_stack.last == true
-      return nil if @conditional_stack.last == false
-      return failure
+      return push_conditional(cond)
     end
 
     # If the given parameter is "yes" or "true", do the steps until I see an
@@ -1230,17 +1520,7 @@ module Rsel
     #
     def if_parameter(text)
       return false if aborted?
-      if !@conditional_stack.last
-        @conditional_stack.push nil
-        return nil
-      end
-
-      # Test the condition.
-      @conditional_stack.push string_is_true?(text)
-
-      return true if @conditional_stack.last == true
-      return nil if @conditional_stack.last == false
-      return failure
+      return push_conditional(string_is_true?(text))
     end
 
     # If the first parameter is the same as the second, do the steps until I see an
@@ -1265,17 +1545,7 @@ module Rsel
     #
     def if_is(text, expected)
       return false if aborted?
-      if !@conditional_stack.last
-        @conditional_stack.push nil
-        return nil
-      end
-
-      # Test the condition.
-      @conditional_stack.push selenium_compare(text, expected)
-
-      return true if @conditional_stack.last == true
-      return nil if @conditional_stack.last == false
-      return failure
+      return push_conditional(selenium_compare(text, expected))
     end
 
     # End an if block.
@@ -1285,11 +1555,11 @@ module Rsel
     def end_if
       return false if aborted?
       # If there was no prior matching if, fail.
-      return failure if @conditional_stack.length <= 1
+      return failure "End if without matching if" if !in_conditional?
 
       last_status = @conditional_stack.pop
       # If this end_if is within an un-executed if block, don't execute it.
-      return nil if last_status == nil
+      return nil if last_status.nil?
       return true
     end
 
@@ -1307,10 +1577,10 @@ module Rsel
     def otherwise
       return false if aborted?
       # If there was no prior matching if, fail.
-      return failure if @conditional_stack.length <= 1
+      return failure "Otherwise without matching if" if !in_conditional?
 
       # If this otherwise is within an un-executed if block, don't execute it.
-      return nil if @conditional_stack.last == nil
+      return nil if in_nil_conditional?
 
       last_stack = @conditional_stack.pop
       @conditional_stack.push !last_stack
@@ -1319,9 +1589,154 @@ module Rsel
       return failure
     end
 
+    # Reset the conditional stack to its initial state. This method is included
+    # mainly for unit testing purposes, and is not intended to be called by
+    # normal test scripts.
+    #
+    # @since 0.1.2
+    #
+    def reset_conditionals
+      @conditional_stack = [true]
+    end
 
     private
 
+    # Return true if we're inside a conditional block, false otherwise.
+    #
+    # @since 0.1.2
+    #
+    def in_conditional?
+      return @conditional_stack.length > 1
+    end
+
+    # Return true if we're inside a nil conditional block (one whose evaluation
+    # doesn't matter because it was precluded by an outer conditional block
+    # that was false).
+    #
+    # @since 0.1.2
+    #
+    def in_nil_conditional?
+      return in_conditional? && @conditional_stack.last.nil?
+    end
+
+    # Return true if we're inside a conditional block that was skipped,
+    # either because it evaluated false, or because it was inside another
+    # conditional that evaluated false.
+    #
+    # @since 0.1.2
+    #
+    def in_skipped_conditional?
+      return in_conditional? && !@conditional_stack.last
+    end
+
+    # Push a conditional result onto the stack.
+    #
+    # @param [Boolean] result
+    #   The result of the conditional expression you're pushing.
+    #
+    # @return [Boolean, nil]
+    #   true if the result is true, false otherwise.
+    #
+    # @since 0.1.2
+    #
+    def push_conditional(result)
+      # If this if is inside a block that's not running, record that.
+      if in_skipped_conditional?
+        @conditional_stack.push nil
+        return nil
+      end
+
+      # Test the condition.
+      @conditional_stack.push result
+
+      return true if @conditional_stack.last == true
+      return nil if @conditional_stack.last == false
+      return failure
+    end
+
+    # Overrides the support.rb loc() method, allowing searching a studied page
+    # to try simplify a CSS or XPath expression to an id= or name= expression.
+    #
+    # @param [Boolean] try_study
+    #   Try to use the studied page to simplify the path?  Defaults to true.
+    def loc(locator, kind='', scope={}, try_study=true)
+      locator = super(locator, kind, scope)
+      return locator unless try_study
+      @study.study(page_to_study) if(@fields_study_min == 1 && !@study.clean? && locator[0,6] == 'xpath=' && locator.length >= @xpath_study_length_min)
+      begin
+        retval = @study.simplify_locator(locator)
+      rescue
+        retval = locator
+      end
+      @study.dirty
+      return retval
+    end
+
+    # Returns the HTML of the current browser page, for studying.
+    # Just to keep this consistent.
+    def page_to_study
+      #puts "Page to study: <html>#{@browser.get_eval('window.document.getElementsByTagName(\'html\')[0].innerHTML')}</html>"
+      return "<html>#{@browser.get_eval('window.document.getElementsByTagName(\'html\')[0].innerHTML')}</html>"
+    end
+
+    # Parse the argument given into a value for @fields_study_min
+    # Returns the value, rather than setting @fields_study_min.
+    def parse_fields_study_min(s, default)
+      begin
+        s = s.downcase.strip
+      rescue
+      end
+
+      case s
+      when 'never'
+        return 0
+      when 'always'
+        return 1
+      when /^auto/
+        if @browser.browser_string == '*iexplore'
+          @default_fields_study_min = 1
+        else
+          @default_fields_study_min = 10
+        end
+      else
+        begin
+          return Integer(s.gsub(/[^0-9]/,''))
+        rescue
+          # Default case:
+          return default
+        end
+      end
+    end
+
+    # Use Javascript to determine the type of field referenced by loceval.
+    # Also turns loceval into an id= locator if possible.
+    #
+    # @param [String] loceval
+    #   Selenium-style locator
+    #   Warning: This parameter is effectively passed by reference!
+    #   We attempt to replace an xpath locator with an id=.
+    #
+    # @since 0.1.1
+    #
+    def tagname(loceval)
+      tname = nil
+      if @study.clean?
+        tname = @study.get_node(loceval)
+        # If we've studied, loceval should have already been converted to an id, or name, etc. So trying to change it again would be pointless.
+        return "#{tname.node_name}.#{tname['type']}" unless tname == nil
+        # If get_studied_node failed, try the old-fashioned way.
+        #puts "Studying tagname #{loceval} failed."
+      end
+      tname = @browser.get_eval(
+        'var ev=this.browserbot.findElement("' +
+        loceval + '");ev.tagName+"."+ev.type+";"+((ev.id != "" && window.document.getElementById(ev.id)==ev)?ev.id:"")').downcase
+
+      tname = tname.split(';',2)
+      # This modifies loceval in-place.
+      loceval[0,loceval.length] = "id=#{tname[1]}" if tname[1] != ''
+      return tname[0]
+    end
+
     # Execute the given block, and return false if it raises an exception.
     # Otherwise, return true.
     #
@@ -1336,7 +1751,7 @@ module Rsel
       rescue => e
         #puts e.message
         #puts e.backtrace
-        failure("#{e.message}")
+        failure("#{e.message}:<br>#{e.backtrace.join("\n")}")
       else
         return true
       end
@@ -1394,7 +1809,7 @@ module Rsel
     # @since 0.1.1
     #
     def skip_step?
-      return aborted? || !@conditional_stack.last
+      return aborted? || in_skipped_conditional?
     end
 
     # Presuming the current step should be skipped, what status should I return?
@@ -1403,7 +1818,7 @@ module Rsel
     #
     def skip_status
       return false if aborted?
-      return nil if !@conditional_stack.last
+      return nil if in_skipped_conditional?
     end