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

Provide a more idiomatic API than the generated Ruby driver.

Work in progress…

Methods

Public Instance methods

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 164
164:       def alert
165:         string_command"getAlert"
166:       end

Whether an alert occurred

[Source]

     # File lib/selenium/client/idiomatic.rb, line 146
146:       def alert?
147:         boolean_command "isAlertPresent"
148:       end

Gets the entire text of the page.

[Source]

    # File lib/selenium/client/idiomatic.rb, line 81
81:       def body_text
82:         string_command"getBodyText"
83:       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

[Source]

     # File lib/selenium/client/idiomatic.rb, line 141
141:       def checked?(locator)
142:         boolean_command "isChecked", [locator,]
143:       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 ‘some_id’, :wait_for => :page # will wait for a new page to load
  • click ‘some_id’, :wait_for => :ajax # will wait for all ajax requests to be completed (Prototype only)
  • click ‘some_id’, :wait_for => :effects # will wait for all Prototype effects to be rendered
  • click ‘some_id’, :wait_for => :element, :element => ‘new_element_id’ # will wait for an element to be present/appear
  • click ‘some_id’, :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 => :no_text, :text => ‘some text’ # will wait for the text to be not be present/disappear
  • click ‘some_id’, :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 103
103:       def click(locator, options={})
104:         remote_control_command("click", [locator,])        
105:         wait_for options
106:       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.

[Source]

     # File lib/selenium/client/idiomatic.rb, line 190
190:       def confirmation
191:         string_command"getConfirmation"
192:       end

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

[Source]

     # File lib/selenium/client/idiomatic.rb, line 169
169:       def confirmation?
170:         boolean_command "isConfirmationPresent"
171:       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

[Source]

     # File lib/selenium/client/idiomatic.rb, line 294
294:       def cookie(name)
295:         string_command "getCookieByName", [name,]
296:       end

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 301
301:       def cookie?(name)
302:         boolean_command "isCookiePresent", [name,]
303:       end

Return all cookies for the current page under test.

[Source]

     # File lib/selenium/client/idiomatic.rb, line 287
287:       def cookies
288:         string_command "getCookie"
289:       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.

[Source]

     # File lib/selenium/client/idiomatic.rb, line 311
311:       def create_cookie(name_value_pair, options="")
312:               if options.kind_of? Hash
313:                       options = options.keys.collect {|key| "#{key}=#{options[key]}" }.sort.join(", ")
314:                     end
315:         remote_control_command "createCookie", [name_value_pair,options,]
316:       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.

[Source]

     # File lib/selenium/client/idiomatic.rb, line 331
331:       def delete_cookie(name, options="")
332:               if options.kind_of? Hash
333:                       ordered_keys = options.keys.sort {|a,b| a.to_s <=> b.to_s }
334:                       options = ordered_keys.collect {|key| "#{key}=#{options[key]}" }.join(", ")
335:                     end
336:         remote_control_command "deleteCookie", [name,options,]
337:       end

Verifies that the specified element is somewhere on the page.

  • ‘locator’ is an element locator

[Source]

     # File lib/selenium/client/idiomatic.rb, line 118
118:       def element?(locator)
119:         boolean_command "isElementPresent", [locator,]
120:       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

[Source]

     # File lib/selenium/client/idiomatic.rb, line 128
128:       def field(locator)
129:         string_command "getValue", [locator,]
130:       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 => :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 => :no_text, :text => ‘some text’ # will wait for the text to be not be present/disappear
  • 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.

[Source]

     # File lib/selenium/client/idiomatic.rb, line 281
281:       def go_back(options={})
282:         remote_control_command "goBack"
283:         wait_for options
284:       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

[Source]

     # File lib/selenium/client/idiomatic.rb, line 227
227:       def js_eval(script)
228:         string_command"getEval", [script,]
229:       end

Returns the absolute URL of the current page.

[Source]

    # File lib/selenium/client/idiomatic.rb, line 28
28:       def location
29:         string_command"getLocation"
30:       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.

[Source]

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

Whether a prompt occurred

[Source]

     # File lib/selenium/client/idiomatic.rb, line 195
195:       def prompt?
196:         boolean_command "isPromptPresent"
197:       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.

[Source]

     # File lib/selenium/client/idiomatic.rb, line 238
238:       def remote_control_timeout_in_seconds=(timeout_in_seconds)
239:           remote_control_command "setTimeout", [timeout_in_seconds * 1000,]
240:       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"

[Source]

     # File lib/selenium/client/idiomatic.rb, line 246
246:       def table_cell_text(tableCellAddress)
247:         string_command "getTable", [tableCellAddress,]
248:       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

[Source]

     # File lib/selenium/client/idiomatic.rb, line 111
111:       def text?(pattern)
112:         boolean_command "isTextPresent", [pattern,]
113:       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

[Source]

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

Return the title of the current HTML page.

[Source]

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

Alias for field

[Source]

     # File lib/selenium/client/idiomatic.rb, line 133
133:       def value(locator)
134:               field locator
135:       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 => :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 => :no_text, :text => ‘some text’ # will wait for the text to be not be present/disappear
  • 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 60
60:       def wait_for(options)
61:         if options[:wait_for] == :page
62:           wait_for_page options[:timeout_in_seconds]
63:               elsif options[:wait_for] == :ajax
64:                   wait_for_ajax options[:timeout_in_seconds]
65:               elsif options[:wait_for] == :element
66:                   wait_for_element options[:element], options[:timeout_in_seconds]
67:               elsif options[:wait_for] == :no_element
68:                   wait_for_no_element options[:element], options[:timeout_in_seconds]
69:               elsif options[:wait_for] == :text
70:                   wait_for_text options[:text], options[:timeout_in_seconds]
71:               elsif options[:wait_for] == :no_text
72:                   wait_for_no_text options[:text], options[:timeout_in_seconds]
73:               elsif options[:wait_for] == :effects
74:                   wait_for_effects options[:timeout_in_seconds]
75:               elsif options[:wait_for] == :condition
76:                   wait_for_condition options[:javascript], options[:timeout_in_seconds]
77:         end
78:       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

[Source]

     # File lib/selenium/client/idiomatic.rb, line 262
262:       def wait_for_condition(script, timeout_in_seconds = nil)
263:         remote_control_command "waitForCondition", [script, (timeout_in_seconds || default_timeout_in_seconds) * 1000,]
264:       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

[Source]

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

[Validate]