org.openqa.selenium
Interface WebDriver

All Superinterfaces:

SearchContext

public interface WebDriver
extends SearchContext

The main interface to use for testing, which represents an idealised web browser. The methods in this class fall into three categories:

• Control of the browser itself
• Selection of WebElements
• Debugging aids

Key methods are get(String), which is used to load a new web page, and the various methods similar to findElement(By), which is used to find WebElements.

Currently, you will need to instantiate implementations of this class directly. It is hoped that you write your tests against this interface so that you may "swap in" a more fully featured browser when there is a requirement for one. Given this approach to testing, it is best to start writing your tests using the org.openqa.selenium.htmlunit.HtmlUnitDriver implementation.

Note that all methods that use XPath to locate elements will throw a RuntimeException should there be an error thrown by the underlying XPath engine.

See Also:

org.openqa.selenium.ie.InternetExplorerDriver, org.openqa.selenium.htmlunit.HtmlUnitDriver

Nested Class Summary

static interface	WebDriver.ImeHandler An interface for managing input methods.
static interface	WebDriver.Navigation
static interface	WebDriver.Options An interface for managing stuff you would do in a browser menu
static interface	WebDriver.TargetLocator Used to locate a given frame or window.
static interface	WebDriver.Timeouts An interface for managing timeout behavior for WebDriver instances.
static interface	WebDriver.Window

Method Summary

void	close() Close the current window, quitting the browser if it's the last window currently open.
WebElement	findElement(By by) Find the first WebElement using the given method.
java.util.List<WebElement>	findElements(By by) Find all elements within the current page using the given mechanism.
void	get(java.lang.String url) Load a new web page in the current browser window.
java.lang.String	getCurrentUrl() Get a string representing the current URL that the browser is looking at.
java.lang.String	getPageSource() Get the source of the last loaded page.
java.lang.String	getTitle() The title of the current page.
java.lang.String	getWindowHandle() Return an opaque handle to this window that uniquely identifies it within this driver instance.
java.util.Set<java.lang.String>	getWindowHandles() Return a set of window handles which can be used to iterate over all open windows of this webdriver instance by passing them to #switchTo().window(String)
WebDriver.Options	manage() Gets the Option interface
WebDriver.Navigation	navigate() An abstraction allowing the driver to access the browser's history and to navigate to a given URL.
void	quit() Quits this driver, closing every associated window.
WebDriver.TargetLocator	switchTo() Send future commands to a different frame or window.

Method Detail

get

void get(java.lang.String url)

Load a new web page in the current browser window. This is done using an HTTP GET operation, and the method will block until the load is complete. This will follow redirects issued either by the server or as a meta-redirect from within the returned HTML. Should a meta-redirect "rest" for any duration of time, it is best to wait until this timeout is over, since should the underlying page change whilst your test is executing the results of future calls against this interface will be against the freshly loaded page. Synonym for WebDriver.Navigation.to(String).

Parameters:

url - The URL to load. It is best to use a fully qualified URL

getCurrentUrl

java.lang.String getCurrentUrl()

Get a string representing the current URL that the browser is looking at.

Returns:

The URL of the page currently loaded in the browser

getTitle

java.lang.String getTitle()

The title of the current page.

Returns:

The title of the current page, with leading and trailing whitespace stripped, or null if one is not already set

findElements

java.util.List<WebElement> findElements(By by)

Find all elements within the current page using the given mechanism. This method is affected by the 'implicit wait' times in force at the time of execution. When implicitly waiting, this method will return as soon as there are more than 0 items in the found collection, or will return an empty list if the timeout is reached.

Specified by:

findElements in interface SearchContext

Parameters:

by - The locating mechanism to use

Returns:

A list of all WebElements, or an empty list if nothing matches

See Also:

By, WebDriver.Timeouts

findElement

WebElement findElement(By by)

Find the first WebElement using the given method. This method is affected by the 'implicit wait' times in force at the time of execution. The findElement(..) invocation will return a matching row, or try again repeatedly until the configured timeout is reached. findElement should not be used to look for non-present elements, use findElements(By) and assert zero length response instead.

Specified by:

findElement in interface SearchContext

Parameters:

by - The locating mechanism

Returns:

The first matching element on the current page

Throws:

NoSuchElementException - If no matching elements are found

See Also:

By, WebDriver.Timeouts

getPageSource

java.lang.String getPageSource()

Get the source of the last loaded page. If the page has been modified after loading (for example, by Javascript) there is no guarentee that the returned text is that of the modified page. Please consult the documentation of the particular driver being used to determine whether the returned text reflects the current state of the page or the text last sent by the web server. The page source returned is a representation of the underlying DOM: do not expect it to be formatted or escaped in the same way as the response sent from the web server.

Returns:

The source of the current page

close

void close()

Close the current window, quitting the browser if it's the last window currently open.

quit

void quit()

Quits this driver, closing every associated window.

getWindowHandles

java.util.Set<java.lang.String> getWindowHandles()

Return a set of window handles which can be used to iterate over all open windows of this webdriver instance by passing them to #switchTo().window(String)

Returns:

A set of window handles which can be used to iterate over all open windows.

getWindowHandle

java.lang.String getWindowHandle()

Return an opaque handle to this window that uniquely identifies it within this driver instance. This can be used to switch to this window at a later date

switchTo

WebDriver.TargetLocator switchTo()

Send future commands to a different frame or window.

Returns:

A TargetLocator which can be used to select a frame or window

See Also:

WebDriver.TargetLocator

navigate

WebDriver.Navigation navigate()

An abstraction allowing the driver to access the browser's history and to navigate to a given URL.

Returns:

A WebDriver.Navigation that allows the selection of what to do next

manage

WebDriver.Options manage()

Gets the Option interface

Returns:

An option interface

See Also:

WebDriver.Options