Class: Rsel::SeleniumTest

Inherits:
Object
  • Object
show all
Includes:
Support
Defined in:
lib/rsel/selenium_test.rb

Overview

Main Selenium-test class, and wrapper for all Selenium method calls. This class is intended to be instantiated in a FitNesse / Slim script table. May be customized or extended using a subclass.

@note: Function names beginning with the words 'check', 'ensure', 'reject', 'note', 'show', or 'start' cannot be called from a Slim script table, since these are keywords that receive special handling by Slim.

Examples:

!| script | selenium test | http://www.example.com/ |
| script | selenium test | !-http://www.example.com/-! |

Instance Attribute Summary (collapse)

Instance Method Summary (collapse)

Methods included from Support

#apply_scope, #csspath, #escape_for_hash, #failed_within, #globify, #normalize_ids, #result_within, #selenium_compare, #string_is_true?, #strip_tags, #xpath, #xpath_expressions, #xpath_row_containing, #xpath_sanitize

Constructor Details

- (SeleniumTest) initialize(url, options = {})

Initialize a test, connecting to the given Selenium server.

Examples:

| script | selenium test | http://site.to.test/ |
| script | selenium test | http://site.to.test/ | !{host:192.168.0.3} |
| script | selenium test | http://site.to.test/ | !{host:192.168.0.3, port:4445} |
| script | selenium test | http://site.to.test/ | !{stop_on_failure:true} |
| script | selenium test | http://site.to.test/ | !{study:Auto} |

Options Hash (options):

  • :host (String)

    IP address or hostname where selenium-server is running

  • :port (String)

    Port number of selenium-server

  • :browser (String)

    Which browser to run. Should be a string like '*firefox' (default), '*googlechrome', '*opera', '*iexplore', '*safari' etc.

  • :stop_on_failure (String, Boolean)

    true or 'true' to abort the test when a failure occurs; false or 'false' to continue execution when failure occurs.

  • :study (String, Integer)

    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.

  • :timeout (String, Integer)

    Default timeout in seconds. This determines how long the open method 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.



64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
# File 'lib/rsel/selenium_test.rb', line 64

def initialize(url, options={})
  # Strip HTML tags from URL
  @url = strip_tags(url)
  @browser = Selenium::Client::Driver.new(
    :host => options[:host] || 'localhost',
    :port => options[:port] || 4444,
    :browser => options[:browser] || '*firefox',
    :url => @url,
    :default_timeout_in_seconds => options[:timeout] || 300)
  # Accept Booleans or strings, case-insensitive
  if options[:stop_on_failure].to_s =~ /true/i
    @stop_on_failure = true
  else
    @stop_on_failure = false
  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

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

- (Object) method_missing(method, *args, &block)

Invoke a missing method. If a method is called on a SeleniumTest instance, and that method is not explicitly defined, this method will check to see whether the underlying Selenium::Client::Driver 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



1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
# File 'lib/rsel/selenium_test.rb', line 1422

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
      # 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)
      # Not a Boolean return value or string--assume passing
      return true
    end
  else
    super
  end
end

Instance Attribute Details

- (Object) browser (readonly)

Returns the value of attribute browser



93
94
95
# File 'lib/rsel/selenium_test.rb', line 93

def browser
  @browser
end

- (Object) found_failure

Returns the value of attribute found_failure



93
94
95
# File 'lib/rsel/selenium_test.rb', line 93

def found_failure
  @found_failure
end

- (Object) stop_on_failure

Returns the value of attribute stop_on_failure



93
94
95
# File 'lib/rsel/selenium_test.rb', line 93

def stop_on_failure
  @stop_on_failure
end

- (Object) url (readonly)

Returns the value of attribute url



93
94
95
# File 'lib/rsel/selenium_test.rb', line 93

def url
  @url
end

Instance Method Details

- (Object) begin_scenario

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 whether those scenarios passed or failed.

Examples:

| Begin scenario |

Since:

  • 0.0.9



237
238
239
240
241
# File 'lib/rsel/selenium_test.rb', line 237

def begin_scenario
  @found_failure = false
  @errors = []
  return true
end

- (Object) begin_study

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.



178
179
180
181
182
183
# File 'lib/rsel/selenium_test.rb', line 178

def begin_study
  return skip_status if skip_step?
  fail_on_exception do
    @study.begin_section { page_to_study }
  end
end

- (Object) button_exists(locator, scope = {})

Ensure that a button exists on the page.

Examples:

| Button | Search | exists |
| Button | Search | exists | !{within:members} |

Since:

  • 0.0.2



571
572
573
574
575
576
577
578
579
580
# File 'lib/rsel/selenium_test.rb', line 571

def button_exists(locator, scope={})
  return skip_status if skip_step?
  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

- (Object) checkbox_is_disabled(locator, scope = {})

Verify that a given checkbox is disabled (unchecked)

Examples:

| Checkbox | send me spam | is disabled |
| Checkbox | send me spam | is disabled | !{within:opt_in} |


868
869
870
871
872
873
874
875
876
877
878
879
# File 'lib/rsel/selenium_test.rb', line 868

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
    failure "Can't identify checkbox #{locator}"
  else
    return !enabled
  end
end

- (Object) checkbox_is_enabled(locator, scope = {})

Verify that a given checkbox is enabled (checked)

Examples:

| Checkbox | send me spam | is enabled |
| Checkbox | send me spam | is enabled | !{within:opt_in} |


816
817
818
819
820
821
822
823
824
825
826
827
# File 'lib/rsel/selenium_test.rb', line 816

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
    failure "Can't identify checkbox #{locator}"
  else
    return enabled
  end
end

- (Object) click(locator, scope = {})

Click on a link or button, and wait for a page to load.

Examples:

| Click | Next   |
| Click | Logout |
| Click; | Logout | !{within:header} |


709
710
711
712
713
714
# File 'lib/rsel/selenium_test.rb', line 709

def click(locator, scope={})
  return skip_status if skip_step?
  fail_on_exception do
    @browser.click(loc(locator, 'link_or_button', scope))
  end
end

- (Object) click_back

Click the Back button to navigate to the previous page.

Examples:

| Click back |


282
283
284
285
286
287
288
# File 'lib/rsel/selenium_test.rb', line 282

def click_back
  return skip_status if skip_step?
  end_study
  fail_on_exception do
    @browser.go_back
  end
end

- (Object) click_button(locator, scope = {}) Also known as: press

Press a button. Passes if the button exists and is not disabled. Fails if the button is not found, or is disabled.

Examples:

| Click | Search | button |
| Press | Login |
| Click | Search | button | !{within:customers} |


751
752
753
754
755
756
757
# File 'lib/rsel/selenium_test.rb', line 751

def click_button(locator, scope={})
  return skip_status if skip_step?
  button = loc(locator, 'button', scope)
  fail_on_exception do
    ensure_editable(button) && @browser.click(button)
  end
end

Click on a link.

Examples:

| Click | Logout | link |
| Follow | Logout |
| Click | Logout | link | !{within:header} |
| Click | Edit | link | !{in_row:Eric} |


729
730
731
732
733
734
# File 'lib/rsel/selenium_test.rb', line 729

def click_link(locator, scope={})
  return skip_status if skip_step?
  fail_on_exception do
    @browser.click(loc(locator, 'link', scope))
  end
end

- (Object) close_browser(show_errors = '')

Stop the session and close the browser window. Show error messages in an exception if requested.

Examples:

| Close browser |
| Close browser | and show errors |
| Close browser | without showing errors |


134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
# File 'lib/rsel/selenium_test.rb', line 134

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;')
  end
  return true
end

- (Object) continue_study

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.)



206
207
208
209
# File 'lib/rsel/selenium_test.rb', line 206

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

- (Object) disable_checkbox(locator, scope = {})

Disable (uncheck) a checkbox by clicking on it. If the checkbox is already disabled, do nothing. Passes if the checkbox exists and is editable. Fails if the checkbox is not found, or is not editable.

Examples:

| Disable | Send me spam | checkbox |
| Disable | Send me spam | checkbox | !{within:opt_in} |


796
797
798
799
800
801
802
# File 'lib/rsel/selenium_test.rb', line 796

def disable_checkbox(locator, scope={})
  return skip_status if skip_step?
  cb = loc(locator, 'checkbox', scope)
  fail_on_exception do
    ensure_editable(cb) && checkbox_is_enabled(cb) && @browser.click(cb)
  end
end

- (Object) do_not_see(text, scope = nil)

Ensure that the given text does not appear on the current page.

Examples:

| Do not see | Take a hike |


356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
# File 'lib/rsel/selenium_test.rb', line 356

def do_not_see(text, scope=nil)
  return skip_status if skip_step?
  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

- (Object) do_not_see_title(title)

Ensure that the current page does not have the given title text.

Examples:

| Do not see title | Someone else's homepage |


484
485
486
487
# File 'lib/rsel/selenium_test.rb', line 484

def do_not_see_title(title)
  return skip_status if skip_step?
  pass_if !(@browser.get_title == title)
end

- (Object) do_not_see_within_seconds(text, seconds = -1,, scope = nil)

Ensure that the given text does not appear on the current page, eventually.

Examples:

| Click | close | button | !{within:popup_ad} |
| Do not see | advertisement | within | 10 | seconds |

Since:

  • 0.1.1



434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
# File 'lib/rsel/selenium_test.rb', line 434

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
  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

Check whether an option is currently selected in a dropdown/combo box.

Examples:

| Dropdown | Height | equals | Tall |

Since:

  • 0.0.2



989
990
991
992
993
994
995
996
997
998
999
# File 'lib/rsel/selenium_test.rb', line 989

def dropdown_equals(locator, option, scope={})
  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
    pass_if selected == option, "Dropdown equals '#{selected}', not '#{option}'"
  end
end

Check whether an option exists in a dropdown/combo box.

Examples:

| Dropdown | Height | includes | Tall |

Since:

  • 0.0.2



964
965
966
967
968
969
970
971
972
973
974
# File 'lib/rsel/selenium_test.rb', line 964

def dropdown_includes(locator, option, scope={})
  return skip_status if skip_step?
  # TODO: Apply scope
  dropdown = XPath::HTML.select(locator)
  opt = dropdown[XPath::HTML.option(option)]
  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

- (Object) enable_checkbox(locator, scope = {})

Enable (check) a checkbox by clicking on it. If the checkbox is already enabled, do nothing. Passes if the checkbox exists and is editable. Fails if the checkbox is not found, or is not editable.

Examples:

| Enable | Send me spam | checkbox |
| Enable | Send me spam | checkbox | !{within:opt_in} |


774
775
776
777
778
779
780
# File 'lib/rsel/selenium_test.rb', line 774

def enable_checkbox(locator, scope={})
  return skip_status if skip_step?
  cb = loc(locator, 'checkbox', scope)
  fail_on_exception do
    ensure_editable(cb) && checkbox_is_disabled(cb) && @browser.click(cb)
  end
end

- (Object) end_if

End an if block.

Since:

  • 0.1.1



1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
# File 'lib/rsel/selenium_test.rb', line 1556

def end_if
  return false if aborted?
  # If there was no prior matching if, fail.
  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 true
end

- (Object) end_scenario

End the current scenario. For now, this does not do anything, but is merely provided for symmetry with #begin_scenario.

Examples:

| End scenario |

Since:

  • 0.0.9



252
253
254
255
# File 'lib/rsel/selenium_test.rb', line 252

def end_scenario
  end_study
  return true
end

- (Object) end_study

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!



195
196
197
198
199
# File 'lib/rsel/selenium_test.rb', line 195

def end_study
  @study.end_section
  return skip_status if skip_step?
  return true
end

- (Object) errors

Show any current error messages. Also clears the error message log.

Examples:

| Show | errors |

Since:

  • 0.1.1



158
159
160
161
162
# File 'lib/rsel/selenium_test.rb', line 158

def errors
  current_errors = @errors
  @errors = []
  return current_errors.join("\n")
end

- (Object) field_contains(locator, text, scope = {})

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.

Examples:

| Field | First name | contains | Eric |


661
662
663
664
665
666
667
668
669
670
671
# File 'lib/rsel/selenium_test.rb', line 661

def field_contains(locator, text, scope={})
  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
    pass_if field.include?(text), "Field contains '#{field}', not '#{text}'"
  end
end

- (Object) field_equals(locator, text, scope = {})

Verify that a text field's value equals the given text. The value must match exactly.

Examples:

| Field | First name | equals | Eric |
| Field | First name | equals; | Eric | !{within:contact} |


686
687
688
689
690
691
692
693
694
695
696
# File 'lib/rsel/selenium_test.rb', line 686

def field_equals(locator, text, scope={})
  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
    pass_if field == text, "Field contains '#{field}', not '#{text}'"
  end
end

- (Object) field_equals_among(field, value, ids = {}, scope = {})

Check a value (with #set_field) in the named field, based on the given name/value pairs. Uses Rsel::Support#escape_for_hash to allow certain characters in FitNesse.

Since:

  • 0.1.1



1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
# File 'lib/rsel/selenium_test.rb', line 1297

def field_equals_among(field, value, ids={}, scope={})
  return skip_status if skip_step?
  # FitNesse passes in "" for an empty field. Fix it.
  ids = {} if ids == ""

  normalize_ids(ids)

  if ids[field.downcase]
    return generic_field_equals(escape_for_hash(ids[field.downcase]), value, scope)
  else
    return generic_field_equals(field, value, scope)
  end
end

- (Object) fields_equal(fields = {}, scope = {})

Check values (with #set_field) in the named fields of a hash, based on the given name/value pairs. Uses Rsel::Support#escape_for_hash to allow certain characters in FitNesse. Note: Order of entries is not guaranteed, and depends on the version of Ruby on your server!

Since:

  • 0.1.1



1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
# File 'lib/rsel/selenium_test.rb', line 1322

def fields_equal(fields={}, scope={})
  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|
    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

- (Object) fields_equal_among(fields = {}, ids = {}, scope = {})

Check values (with #set_field) in the named fields, based on the given name/value pairs, and with mapping of names in the ids field. Uses Rsel::Support#escape_for_hash to allow certain characters in FitNesse. Note: Order of entries is not guaranteed, and depends on the version of Ruby on your server!

Examples:

Suppose you have a nasty form whose fields have nasty locators.
Suppose further that you want to fill in this form, many times, filling
in different fields different ways.
Begin by creating a Scenario table:

    | scenario | Check nasty form fields | values |
    | fields equal | @values | among | !{Name:id=nasty_field_name_1,Email:id=nasty_field_name_2,E-mail:id=nasty_field_name_2,Send me spam:id=nasty_checkbox_name_1} |

Using that you can now say something like:

    | Check nasty form fields | !{Name:Ken,email:ken@kensaddress.com,send me spam: no} |

Or:

    | Check nasty form fields | !{Name:Ken,Send me Spam: no} |

Or:

    | Check nasty form fields | !{name:Ken,e-mail:,SEND ME SPAM: yes} |

Since:

  • 0.1.1



1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
# File 'lib/rsel/selenium_test.rb', line 1384

def fields_equal_among(fields={}, ids={}, scope={})
  return skip_status if skip_step?
  # FitNesse passes in "" for an empty field. Fix it.
  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|
    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

- (Object) fill_in_with(locator, text, scope = {})

Fill in a field with the given text. Passes if the field exists and is editable. Fails if the field is not found, or is not editable.

Examples:

| Fill in | First name | with | Eric |


645
646
647
648
# File 'lib/rsel/selenium_test.rb', line 645

def fill_in_with(locator, text, scope={})
  return skip_status if skip_step?
  type_into_field(text, locator, scope)
end

- (Object) generic_field_equals(locator, value = '', scope = {})

A generic way to check any field, of any type. (Just about.) Kind of nasty since it needs to use Javascript on the page.

Types accepted:

  • a*
  • button*
  • input
    • type=button*
    • type=checkbox
    • type=image*
    • type=radio*
    • type=reset*
    • type=submit*
    • type=text
  • select
  • textarea

* Value is ignored: this control type is just clicked/selected.

Since:

  • 0.1.1



1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
# File 'lib/rsel/selenium_test.rb', line 1254

def generic_field_equals(locator, value='', scope={})
  return skip_status if skip_step?
  fail_on_exception do
    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)
    when 'input.radio'
      if string_is_true?(value)
        return radio_is_enabled(loceval)
      else
        return radio_is_disabled(loceval)
      end
    when 'input.checkbox'
      if string_is_true?(value)
        return checkbox_is_enabled(loceval)
      else
        return checkbox_is_disabled(loceval)
      end
    when /^select\./
      return dropdown_equals(loceval, value)
    else
      return failure("Unidentified field for comparison: #{locator}.")
    end
  end
end

- (Object) if_i_see(text)

If I see the given text, do the steps until I see an otherwise or end_if. Otherwise do not do those steps.

Examples:

| If I see | pop-over ad |
| Click | Close | button |
| End if |

Since:

  • 0.1.1



1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
# File 'lib/rsel/selenium_test.rb', line 1494

def if_i_see(text)
  return false if aborted?
  cond = false
  begin
    cond = @browser.text?(text)
  rescue
    # Something went wrong.  Therefore, I did not see the text.
    cond = false
  end
  return push_conditional(cond)
end

- (Object) if_is(text, expected)

If the first parameter is the same as the second, do the steps until I see an otherwise or end_if. Otherwise do not do those steps.

Examples:

| $name= | Get value | id=response_field |
| If | $name | is | George |
| Type | Hi, George. | into | chat | field |
| Otherwise |
| Type | Go away! Bring me George! | into | chat | field |
| End if |

Since:

  • 0.1.1



1547
1548
1549
1550
# File 'lib/rsel/selenium_test.rb', line 1547

def if_is(text, expected)
  return false if aborted?
  return push_conditional(selenium_compare(text, expected))
end

- (Object) if_parameter(text)

If the given parameter is "yes" or "true", do the steps until I see an otherwise or end_if. Otherwise do not do those steps.

Examples:

| If parameter | ${spam_me} |
| Enable | Send me spam | checkbox |
| See | Email: | within | 10 | seconds |
| Type | ${spam_me_email} | into field | spammable_email |
| End if |

Since:

  • 0.1.1



1522
1523
1524
1525
# File 'lib/rsel/selenium_test.rb', line 1522

def if_parameter(text)
  return false if aborted?
  return push_conditional(string_is_true?(text))
end

Ensure that a link exists on the page.

Examples:

| Link | Logout | exists |
| Link | Logout | exists | !{within:header} |

Since:

  • 0.0.2



546
547
548
549
550
551
552
553
554
555
# File 'lib/rsel/selenium_test.rb', line 546

def link_exists(locator, scope={})
  return skip_status if skip_step?
  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

- (Object) maximize_browser

Maximize the browser window. May not work in some browsers.

Examples:

| Maximize browser |


310
311
312
313
# File 'lib/rsel/selenium_test.rb', line 310

def maximize_browser
  @browser.window_maximize
  return true
end

- (Object) open_browser

Start the session and open a browser to the URL defined at the start of the test. If a browser session is already open, just return true.

Examples:

| Open browser |

Raises:



105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
# File 'lib/rsel/selenium_test.rb', line 105

def open_browser
  return true if @browser.session_started?
  begin
    @browser.start_new_browser_session
  rescue
    raise StopTestCannotConnect,
      "Cannot connect to Selenium server at #{@browser.host}:#{@browser.port}"
  else
    visit @url
  end

  # Use javascript-xpath for IE, since it's a lot faster than the default
  if @browser.browser_string == '*iexplore'
    @browser.use_xpath_library('javascript-xpath')
  end

  # Make Selenium highlight elements whenever it locates them
  @browser.highlight_located_element = true
end

- (Object) otherwise

The else case to match any if.

| if parameter | $login_by_phone | | type | $login | into field | phone_number | | otherwise | | type | $login | into field | login | | end if |

Since:

  • 0.1.1



1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
# File 'lib/rsel/selenium_test.rb', line 1578

def otherwise
  return false if aborted?
  # If there was no prior matching if, fail.
  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 in_nil_conditional?

  last_stack = @conditional_stack.pop
  @conditional_stack.push !last_stack
  return true if @conditional_stack.last == true
  return nil if @conditional_stack.last == false
  return failure
end

- (Object) page_loads_in_seconds_or_less(seconds)

Wait some number of seconds for the current page request to finish. Fails if the page does not finish loading within the specified time.

Examples:

| Page loads in | 10 | seconds or less |


1027
1028
1029
1030
1031
1032
1033
# File 'lib/rsel/selenium_test.rb', line 1027

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
end

- (Object) pause_seconds(seconds) Also known as: pause_secs

Pause for a certain number of seconds.

Examples:

| Pause | 5 | seconds |


1010
1011
1012
1013
1014
# File 'lib/rsel/selenium_test.rb', line 1010

def pause_seconds(seconds)
  return skip_status if skip_step?
  sleep seconds.to_i
  return true
end

- (Object) radio_is_disabled(locator, scope = {})

Verify that a given radio button is disabled (unchecked)

Examples:

| Radio | medium | is disabled |
| Radio | medium | is disabled | !{within:shirt_size} |

Since:

  • 0.0.4



895
896
897
898
899
900
901
902
903
904
905
906
# File 'lib/rsel/selenium_test.rb', line 895

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
    failure "Can't identify radio #{locator}"
  else
    return !enabled
  end
end

- (Object) radio_is_enabled(locator, scope = {})

Verify that a given radio button is enabled (checked)

Examples:

| Radio | medium | is enabled |
| Radio | medium | is enabled | !{within:shirt_size} |

Since:

  • 0.0.4



843
844
845
846
847
848
849
850
851
852
853
854
# File 'lib/rsel/selenium_test.rb', line 843

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
    failure "Can't identify radio #{locator}"
  else
    return enabled
  end
end

- (Object) refresh_page

Reload the current page.

Examples:

| Refresh page |


296
297
298
299
300
301
302
# File 'lib/rsel/selenium_test.rb', line 296

def refresh_page
  return skip_status if skip_step?
  end_study
  fail_on_exception do
    @browser.refresh
  end
end

- (Object) reset_conditionals

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



1599
1600
1601
# File 'lib/rsel/selenium_test.rb', line 1599

def reset_conditionals
  @conditional_stack = [true]
end

- (Boolean) respond_to?(orgmethod, include_private = false)

Return true if SeleniumTest explicitly responds to a given method name, or if the underlying Selenium::Client::Driver instance can respond to it. This is a counterpart to #method_missing, used for checking whether a given method can be called on this instance.

Since:

  • 0.0.6



1469
1470
1471
1472
1473
1474
1475
1476
1477
# File 'lib/rsel/selenium_test.rb', line 1469

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
    super
  end
end

- (Object) row_exists(cells)

Ensure that a table row with the given cell values exists. Order does not matter as of v0.1.1.

Examples:

| Row exists | First, Middle, Last, Email |
| Row | First, Last, Middle, Email | exists |

Since:

  • 0.0.3



596
597
598
599
600
601
602
603
604
605
# File 'lib/rsel/selenium_test.rb', line 596

def row_exists(cells)
  return skip_status if skip_step?
  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

- (Object) see(text, scope = nil)

Ensure that the given text appears on the current page.

Examples:

| See | Welcome, Marcus |


327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
# File 'lib/rsel/selenium_test.rb', line 327

def see(text, scope=nil)
  return skip_status if skip_step?
  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

- (Object) see_alert_within_seconds(text = nil, seconds = -1))

Ensure that an alert appears, optionally having the given text, within the given time or the default timeout.

Examples:

| see alert within seconds |
  Validates any alert within the default timeout.
| 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



508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
# File 'lib/rsel/selenium_test.rb', line 508

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

- (Object) see_title(title)

Ensure that the current page has the given title text.

Examples:

| See title | Our Homepage |


466
467
468
469
470
471
472
473
# File 'lib/rsel/selenium_test.rb', line 466

def see_title(title)
  return skip_status if skip_step?
  # 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

- (Object) see_within_seconds(text, seconds = -1,, scope = nil)

Ensure that the given text appears on the current page, eventually.

Examples:

| 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 | !{within:terminal} |

Since:

  • 0.1.1



397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
# File 'lib/rsel/selenium_test.rb', line 397

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
  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

- (Object) select_from_dropdown(option, locator, scope = {})

Select an option from a dropdown/combo box. Passes if the dropdown exists, is editable, and includes the given option. Fails if the dropdown is not found, the option is not found, or the dropdown is not editable.

Examples:

| Select | Tall | from | Height | dropdown |
| Select | Tall | from dropdown | Height |


943
944
945
946
947
948
949
# File 'lib/rsel/selenium_test.rb', line 943

def select_from_dropdown(option, locator, scope={})
  return skip_status if skip_step?
  dropdown = loc(locator, 'select', scope)
  fail_on_exception do
    ensure_editable(dropdown) && @browser.select(dropdown, option)
  end
end

- (Object) select_radio(locator, scope = {})

Select a radio button. Passes if the radio button exists and is editable. Fails if the radiobutton is not found, or is not editable.

Examples:

| Select | female | radio |
| Select | female | radio | !{within:gender} |


921
922
923
924
925
926
927
# File 'lib/rsel/selenium_test.rb', line 921

def select_radio(locator, scope={})
  return skip_status if skip_step?
  radio = loc(locator, 'radio_button', scope)
  fail_on_exception do
    ensure_editable(radio) && @browser.click(radio)
  end
end

- (Object) set_field(locator, value = '', scope = {})

A generic way to fill in any field, of any type. (Just about.) Kind of nasty since it needs to use Javascript on the page.

Types accepted:

  • a*
  • button*
  • input
    • type=button*
    • type=checkbox
    • type=image*
    • type=radio*
    • type=reset*
    • type=submit*
    • type=text
  • select
  • textarea

* Value is ignored: this control type is just clicked/selected.

Since:

  • 0.1.1



1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
# File 'lib/rsel/selenium_test.rb', line 1065

def set_field(locator, value='', scope={})
  return skip_status if skip_step?
  fail_on_exception do
    loceval = loc(locator, 'field', scope)
    mytagname = ''
    begin
      mytagname = tagname(loceval)
    rescue
      loceval = loc(locator, 'link_or_button', scope)
      mytagname = tagname(loceval)
    end
    #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'
      return select_radio(loceval)
    when 'input.checkbox'
      if string_is_true?(value)
        return enable_checkbox(loceval)
      else
        return disable_checkbox(loceval)
      end
    when /^select\./
      return select_from_dropdown(value, loceval)
    when /^(a|button)\./,'input.button','input.submit','input.image','input.reset'
      return click(loceval)
    else
      return failure("Unidentified field #{locator}.")
    end
  end
end

- (Object) set_field_among(field, value, ids = {}, scope = {})

Set a value (with #set_field) in the named field, based on the given name/value pairs. Uses Rsel::Support#escape_for_hash to allow certain characters in FitNesse.

Since:

  • 0.1.1



1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
# File 'lib/rsel/selenium_test.rb', line 1115

def set_field_among(field, value, ids={}, scope={})
  return skip_status if skip_step?
  # FitNesse passes in "" for an empty field. Fix it.
  ids = {} if ids == ""

  normalize_ids(ids)

  if ids[field.downcase]
    return set_field(escape_for_hash(ids[field.downcase]), value, scope)
  else
    return set_field(field, value, scope)
  end
end

- (Object) set_fields(fields = {}, scope = {})

Set values (with #set_field) in the named fields of a hash, based on the given name/value pairs. Uses Rsel::Support#escape_for_hash to allow certain characters in FitNesse. Note: Order of entries is not guaranteed, and depends on the version of Ruby on your server!

Since:

  • 0.1.1



1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
# File 'lib/rsel/selenium_test.rb', line 1140

def set_fields(fields={}, scope={})
  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

- (Object) set_fields_among(fields = {}, ids = {}, scope = {})

Set values (with #set_field) in the named fields, based on the given name/value pairs, and with mapping of names in the ids field. Uses Rsel::Support#escape_for_hash to allow certain characters in FitNesse. Note: Order of entries is not guaranteed, and depends on the version of Ruby on your server!

Examples:

Suppose you have a nasty form whose fields have nasty locators. Suppose
further that you want to fill in this form, many times, filling in
different fields different ways. Begin by creating a Scenario table:

    | scenario | Set nasty form fields | values |
    | Set | @values | fields among | !{Name:id=nasty_field_name_1,Email:id=nasty_field_name_2,E-mail:id=nasty_field_name_2,Send me spam:id=nasty_checkbox_name_1} |

Using that you can now say something like:

    | Set nasty form fields | !{Name:Ken,email:ken@kensaddress.com,send me spam: no} |

Or:

    | Set nasty form fields | !{Name:Ken,Send me Spam: no} |

Or:

    | Set nasty form fields | !{name:Ken,e-mail:,SEND ME SPAM: yes} |

Since:

  • 0.1.1



1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
# File 'lib/rsel/selenium_test.rb', line 1200

def set_fields_among(fields={}, ids={}, scope={})
  return skip_status if skip_step?
  # FitNesse passes in "" for an empty field. Fix it.
  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

- (Object) set_fields_study_min(level = nil)

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.



219
220
221
222
223
224
225
# File 'lib/rsel/selenium_test.rb', line 219

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

- (Object) type_into_field(text, locator, scope = {})

Type a value into the given field. Passes if the field exists and is editable. Fails if the field is not found, or is not editable.

Examples:

| Type | Dale | into | First name | field |
| Type | Dale | into | First name | field | !{within:contact} |


623
624
625
626
627
628
629
# File 'lib/rsel/selenium_test.rb', line 623

def type_into_field(text, locator, scope={})
  return skip_status if skip_step?
  field = loc(locator, 'field', scope)
  fail_on_exception do
    ensure_editable(field) && @browser.type(field, text)
  end
end

- (Object) visit(path_or_url)

Load an absolute URL or a relative path in the browser.

Examples:

| Visit | http://www.automation-excellence.com |
| Visit | /software |


268
269
270
271
272
273
274
# File 'lib/rsel/selenium_test.rb', line 268

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
end