module Selenium::Client::Idiomatic
Provide a more idiomatic API than the generated Ruby driver.
Work in progress…
Public Instance Methods
# File lib/selenium/client/idiomatic.rb, line 480 def actual_timeout_in_milliseconds(timeout_in_seconds) actual_timeout = (timeout_in_seconds || default_timeout_in_seconds).to_i actual_timeout * 1000 end
Retrieves the message of a JavaScript alert generated during the previous action, or fail if there were no alerts.
Getting an alert has the same effect as manually clicking OK. If an alert is generated but you do not consume it with getAlert, the next Selenium action will fail.
Under Selenium, JavaScript alerts will NOT pop up a visible alert dialog.
Selenium does NOT support JavaScript alerts that are generated in a page's onload() event handler. In this case a visible dialog WILL be generated and Selenium will hang until someone manually clicks OK.
# File lib/selenium/client/idiomatic.rb, line 220 def alert string_command "getAlert" end
Whether an alert occurred
# File lib/selenium/client/idiomatic.rb, line 202 def alert? boolean_command "isAlertPresent" end
Returns the IDs of all windows that the browser knows about.
# File lib/selenium/client/idiomatic.rb, line 408 def all_window_ids string_array_command "getAllWindowIds" end
Returns the names of all windows that the browser knows about.
# File lib/selenium/client/idiomatic.rb, line 414 def all_window_names string_array_command "getAllWindowNames" end
Returns the titles of all windows that the browser knows about.
# File lib/selenium/client/idiomatic.rb, line 420 def all_window_titles string_array_command "getAllWindowTitles" end
Gets the entire text of the page.
# File lib/selenium/client/idiomatic.rb, line 115 def body_text string_command "getBodyText" end
Returns a string representation of the network traffic seen by the browser, including headers, AJAX requests, status codes, and timings. When this function is called, the traffic log is cleared, so the returned content is only the traffic seen since the last call.
The network traffic is returned in the format it was requested. Valid values are: :json, :xml, or :plain.
Warning: For #browser_network_traffic to work you need to start your browser session with the option “captureNetworkTraffic=true”, which will force ALL traffic to go to the Remote Control proxy even for more efficient browser modes like `*firefox` and `*safari`.
# File lib/selenium/client/idiomatic.rb, line 436 def browser_network_traffic(format = :plain) raise "format must be :plain, :json, or :xml" \ unless [:plain, :json, :xml].include?(format) remote_control_command "captureNetworkTraffic", [format.to_s] end
Allows choice of a specific XPath libraries for Xpath evualuation in the browser (e.g. to resolve XPath locators).
`library_name' can be:
* :ajaxslt : Google's library * :javascript-xpath : Cybozu Labs' faster library * :default : Selenium default library.
# File lib/selenium/client/idiomatic.rb, line 450 def browser_xpath_library=(library_name) raise "library name must be :ajaxslt, :javascript-xpath, or :default" \ unless [:ajaxslt, :'javascript-xpath', :default].include?(library_name) remote_control_command "useXpathLibrary", [library_name.to_s] end
Returns whether a toggle-button (checkbox/radio) is checked. Fails if the specified element doesn't exist or isn't a toggle-button.
-
'locator' is an element locator pointing to a checkbox or radio button
# File lib/selenium/client/idiomatic.rb, line 197 def checked?(locator) boolean_command "isChecked", [locator,] end
Clicks on a link, button, checkbox or radio button.
'locator' is an element locator
Using 'options' you can automatically wait for an event to happen after the click. e.g.
-
click “a_locator”, :wait_for => :page # will wait for a new page to load
-
click “a_locator”, :wait_for => :popup, :window => 'a window id' # will wait for a new popup window to appear. Also selects the popup window for you provide `:select => true`
-
click “a_locator”, :wait_for => :ajax # will wait for all ajax requests to be completed using semantics of default javascript framework
-
click “a_locator”, :wait_for => :ajax, :javascript_framework => :jquery # will wait for all ajax requests to be completed overriding default javascript framework
-
click “a_locator”, :wait_for => :effects # will wait for all javascript effects to be rendered using semantics of default javascript framework
-
click “a_locator”, :wait_for => :effects, :javascript_framework => :prototype # will wait for all javascript effects to be rendered overriding default javascript framework
-
click “a_locator”, :wait_for => :element, :element => 'new_element_id' # will wait for an element to be present/appear
-
click “a_locator”, :wait_for => :no_element, :element => 'new_element_id' # will wait for an element to be not be present/disappear
-
click “a_locator”, :wait_for => :text, :text => 'some text' # will wait for some text to be present/appear
-
click “a_locator”, :wait_for => :text, :text => /A Regexp/ # will wait for some text to be present/appear
-
click “a_locator”, :wait_for => :text, :element => 'a_locator', :text => 'some text' # will wait for the content of 'a_locator' to be 'some text'
-
click “a_locator”, :wait_for => :no_text, :text => 'some text' # will wait for the text to be not be present/disappear
-
click “a_locator”, :wait_for => :no_text, :text => /A Regexp/ # will wait for the text to be not be present/disappear
-
click “a_locator”, :wait_for => :no_text, :element => 'a_locator', :text => 'some text' # will wait for the content of 'a_locator' to not be 'some text'
-
click “a_locator”, :wait_for => :value, :element => 'a_locator', :value => 'some value' # will wait for the field value of 'a_locator' to be 'some value'
-
click “a_locator”, :wait_for => :no_value, :element => 'a_locator', :value => 'some value' # will wait for the field value of 'a_locator' to not be 'some value'
-
click “a_locator”, :wait_for => :visible, :element => 'a_locator' # will wait for element to be visible
-
click “a_locator”, :wait_for => :not_visible, :element => 'a_locator' # will wait for element to not be visible
-
click “a_locator”, :wait_for => :condition, :javascript => 'some expression' # will wait for the javascript expression to be true
Using options you can also define an explicit timeout (:timeout_in_seconds key). Otherwise the default driver timeout is used.
# File lib/selenium/client/idiomatic.rb, line 148 def click(locator, options={}) remote_control_command "click", [locator,] wait_for options end
Retrieves the message of a JavaScript confirmation dialog generated during the previous action.
By default, the confirm function will return true, having the same effect as manually clicking OK. This can be changed by prior execution of the chooseCancelOnNextConfirmation command.
If an confirmation is generated but you do not consume it with getConfirmation, the next Selenium action will fail.
NOTE: under Selenium, JavaScript confirmations will NOT pop up a visible dialog.
NOTE: Selenium does NOT support JavaScript confirmations that are generated in a page's onload() event handler. In this case a visible dialog WILL be generated and Selenium will hang until you manually click OK.
# File lib/selenium/client/idiomatic.rb, line 246 def confirmation string_command "getConfirmation" end
Whether a confirmation has been auto-acknoledged (i.e. confirm() been called)
# File lib/selenium/client/idiomatic.rb, line 225 def confirmation? boolean_command "isConfirmationPresent" end
Verifies that the specified element is somewhere on the page.
-
'locator' is an element locator
# File lib/selenium/client/idiomatic.rb, line 163 def element?(locator) boolean_command "isElementPresent", [locator,] end
Get execution delay in milliseconds, i.e. a pause delay following each selenium operation. By default, there is no such delay (value is 0).
# File lib/selenium/client/idiomatic.rb, line 468 def execution_delay string_command "getSpeed" end
Set the execution delay in milliseconds, i.e. a pause delay following each selenium operation. By default, there is no such delay.
Setting an execution can be useful to troubleshoot or capture videos
# File lib/selenium/client/idiomatic.rb, line 476 def execution_delay=(delay_in_milliseconds) remote_control_command "setSpeed", [delay_in_milliseconds] end
Gets the (whitespace-trimmed) value of an input field (or anything else with a value parameter). For checkbox/radio elements, the value will be “on” or “off” depending on whether the element is checked or not.
-
'locator' is an element locator
# File lib/selenium/client/idiomatic.rb, line 184 def field(locator) string_command "getValue", [locator,] end
Simulates the user clicking the “back” button on their browser. Using 'options' you can automatically wait for an event to happen after the click. e.g.
-
#go_back :wait_for => :page # will wait for a new page to load
-
#go_back :wait_for => :popup, :window => 'a window id' # will wait for a new popup window to appear. Also selects the popup window for you provide `:select => true`
-
#go_back :wait_for => :ajax # will wait for all ajax requests to be completed using semantics of default javascript framework
-
#go_back :wait_for => :ajax, :javascript_framework => :jquery # will wait for all ajax requests to be completed overriding default javascript framework
-
#go_back :wait_for => :effects # will wait for all javascript effects to be rendered using semantics of default javascript framework
-
#go_back :wait_for => :effects, :javascript_framework => :prototype # will wait for all javascript effects to be rendered overriding default javascript framework
-
#go_back :wait_for => :element, :element => 'new_element_id' # will wait for an element to be present/appear
-
#go_back :wait_for => :no_element, :element => 'new_element_id' # will wait for an element to be not be present/disappear
-
#go_back :wait_for => :text, :text => 'some text' # will wait for some text to be present/appear
-
#go_back “a_locator”, :wait_for => :text, :text => /A Regexp/ # will wait for some text to be present/appear
-
#go_back :wait_for => :text, :element => 'a_locator', :text => 'some text' # will wait for the content of 'a_locator' to be 'some text'
-
#go_back :wait_for => :no_text, :text => 'some text' # will wait for the text to be not be present/disappear
-
#go_back “a_locator”, :wait_for => :no_text, :text => /A Regexp/ # will wait for the text to be not be present/disappear
-
#go_back :wait_for => :no_text, :element => 'a_locator', :text => 'some text' # will wait for the content of 'a_locator' to not be 'some text'
-
#go_back :wait_for => :condition, :javascript => 'some expression' # will wait for the javascript expression to be true
-
#go_back :wait_for => :value, :element => 'a_locator', :value => 'some value' # will wait for the field value of 'a_locator' to be 'some value'
-
#go_back :wait_for => :visible, :element => 'a_locator' # will wait for element to be visible
-
#go_back :wait_for => :not_visible, :element => 'a_locator' # will wait for element to not be visible
-
#go_back :wait_for => :no_value, :element => 'a_locator', :value => 'some value' # will wait for the field value of 'a_locator' to not be 'some value'
Using options you can also define an explicit timeout (:timeout_in_seconds key). Otherwise the default driver timeout is used.
# File lib/selenium/client/idiomatic.rb, line 349 def go_back(options={}) remote_control_command "goBack" wait_for options end
Turn on/off the automatic hightlighting of the element driven or inspected by Selenium core. Useful when recording videos
# File lib/selenium/client/idiomatic.rb, line 460 def highlight_located_element=(enabled) boolean = (true == enabled) js_eval "selenium.browserbot.shouldHighlightLocatedElement = #{boolean}" end
Returns the result of evaluating the specified JavaScript snippet whithin the browser.
The snippet may have multiple lines, but only the result of the last line will be returned.
Note that, by default, the snippet will run in the context of the
“selenium” object itself, so this
will refer to the Selenium object. Use window
to
refer to the window of your application, e.g.
window.document.getElementById('foo')
If you need to
use a locator to refer to a single element in your application page, you
can use this.browserbot.findElement("id=foo")
where
“id=foo” is your locator.
-
'script' is the JavaScript snippet to run
# File lib/selenium/client/idiomatic.rb, line 283 def js_eval(script) string_command "getEval", [script,] end
Returns the absolute URL of the current page.
# File lib/selenium/client/idiomatic.rb, line 30 def location string_command "getLocation" end
Retrieves the message of a JavaScript question prompt dialog generated during the previous action.
Successful handling of the prompt requires prior execution of the answerOnNextPrompt command. If a prompt is generated but you do not get/verify it, the next Selenium action will fail.
NOTE: under Selenium, JavaScript prompts will NOT pop up a visible dialog.
NOTE: Selenium does NOT support JavaScript prompts that are generated in a page's onload() event handler. In this case a visible dialog WILL be generated and Selenium will hang until someone manually clicks OK.
# File lib/selenium/client/idiomatic.rb, line 268 def prompt string_command "getPrompt" end
Whether a prompt occurred
# File lib/selenium/client/idiomatic.rb, line 251 def prompt? boolean_command "isPromptPresent" end
Set the Remote Control timeout (as opposed to the client side driver timeout). This timout specifies the amount of time that Selenium Core will wait for actions to complete.
The default timeout is 30 seconds. 'timeout' is a timeout in seconds, after which the action will return with an error
Actions that require waiting include “open” and the “waitFor*” actions.
# File lib/selenium/client/idiomatic.rb, line 294 def remote_control_timeout_in_seconds=(timeout_in_seconds) remote_control_command "setTimeout", [actual_timeout_in_milliseconds(timeout_in_seconds),] end
Returns the text from a cell of a table. The cellAddress syntax tableLocator.row.column, where row and column start at 0.
-
'tableCellAddress' is a cell address, e.g. “foo.1.4”
# File lib/selenium/client/idiomatic.rb, line 302 def table_cell_text(tableCellAddress) string_command "getTable", [tableCellAddress,] end
Return the text content of an HTML element (rendered text shown to the user). Works for any HTML element that contains text.
This command uses either the textContent (Mozilla-like browsers) or the innerText (IE-like browsers) of the element, which is the rendered text shown to the user.
-
'locator' is an Selenium element locator
# File lib/selenium/client/idiomatic.rb, line 19 def text(locator) string_command "getText", [locator,] end
Verifies that the specified text pattern appears somewhere on the rendered page shown to the user.
-
'pattern' is a pattern to match with the text of the page
# File lib/selenium/client/idiomatic.rb, line 156 def text?(pattern) boolean_command "isTextPresent", [pattern,] end
Return the title of the current HTML page.
# File lib/selenium/client/idiomatic.rb, line 25 def title string_command "getTitle" end
Alias for field
# File lib/selenium/client/idiomatic.rb, line 189 def value(locator) field locator end
Determines if the specified element is visible. An element can be rendered invisible by setting the CSS “visibility” property to “hidden”, or the “display” property to “none”, either for the element itself or one if its ancestors. This method will fail if the element is not present.
'locator' is an element locator
# File lib/selenium/client/idiomatic.rb, line 174 def visible?(locator) boolean_command "isVisible", [locator,] end
Flexible wait semantics. ait is happening browser side. Useful for testing AJAX application.
-
wait :wait_for => :page # will wait for a new page to load
-
wait :wait_for => :popup, :window => 'a window id' # will wait for a new popup window to appear. Also selects the popup window for you provide `:select => true`
-
wait :wait_for => :ajax # will wait for all ajax requests to be completed using semantics of default javascript framework
-
wait :wait_for => :ajax, :javascript_framework => :jquery # will wait for all ajax requests to be completed overriding default javascript framework
-
wait :wait_for => :effects # will wait for all javascript effects to be rendered using semantics of default javascript framework
-
wait :wait_for => :effects, :javascript_framework => :prototype # will wait for all javascript effects to be rendered overriding default javascript framework
-
wait :wait_for => :element, :element => 'new_element_id' # will wait for an element to be present/appear
-
wait :wait_for => :no_element, :element => 'new_element_id' # will wait for an element to be not be present/disappear
-
wait :wait_for => :text, :text => 'some text' # will wait for some text to be present/appear
-
wait :wait_for => :text, :text => /A Regexp/ # will wait for some text to be present/appear
-
wait :wait_for => :text, :element => 'a_locator', :text => 'some text' # will wait for the content of 'a_locator' to be 'some text'
-
wait :wait_for => :no_text, :text => 'some text' # will wait for the text to be not be present/disappear
-
wait :wait_for => :no_text, :text => /A Regexp/ # will wait for the text to be not be present/disappear
-
wait :wait_for => :no_text, :element => 'a_locator', :text => 'some text' # will wait for the content of 'a_locator' to not be 'some text'
-
wait :wait_for => :value, :element => 'a_locator', :value => 'some value' # will wait for the field value of 'a_locator' to be 'some value'
-
wait :wait_for => :no_value, :element => 'a_locator', :value => 'some value' # will wait for the field value of 'a_locator' to not be 'some value'
-
wait :wait_for => :visible, :element => 'a_locator' # will wait for element to be visible
-
wait :wait_for => :not_visible, :element => 'a_locator' # will wait for element to not be visible
-
wait :wait_for => :condition, :javascript => 'some expression' # will wait for the javascript expression to be true
Using options you can also define an explicit timeout (:timeout_in_seconds key). Otherwise the default driver timeout is used.
# File lib/selenium/client/idiomatic.rb, line 83 def wait_for(options) if options[:wait_for] == :page wait_for_page options[:timeout_in_seconds] elsif options[:wait_for] == :ajax wait_for_ajax options elsif options[:wait_for] == :element wait_for_element options[:element], options elsif options[:wait_for] == :no_element wait_for_no_element options[:element], options elsif options[:wait_for] == :text wait_for_text options[:text], options elsif options[:wait_for] == :no_text wait_for_no_text options[:text], options elsif options[:wait_for] == :effects wait_for_effects options elsif options[:wait_for] == :popup wait_for_popup options[:window], options[:timeout_in_seconds] select_window options[:window] if options[:select] elsif options[:wait_for] == :value wait_for_field_value options[:element], options[:value], options elsif options[:wait_for] == :no_value wait_for_no_field_value options[:element], options[:value], options elsif options[:wait_for] == :visible wait_for_visible options[:element], options elsif options[:wait_for] == :not_visible wait_for_not_visible options[:element], options elsif options[:wait_for] == :condition wait_for_condition options[:javascript], options[:timeout_in_seconds] end end
Runs the specified JavaScript snippet repeatedly until it evaluates to “true”. The snippet may have multiple lines, but only the result of the last line will be considered.
Note that, by default, the snippet will be run in the runner's test
window, not in the window of your application. To get the window of your
application, you can use the JavaScript snippet
selenium.browserbot.getCurrentWindow()
, and then run your
JavaScript in there
-
'script' is the JavaScript snippet to run
-
'timeout_in_seconds' is a timeout in seconds, after which this command will return with an error
# File lib/selenium/client/idiomatic.rb, line 318 def wait_for_condition(script, timeout_in_seconds = nil) remote_control_command "waitForCondition", [script, actual_timeout_in_milliseconds(timeout_in_seconds),] end
Waits for a new page to load.
Selenium constantly keeps track of new pages loading, and sets a “newPageLoaded” flag when it first notices a page load. Running any other Selenium command after turns the flag to false. Hence, if you want to wait for a page to load, you must wait immediately after a Selenium command that caused a page-load.
-
'timeout_in_seconds' is a timeout in seconds, after which this command will return with an error
# File lib/selenium/client/idiomatic.rb, line 44 def wait_for_page(timeout_in_seconds=nil) remote_control_command "waitForPageToLoad", [actual_timeout_in_milliseconds(timeout_in_seconds),] end
Waits for a popup window to appear and load up.
window_id is the JavaScript window “name” of the window that will appear (not the text of the title bar) timeout_in_seconds is a timeout in seconds, after which the action will return with an error
# File lib/selenium/client/idiomatic.rb, line 54 def wait_for_popup(window_id, timeout_in_seconds=nil) remote_control_command "waitForPopUp", [window_id, actual_timeout_in_milliseconds(timeout_in_seconds) ,] end