module Selenium
module Client
# Provide a more idiomatic API than the generated Ruby driver.
#
# Work in progress...
module Idiomatic
# 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
#
# TODO - Should be renamed 'text'
def text_content(locator)
string_command "getText", [locator,]
end
# Return the title of the current HTML page.
def title
string_command "getTitle"
end
# Returns the absolute URL of the current page.
def location
string_command "getLocation"
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
def wait_for_page(timeout_in_seconds=nil)
actual_timeout = timeout_in_seconds || default_timeout_in_seconds
remote_control_command "waitForPageToLoad", [actual_timeout * 1000,]
end
alias_method :wait_for_page_to_load, :wait_for_page
# 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
def wait_for_popup(window_id, timeout_in_seconds=nil)
actual_timeout = timeout_in_seconds || default_timeout_in_seconds
remote_control_command "waitForPopUp", [window_id, actual_timeout * 1000 ,]
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 (Prototype only)
# * wait :wait_for => :effects # will wait for all Prototype effects to be rendered
# * 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, :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, :element => 'a_locator', :text => 'some text' # will wait for the content of 'a_locator' to not be 'some text'
# * 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.
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[:timeout_in_seconds]
elsif options[:wait_for] == :element
wait_for_element options[:element], options[:timeout_in_seconds]
elsif options[:wait_for] == :no_element
wait_for_no_element options[:element], options[:timeout_in_seconds]
elsif options[:wait_for] == :text
wait_for_text options[:text], options[:element], options[:timeout_in_seconds]
elsif options[:wait_for] == :no_text
wait_for_no_text options[:text], options[:element], options[:timeout_in_seconds]
elsif options[:wait_for] == :effects
wait_for_effects options[:timeout_in_seconds]
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] == :condition
wait_for_condition options[:javascript], options[:timeout_in_seconds]
end
end
# Gets the entire text of the page.
def body_text
string_command "getBodyText"
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 :wait_for => :page # will wait for a new page to load
# * click :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 :wait_for => :ajax # will wait for all ajax requests to be completed (Prototype only)
# * click :wait_for => :effects # will wait for all Prototype effects to be rendered
# * click :wait_for => :element, :element => 'new_element_id' # will wait for an element to be present/appear
# * click :wait_for => :no_element, :element => 'new_element_id' # will wait for an element to be not be present/disappear
# * click :wait_for => :text, :text => 'some text' # will wait for some text to be present/appear
# * click :wait_for => :text, :element => 'a_locator', :text => 'some text' # will wait for the content of 'a_locator' to be 'some text'
# * click :wait_for => :no_text, :text => 'some text' # will wait for the text to be not be present/disappear
# * click :wait_for => :no_text, :element => 'a_locator', :text => 'some text' # will wait for the content of 'a_locator' to not be 'some text'
# * click :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.
def click(locator, options={})
remote_control_command "click", [locator,]
wait_for options
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
def text?(pattern)
boolean_command "isTextPresent", [pattern,]
end
# Verifies that the specified element is somewhere on the page.
#
# * 'locator' is an element locator
def element?(locator)
boolean_command "isElementPresent", [locator,]
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
def field(locator)
string_command "getValue", [locator,]
end
# Alias for +field+
def value(locator)
field locator
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
def checked?(locator)
boolean_command "isChecked", [locator,]
end
# Whether an alert occurred
def alert?
boolean_command "isAlertPresent"
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.
#
def alert
string_command "getAlert"
end
# Whether a confirmation has been auto-acknoledged (i.e. confirm() been called)
def confirmation?
boolean_command "isConfirmationPresent"
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.
def confirmation
string_command "getConfirmation"
end
# Whether a prompt occurred
def prompt?
boolean_command "isPromptPresent"
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.
def prompt
string_command "getPrompt"
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
def js_eval(script)
string_command "getEval", [script,]
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.
def remote_control_timeout_in_seconds=(timeout_in_seconds)
remote_control_command "setTimeout", [timeout_in_seconds * 1000,]
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"
def table_cell_text(tableCellAddress)
string_command "getTable", [tableCellAddress,]
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
def wait_for_condition(script, timeout_in_seconds = nil)
remote_control_command "waitForCondition", [script, (timeout_in_seconds || default_timeout_in_seconds) * 1000,]
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 (Prototype only)
# * go_back :wait_for => :effects # will wait for all Prototype effects to be rendered
# * 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 :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 :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
#
# Using options you can also define an explicit timeout (:timeout_in_seconds key). Otherwise the default driver timeout
# is used.
def go_back(options={})
remote_control_command "goBack"
wait_for options
end
# Return all cookies for the current page under test.
def cookies
string_command "getCookie"
end
# Returns the value of the cookie with the specified name, or throws an error if the cookie is not present.
#
# 'name' is the name of the cookie
def cookie(name)
string_command "getCookieByName", [name,]
end
# Returns true if a cookie with the specified name is present, or false otherwise.
#
# 'name' is the name of the cookie
def cookie?(name)
boolean_command "isCookiePresent", [name,]
end
# Create a new cookie whose path and domain are same with those of current page
# under test, unless you specified a path for this cookie explicitly.
#
# 'nameValuePair' is name and value of the cookie in a format "name=value"
# 'optionsString' is options for the cookie. Currently supported options include 'path', 'max_age' and 'domain'.
# the optionsString's format is "path=/path/, max_age=60, domain=.foo.com". The order of options are irrelevant, the unit of the value of 'max_age' is second. Note that specifying a domain that isn't a subset of the current domain will usually fail.
def create_cookie(name_value_pair, options="")
if options.kind_of? Hash
options = options.keys.collect {|key| "#{key}=#{options[key]}" }.sort.join(", ")
end
remote_control_command "createCookie", [name_value_pair,options,]
end
# Delete a named cookie with specified path and domain. Be careful; to delete a cookie, you
# need to delete it using the exact same path and domain that were used to create the cookie.
# If the path is wrong, or the domain is wrong, the cookie simply won't be deleted. Also
# note that specifying a domain that isn't a subset of the current domain will usually fail.
#
# Since there's no way to discover at runtime the original path and domain of a given cookie,
# we've added an option called 'recurse' to try all sub-domains of the current domain with
# all paths that are a subset of the current path. Beware; this option can be slow. In
# big-O notation, it operates in O(n*m) time, where n is the number of dots in the domain
# name and m is the number of slashes in the path.
#
# 'name' is the name of the cookie to be deleted
# 'optionsString' is options for the cookie. Currently supported options include 'path', 'domain' and 'recurse.' The optionsString's format is "path=/path/, domain=.foo.com, recurse=true". The order of options are irrelevant. Note that specifying a domain that isn't a subset of the current domain will usually fail.
def delete_cookie(name, options="")
if options.kind_of? Hash
ordered_keys = options.keys.sort {|a,b| a.to_s <=> b.to_s }
options = ordered_keys.collect {|key| "#{key}=#{options[key]}" }.join(", ")
end
remote_control_command "deleteCookie", [name,options,]
end
# Returns the IDs of all windows that the browser knows about.
def all_window_ids
string_array_command "getAllWindowIds"
end
# Returns the names of all windows that the browser knows about.
def all_window_names
string_array_command "getAllWindowNames"
end
# Returns the titles of all windows that the browser knows about.
def all_window_titles
string_array_command "getAllWindowTitles"
end
end
end
end