Module | Selenium::Client::Idiomatic
In: | lib/selenium/client/idiomatic.rb

Provide a more idiomatic API than the generated Ruby driver.

Work in progress…

### Methods

alert alert? all_window_ids all_window_names all_window_titles body_text browser_network_traffic browser_xpath_library= checked? click confirmation confirmation? cookie cookie? cookies create_cookie delete_cookie element? field go_back js_eval location prompt prompt? remote_control_timeout_in_seconds= table_cell_text text text? text_content title value visible? wait_for wait_for_condition wait_for_page wait_for_page_to_load wait_for_popup

### Public Instance methods

alert()

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.

[Source]

         # File lib/selenium/client/idiomatic.rb, line 212
    212:       def alert
    213:         string_command "getAlert"
    214:       end

alert?()

Whether an alert occurred

[Source]

         # File lib/selenium/client/idiomatic.rb, line 194
    194:       def alert?
    195:         boolean_command "isAlertPresent"
    196:       end

all_window_ids()

Returns the IDs of all windows that the browser knows about.

[Source]

         # File lib/selenium/client/idiomatic.rb, line 397
    397:       def all_window_ids
    398:         string_array_command "getAllWindowIds"
    399:       end

all_window_names()

Returns the names of all windows that the browser knows about.

[Source]

         # File lib/selenium/client/idiomatic.rb, line 403
    403:       def all_window_names
    404:         string_array_command "getAllWindowNames"
    405:       end

all_window_titles()

Returns the titles of all windows that the browser knows about.

[Source]

         # File lib/selenium/client/idiomatic.rb, line 409
    409:       def all_window_titles
    410:         string_array_command "getAllWindowTitles"
    411:       end

body_text()

Gets the entire text of the page.

[Source]

         # File lib/selenium/client/idiomatic.rb, line 109
    109:       def body_text
    110:         string_command "getBodyText"
    111:       end

browser_network_traffic(format = :plain)

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

[Source]

         # File lib/selenium/client/idiomatic.rb, line 425
    425:       def browser_network_traffic(format = :plain)
    426:         raise "format must be :plain, :json, or :xml"   \
    427:             unless [:plain, :json, :xml].include?(format)
    428:
    429:         remote_control_command "captureNetworkTraffic", [format.to_s]
    430:       end

browser_xpath_library=(library_name)

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.

[Source]

         # File lib/selenium/client/idiomatic.rb, line 439
    439:       def browser_xpath_library=(library_name)
    440:         raise "library name must be :ajaxslt, :javascript-xpath, or :default"   \
    441:             unless [:ajaxslt, 'javascript-xpath''javascript-xpath', :default].include?(library_name)
    442:         remote_control_command "useXpathLibrary", [library_name.to_s]
    443:       end

checked?(locator)

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

[Source]

         # File lib/selenium/client/idiomatic.rb, line 189
    189:       def checked?(locator)
    190:         boolean_command "isChecked", [locator,]
    191:       end

click(locator, options={})

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 => :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.

[Source]

         # File lib/selenium/client/idiomatic.rb, line 140
    140:       def click(locator, options={})
    141:         remote_control_command "click", [locator,]
    142:         wait_for options
    143:       end

confirmation()

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.

[Source]

         # File lib/selenium/client/idiomatic.rb, line 238
    238:       def confirmation
    239:         string_command "getConfirmation"
    240:       end

confirmation?()

Whether a confirmation has been auto-acknoledged (i.e. confirm() been called)

[Source]

         # File lib/selenium/client/idiomatic.rb, line 217
    217:       def confirmation?
    218:         boolean_command "isConfirmationPresent"
    219:       end

cookie(name)

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

[Source]

         # File lib/selenium/client/idiomatic.rb, line 351
    351:       def cookie(name)
    352:         string_command "getCookieByName", [name,]
    353:       end

cookie?(name)

Returns true if a cookie with the specified name is present, or false otherwise.

‘name’ is the name of the cookie

[Source]

         # File lib/selenium/client/idiomatic.rb, line 358
    358:       def cookie?(name)
    359:         boolean_command "isCookiePresent", [name,]
    360:       end

cookies()

Return all cookies for the current page under test.

[Source]

         # File lib/selenium/client/idiomatic.rb, line 344
    344:       def cookies
    345:         string_command "getCookie"
    346:       end

create_cookie(name_value_pair, options="")

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.

[Source]

         # File lib/selenium/client/idiomatic.rb, line 368
    368:       def create_cookie(name_value_pair, options="")
    369:               if options.kind_of? Hash
    370:                       options = options.keys.collect {|key| "#{key}=#{options[key]}" }.sort.join(", ")
    371:                     end
    372:         remote_control_command "createCookie", [name_value_pair,options,]
    373:       end

delete_cookie(name, options="")

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.

[Source]

         # File lib/selenium/client/idiomatic.rb, line 388
    388:       def delete_cookie(name, options="")
    389:               if options.kind_of? Hash
    390:                       ordered_keys = options.keys.sort {|a,b| a.to_s <=> b.to_s }
    391:                       options = ordered_keys.collect {|key| "#{key}=#{options[key]}" }.join(", ")
    392:                     end
    393:         remote_control_command "deleteCookie", [name,options,]
    394:       end

element?(locator)

Verifies that the specified element is somewhere on the page.

- ‘locator’ is an element locator

[Source]

         # File lib/selenium/client/idiomatic.rb, line 155
    155:       def element?(locator)
    156:         boolean_command "isElementPresent", [locator,]
    157:       end

field(locator)

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

[Source]

         # File lib/selenium/client/idiomatic.rb, line 176
    176:       def field(locator)
    177:         string_command "getValue", [locator,]
    178:       end

go_back(options={})

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 => :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.

[Source]

         # File lib/selenium/client/idiomatic.rb, line 338
    338:       def go_back(options={})
    339:         remote_control_command "goBack"
    340:         wait_for options
    341:       end

js_eval(script)

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

[Source]

         # File lib/selenium/client/idiomatic.rb, line 275
    275:       def js_eval(script)
    276:         string_command "getEval", [script,]
    277:       end

location()

Returns the absolute URL of the current page.

[Source]

        # File lib/selenium/client/idiomatic.rb, line 30
    30:       def location
    31:         string_command "getLocation"
    32:       end

prompt()

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.

[Source]

         # File lib/selenium/client/idiomatic.rb, line 260
    260:       def prompt
    261:         string_command "getPrompt"
    262:       end

prompt?()

Whether a prompt occurred

[Source]

         # File lib/selenium/client/idiomatic.rb, line 243
    243:       def prompt?
    244:         boolean_command "isPromptPresent"
    245:       end

remote_control_timeout_in_seconds=(timeout_in_seconds)

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.

[Source]

         # File lib/selenium/client/idiomatic.rb, line 286
    286:       def remote_control_timeout_in_seconds=(timeout_in_seconds)
    287:           remote_control_command "setTimeout", [timeout_in_seconds * 1000,]
    288:       end

table_cell_text(tableCellAddress)

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"

[Source]

         # File lib/selenium/client/idiomatic.rb, line 294
    294:       def table_cell_text(tableCellAddress)
    295:         string_command "getTable", [tableCellAddress,]
    296:       end

text(locator)

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

[Source]

        # File lib/selenium/client/idiomatic.rb, line 19
    19:       def text(locator)
    20:         string_command "getText", [locator,]
    21:       end

text?(pattern)

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

[Source]

         # File lib/selenium/client/idiomatic.rb, line 148
    148:       def text?(pattern)
    149:         boolean_command "isTextPresent", [pattern,]
    150:       end

text_content(locator)

Alias for text

title()

Return the title of the current HTML page.

[Source]

        # File lib/selenium/client/idiomatic.rb, line 25
    25:       def title
    26:         string_command "getTitle"
    27:       end

value(locator)

Alias for `field`

[Source]

         # File lib/selenium/client/idiomatic.rb, line 181
    181:       def value(locator)
    182:               field locator
    183:       end

visible?(locator)

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

[Source]

         # File lib/selenium/client/idiomatic.rb, line 166
    166:       def visible?(locator)
    167:          boolean_command "isVisible", [locator,]
    168:       end

wait_for(options)

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 => :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.

[Source]

         # File lib/selenium/client/idiomatic.rb, line 81
     81:       def wait_for(options)
     82:         if options[:wait_for] == :page
     83:           wait_for_page options[:timeout_in_seconds]
     84:               elsif options[:wait_for] == :ajax
     85:                   wait_for_ajax options
     86:               elsif options[:wait_for] == :element
     87:                   wait_for_element options[:element], options
     88:               elsif options[:wait_for] == :no_element
     89:                   wait_for_no_element options[:element], options
     90:               elsif options[:wait_for] == :text
     91:                   wait_for_text options[:text], options
     92:               elsif options[:wait_for] == :no_text
     93:           wait_for_no_text options[:text], options
     94:               elsif options[:wait_for] == :effects
     95:                   wait_for_effects options
     96:         elsif options[:wait_for] == :popup
     97:             wait_for_popup options[:window], options[:timeout_in_seconds]
     98:             select_window options[:window] if options[:select]
     99:         elsif options[:wait_for] == :value
    100:             wait_for_field_value options[:element], options[:value], options
    101:         elsif options[:wait_for] == :no_value
    102:             wait_for_no_field_value options[:element], options[:value], options
    103:               elsif options[:wait_for] == :condition
    104:                   wait_for_condition options[:javascript], options[:timeout_in_seconds]
    105:         end
    106:       end

wait_for_condition(script, timeout_in_seconds = nil)

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

[Source]

         # File lib/selenium/client/idiomatic.rb, line 310
    310:       def wait_for_condition(script, timeout_in_seconds = nil)
    311:         remote_control_command "waitForCondition", [script, (timeout_in_seconds || default_timeout_in_seconds) * 1000,]
    312:       end

wait_for_page(timeout_in_seconds=nil)

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

[Source]

        # File lib/selenium/client/idiomatic.rb, line 44
    44:       def wait_for_page(timeout_in_seconds=nil)
    45:         actual_timeout = timeout_in_seconds || default_timeout_in_seconds
    46:         remote_control_command "waitForPageToLoad", [actual_timeout * 1000,]
    47:       end

wait_for_page_to_load(timeout_in_seconds=nil)

Alias for wait_for_page

wait_for_popup(window_id, timeout_in_seconds=nil)

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

[Source]

        # File lib/selenium/client/idiomatic.rb, line 54
    54:       def wait_for_popup(window_id, timeout_in_seconds=nil)
    55:         actual_timeout = timeout_in_seconds || default_timeout_in_seconds
    56:         remote_control_command "waitForPopUp", [window_id, actual_timeout * 1000 ,]
    57:       end

[Validate]