org.openqa.selenium.WebDriver Maven / Gradle / Ivy
Show all versions of selenium-api Show documentation
// Licensed to the Software Freedom Conservancy (SFC) under one
// or more contributor license agreements. See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership. The SFC licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License. You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied. See the License for the
// specific language governing permissions and limitations
// under the License.
package org.openqa.selenium;
import java.net.URL;
import java.time.Duration;
import java.util.List;
import java.util.Set;
import java.util.concurrent.TimeUnit;
import org.openqa.selenium.logging.LoggingPreferences;
import org.openqa.selenium.logging.Logs;
/**
* WebDriver is a remote control interface that enables introspection and control of user agents
* (browsers). The methods in this interface fall into three categories:
*
*
* - Control of the browser itself
*
- Selection of {@link WebElement}s
*
- Debugging aids
*
*
* Key methods are {@link WebDriver#get(String)}, which is used to load a new web page, and the
* various methods similar to {@link WebDriver#findElement(By)}, which is used to find {@link
* WebElement}s.
*
*
Currently, you will need to instantiate implementations of this interface 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.
*
*
Most implementations of this interface follow W3C
* WebDriver specification
*/
public interface WebDriver extends SearchContext {
// Navigation
/**
* Load a new web page in the current browser window. This is done using an HTTP POST operation,
* and the method will block until the load is complete (with the default 'page load strategy'.
* 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 {@link org.openqa.selenium.WebDriver.Navigation#to(String)}.
*
*
See W3C WebDriver specification
* for more details.
*
* @param url The URL to load. Must be a fully qualified URL
* @see org.openqa.selenium.PageLoadStrategy
*/
void get(String url);
/**
* Get a string representing the current URL that the browser is looking at.
*
*
See W3C WebDriver
* specification for more details.
*
* @return The URL of the page currently loaded in the browser
*/
String getCurrentUrl();
// General properties
/**
* Get the title of the current page.
*
*
See W3C WebDriver specification for
* more details.
*
* @return The title of the current page, with leading and trailing whitespace stripped, or null
* if one is not already set
*/
String getTitle();
/**
* 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.
*
*
See W3C WebDriver specification
* for more details.
*
* @param by The locating mechanism to use
* @return A list of all matching {@link WebElement}s, or an empty list if nothing matches
* @see org.openqa.selenium.By
* @see org.openqa.selenium.WebDriver.Timeouts
*/
@Override
List findElements(By by);
/**
* Find the first {@link 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 {@link
* #findElements(By)} and assert zero length response instead.
*
*
See W3C WebDriver specification
* for more details.
*
* @param by The locating mechanism to use
* @return The first matching element on the current page
* @throws NoSuchElementException If no matching elements are found
* @see org.openqa.selenium.By
* @see org.openqa.selenium.WebDriver.Timeouts
*/
@Override
WebElement findElement(By by);
// Misc
/**
* Get the source of the last loaded page. If the page has been modified after loading (for
* example, by Javascript) there is no guarantee 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. Think of it
* as an artist's impression.
*
*
See W3C WebDriver
* specification for more details.
*
* @return The source of the current page
*/
String getPageSource();
/**
* Close the current window, quitting the browser if it's the last window currently open.
*
*
See W3C WebDriver specification
* for more details.
*/
void close();
/** Quits this driver, closing every associated window. */
void quit();
/**
* Return a set of window handles which can be used to iterate over all open windows of this
* WebDriver instance by passing them to {@link #switchTo()}.{@link Options#window()}
*
*
See W3C WebDriver
* specification for more details.
*
* @return A set of window handles which can be used to iterate over all open windows.
*/
Set getWindowHandles();
/**
* 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
*
* See W3C WebDriver
* specification for more details.
*
* @return the current window handle
*/
String getWindowHandle();
/**
* Send future commands to a different frame or window.
*
* @return A TargetLocator which can be used to select a frame or window
* @see org.openqa.selenium.WebDriver.TargetLocator
*/
TargetLocator switchTo();
/**
* An abstraction allowing the driver to access the browser's history and to navigate to a given
* URL.
*
* @return A {@link org.openqa.selenium.WebDriver.Navigation} that allows the selection of what to
* do next
*/
Navigation navigate();
/**
* Gets the Option interface
*
* @return An option interface
* @see org.openqa.selenium.WebDriver.Options
*/
Options manage();
/** An interface for managing stuff you would do in a browser menu */
interface Options {
/**
* Add a specific cookie. If the cookie's domain name is left blank, it is assumed that the
* cookie is meant for the domain of the current document.
*
*
See W3C WebDriver specification
* for more details.
*
* @param cookie The cookie to add.
*/
void addCookie(Cookie cookie);
/**
* Delete the named cookie from the current domain. This is equivalent to setting the named
* cookie's expiry date to some time in the past.
*
*
See W3C WebDriver
* specification for more details.
*
* @param name The name of the cookie to delete
*/
void deleteCookieNamed(String name);
/**
* Delete a cookie from the browser's "cookie jar". The domain of the cookie will be ignored.
*
* @param cookie nom nom nom
*/
void deleteCookie(Cookie cookie);
/**
* Delete all the cookies for the current domain.
*
*
See W3C WebDriver
* specification for more details.
*/
void deleteAllCookies();
/**
* Get all the cookies for the current domain.
*
*
See W3C WebDriver
* specification for more details.
*
* @return A Set of cookies for the current domain.
*/
Set getCookies();
/**
* Get a cookie with a given name.
*
* See W3C WebDriver
* specification for more details.
*
* @param name the name of the cookie
* @return the cookie, or null if no cookie with the given name is present
*/
Cookie getCookieNamed(String name);
/**
* @return the interface for managing driver timeouts.
*/
Timeouts timeouts();
/**
* @return the interface for managing the current window.
*/
Window window();
/**
* Gets the {@link Logs} interface used to fetch different types of logs.
*
*
To set the logging preferences {@link LoggingPreferences}.
*
* @return A Logs interface.
*/
@Beta
Logs logs();
}
/**
* An interface for managing timeout behavior for WebDriver instances.
*
*
See W3C WebDriver specification
* for more details.
*/
interface Timeouts {
/**
* @deprecated Use {@link #implicitlyWait(Duration)}
*
Specifies the amount of time the driver should wait when searching for an element if
* it is not immediately present.
*
When searching for a single element, the driver should poll the page until the element
* has been found, or this timeout expires before throwing a {@link NoSuchElementException}.
* When searching for multiple elements, the driver should poll the page until at least one
* element has been found or this timeout has expired.
*
Increasing the implicit wait timeout should be used judiciously as it will have an
* adverse effect on test run time, especially when used with slower location strategies
* like XPath.
*
If the timeout is negative, not null, or greater than 2e16 - 1, an error code with
* invalid argument will be returned.
* @param time The amount of time to wait.
* @param unit The unit of measure for {@code time}.
* @return A self reference.
*/
@Deprecated
Timeouts implicitlyWait(long time, TimeUnit unit);
/**
* Specifies the amount of time the driver should wait when searching for an element if it is
* not immediately present.
*
*
When searching for a single element, the driver should poll the page until the element has
* been found, or this timeout expires before throwing a {@link NoSuchElementException}. When
* searching for multiple elements, the driver should poll the page until at least one element
* has been found or this timeout has expired.
*
*
Increasing the implicit wait timeout should be used judiciously as it will have an adverse
* effect on test run time, especially when used with slower location strategies like XPath.
*
*
If the timeout is negative, not null, or greater than 2e16 - 1, an error code with invalid
* argument will be returned.
*
* @param duration The duration to wait.
* @return A self reference.
*/
default Timeouts implicitlyWait(Duration duration) {
return implicitlyWait(duration.toMillis(), TimeUnit.MILLISECONDS);
}
/**
* Gets the amount of time the driver should wait when searching for an element if it is not
* immediately present.
*
* @return The amount of time the driver should wait when searching for an element.
* @see W3C WebDriver
*/
default Duration getImplicitWaitTimeout() {
throw new UnsupportedCommandException();
}
/**
* @deprecated Use {@link #scriptTimeout(Duration)}
*
Sets the amount of time to wait for an asynchronous script to finish execution before
* throwing an error. If the timeout is negative, not null, or greater than 2e16 - 1, an
* error code with invalid argument will be returned.
* @param time The timeout value.
* @param unit The unit of time.
* @return A self reference.
* @see JavascriptExecutor#executeAsyncScript(String, Object...)
* @see W3C WebDriver
* @see W3C WebDriver
*/
@Deprecated
Timeouts setScriptTimeout(long time, TimeUnit unit);
/**
* Sets the amount of time to wait for an asynchronous script to finish execution before
* throwing an error. If the timeout is negative, not null, or greater than 2e16 - 1, an error
* code with invalid argument will be returned.
*
* @param duration The timeout value.
* @deprecated Use {@link #scriptTimeout(Duration)}
* @return A self reference.
* @see JavascriptExecutor#executeAsyncScript(String, Object...)
* @see W3C WebDriver
* @see W3C WebDriver
*/
@Deprecated
default Timeouts setScriptTimeout(Duration duration) {
return setScriptTimeout(duration.toMillis(), TimeUnit.MILLISECONDS);
}
/**
* Sets the amount of time to wait for an asynchronous script to finish execution before
* throwing an error. If the timeout is negative, not null, or greater than 2e16 - 1, an error
* code with invalid argument will be returned.
*
* @param duration The timeout value.
* @return A self reference.
* @see JavascriptExecutor#executeAsyncScript(String, Object...)
* @see W3C WebDriver
* @see W3C WebDriver
*/
default Timeouts scriptTimeout(Duration duration) {
return setScriptTimeout(duration);
}
/**
* Gets the amount of time to wait for an asynchronous script to finish execution before
* throwing an error. If the timeout is negative, not null, or greater than 2e16 - 1, an error
* code with invalid argument will be returned.
*
* @return The amount of time to wait for an asynchronous script to finish execution.
* @see W3C WebDriver
* @see W3C WebDriver
*/
default Duration getScriptTimeout() {
throw new UnsupportedCommandException();
}
/**
* @param time The timeout value.
* @param unit The unit of time.
* @return A Timeouts interface.
* @see W3C WebDriver
* @see W3C WebDriver
* @deprecated Use {@link #pageLoadTimeout(Duration)}
*
Sets the amount of time to wait for a page load to complete before throwing an error.
* If the timeout is negative, not null, or greater than 2e16 - 1, an error code with
* invalid argument will be returned.
*/
@Deprecated
Timeouts pageLoadTimeout(long time, TimeUnit unit);
/**
* Sets the amount of time to wait for a page load to complete before throwing an error. If the
* timeout is negative, not null, or greater than 2e16 - 1, an error code with invalid argument
* will be returned.
*
* @param duration The timeout value.
* @return A Timeouts interface.
* @see W3C WebDriver
* @see W3C WebDriver
*/
default Timeouts pageLoadTimeout(Duration duration) {
return pageLoadTimeout(duration.toMillis(), TimeUnit.MILLISECONDS);
}
/**
* Gets the amount of time to wait for a page load to complete before throwing an error. If the
* timeout is negative, not null, or greater than 2e16 - 1, an error code with invalid argument
* will be returned.
*
* @return The amount of time to wait for a page load to complete.
* @see W3C WebDriver
* @see W3C WebDriver
*/
default Duration getPageLoadTimeout() {
throw new UnsupportedCommandException();
}
}
/** Used to locate a given frame or window. */
interface TargetLocator {
/**
* Select a frame by its (zero-based) index. Selecting a frame by index is equivalent to the JS
* expression window.frames[index] where "window" is the DOM window represented by the current
* context. Once the frame has been selected, all subsequent calls on the WebDriver interface
* are made to that frame.
*
*
See W3C WebDriver
* specification for more details.
*
* @param index (zero-based) index
* @return This driver focused on the given frame
* @throws NoSuchFrameException If the frame cannot be found
*/
WebDriver frame(int index);
/**
* Select a frame by its name or ID. Frames located by matching name attributes are always given
* precedence over those matched by ID.
*
* @param nameOrId the name of the frame window, the id of the <frame> or <iframe>
* element, or the (zero-based) index
* @return This driver focused on the given frame
* @throws NoSuchFrameException If the frame cannot be found
*/
WebDriver frame(String nameOrId);
/**
* Select a frame using its previously located {@link WebElement}.
*
*
See W3C WebDriver
* specification for more details.
*
* @param frameElement The frame element to switch to.
* @return This driver focused on the given frame.
* @throws NoSuchFrameException If the given element is neither an IFRAME nor a FRAME element.
* @throws StaleElementReferenceException If the WebElement has gone stale.
* @see WebDriver#findElement(By)
*/
WebDriver frame(WebElement frameElement);
/**
* Change focus to the parent context. If the current context is the top level browsing context,
* the context remains unchanged.
*
*
See W3C WebDriver
* specification for more details.
*
* @return This driver focused on the parent frame
*/
WebDriver parentFrame();
/**
* Switch the focus of future commands for this driver to the window with the given name/handle.
*
*
See W3C WebDriver
* specification for more details.
*
* @param nameOrHandle The name of the window or the handle as returned by {@link
* WebDriver#getWindowHandle()}
* @return This driver focused on the given window
* @throws NoSuchWindowException If the window cannot be found
*/
WebDriver window(String nameOrHandle);
/**
* Creates a new browser window and switches the focus for future commands of this driver to the
* new window.
*
*
See W3C WebDriver specification
* for more details.
*
* @param typeHint The type of new browser window to be created. The created window is not
* guaranteed to be of the requested type; if the driver does not support the requested
* type, a new browser window will be created of whatever type the driver does support.
* @return This driver focused on the given window
*/
WebDriver newWindow(WindowType typeHint);
/**
* Selects either the first frame on the page, or the main document when a page contains
* iframes.
*
*
See W3C WebDriver
* specification for more details.
*
* @return This driver focused on the top window/first frame.
*/
WebDriver defaultContent();
/**
* Switches to the element that currently has focus within the document currently "switched to",
* or the body element if this cannot be detected. This matches the semantics of calling
* "document.activeElement" in Javascript.
*
*
See W3C WebDriver
* specification for more details.
*
* @return The WebElement with focus, or the body element if no element with focus can be
* detected.
*/
WebElement activeElement();
/**
* Switches to the currently active modal dialog for this particular driver instance.
*
* @return A handle to the dialog.
* @throws NoAlertPresentException If the dialog cannot be found
*/
Alert alert();
}
interface Navigation {
/**
* Move back a single "item" in the browser's history.
*
*
See W3C WebDriver specification for
* more details.
*/
void back();
/**
* Move a single "item" forward in the browser's history. Does nothing if we are on the latest
* page viewed.
*
*
See W3C WebDriver specification for
* more details.
*/
void forward();
/**
* Load a new web page in the current browser window. This is done using an HTTP POST 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.
*
*
See W3C WebDriver specification
* for more details.
*
* @param url The URL to load. Must be a fully qualified URL
*/
void to(String url);
/**
* Overloaded version of {@link #to(String)} that makes it easy to pass in a URL.
*
* @param url URL
*/
void to(URL url);
/**
* Refresh the current page
*
*
See W3C WebDriver specification for
* more details.
*/
void refresh();
}
@Beta
interface Window {
/**
* Get the size of the current window. This will return the outer window dimension, not just the
* view port.
*
*
See W3C WebDriver
* specification for more details.
*
* @return The current window size.
*/
Dimension getSize();
/**
* Set the size of the current window. This will change the outer window dimension, not just the
* view port, synonymous to window.resizeTo() in JS.
*
*
See W3C WebDriver
* specification for more details.
*
* @param targetSize The target size.
*/
void setSize(Dimension targetSize);
/**
* Get the position of the current window, relative to the upper left corner of the screen.
*
*
See W3C WebDriver
* specification for more details.
*
* @return The current window position.
*/
Point getPosition();
/**
* Set the position of the current window. This is relative to the upper left corner of the
* screen, synonymous to window.moveTo() in JS.
*
*
See W3C WebDriver
* specification for more details.
*
* @param targetPosition The target position of the window.
*/
void setPosition(Point targetPosition);
/**
* Maximizes the current window if it is not already maximized
*
*
See W3C WebDriver
* specification for more details.
*/
void maximize();
/**
* Minimizes the current window if it is not already minimized
*
*
See W3C WebDriver
* specification for more details.
*/
void minimize();
/**
* Fullscreen the current window if it is not already fullscreen
*
*
See W3C WebDriver
* specification for more details.
*/
void fullscreen();
}
}