Class RemoteWebDriver

java.lang.Object
org.openqa.selenium.remote.RemoteWebDriver
All Implemented Interfaces:
HasFederatedCredentialManagement, HasCapabilities, HasDownloads, Interactive, JavascriptExecutor, PrintsPage, SearchContext, TakesScreenshot, HasVirtualAuthenticator, WebDriver
Direct Known Subclasses:
ChromiumDriver, FirefoxDriver, InternetExplorerDriver, SafariDriver

  • Constructor Details

    • RemoteWebDriver

      protected RemoteWebDriver()
    • RemoteWebDriver

      public RemoteWebDriver(Capabilities capabilities)
    • RemoteWebDriver

      public RemoteWebDriver(Capabilities capabilities, boolean enableTracing)
    • RemoteWebDriver

      public RemoteWebDriver(URL remoteAddress, Capabilities capabilities)
    • RemoteWebDriver

      public RemoteWebDriver(URL remoteAddress, Capabilities capabilities, boolean enableTracing)
    • RemoteWebDriver

      public RemoteWebDriver(CommandExecutor executor, Capabilities capabilities)
  • Method Details

    • builder

      @Beta public static RemoteWebDriverBuilder builder()
    • getSessionId

      public SessionId getSessionId()
    • setSessionId

      protected void setSessionId(String opaqueKey)
    • startSession

      protected void startSession(Capabilities capabilities)
    • getErrorHandler

      public ErrorHandler getErrorHandler()
    • setErrorHandler

      public void setErrorHandler(ErrorHandler handler)
    • getCommandExecutor

      public CommandExecutor getCommandExecutor()
    • setCommandExecutor

      protected void setCommandExecutor(CommandExecutor executor)
    • getCapabilities

      public Capabilities getCapabilities()
      Specified by:
      getCapabilities in interface HasCapabilities
      Returns:
      The capabilities of the current driver.
    • get

      public void get(String url)
      Description copied from interface: WebDriver
      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 WebDriver.Navigation.to(String).

      See W3C WebDriver specification for more details.

      Specified by:
      get in interface WebDriver
      Parameters:
      url - The URL to load. Must be a fully qualified URL
      See Also:
    • getTitle

      public String getTitle()
      Description copied from interface: WebDriver
      Get the title of the current page.

      See W3C WebDriver specification for more details.

      Specified by:
      getTitle in interface WebDriver
      Returns:
      The title of the current page, with leading and trailing whitespace stripped, or null if one is not already set
    • getCurrentUrl

      public String getCurrentUrl()
      Description copied from interface: WebDriver
      Get a string representing the current URL that the browser is looking at.

      See W3C WebDriver specification for more details.

      Specified by:
      getCurrentUrl in interface WebDriver
      Returns:
      The URL of the page currently loaded in the browser
    • getScreenshotAs

      public <X> X getScreenshotAs(OutputType<X> outputType) throws WebDriverException
      Description copied from interface: TakesScreenshot
      Capture the screenshot and store it in the specified location.

      For a W3C-conformant WebDriver or WebElement, this behaves as stated in W3C WebDriver specification.

      For a non-W3C-conformant WebDriver, this makes a best effort depending on the browser to return the following in order of preference:

      • Entire page
      • Current window
      • Visible portion of the current frame
      • The screenshot of the entire display containing the browser
      For a non-W3C-conformant WebElement extending TakesScreenshot, this makes a best effort depending on the browser to return the following in order of preference:
      • The entire content of the HTML element
      • The visible portion of the HTML element
      Specified by:
      getScreenshotAs in interface TakesScreenshot
      Type Parameters:
      X - Return type for getScreenshotAs.
      Parameters:
      outputType - target type, @see OutputType
      Returns:
      Object in which is stored information about the screenshot.
      Throws:
      WebDriverException - on failure.
    • print

      public Pdf print(PrintOptions printOptions) throws WebDriverException
      Specified by:
      print in interface PrintsPage
      Throws:
      WebDriverException
    • findElement

      public WebElement findElement(By locator)
      Description copied from interface: WebDriver
      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 WebDriver.findElements(By) and assert zero length response instead.

      See W3C WebDriver specification for more details.

      Specified by:
      findElement in interface SearchContext
      Specified by:
      findElement in interface WebDriver
      Parameters:
      locator - The locating mechanism to use
      Returns:
      The first matching element on the current page
      See Also:
    • findElements

      public List<WebElement> findElements(By locator)
      Description copied from interface: WebDriver
      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.

      Specified by:
      findElements in interface SearchContext
      Specified by:
      findElements in interface WebDriver
      Parameters:
      locator - The locating mechanism to use
      Returns:
      A list of all matching WebElements, or an empty list if nothing matches
      See Also:
    • findElements

      public List<WebElement> findElements(SearchContext context, BiFunction<String,Object,CommandPayload> findCommand, By locator)
    • setFoundBy

      protected void setFoundBy(SearchContext context, WebElement element, String by, String using)
    • getPageSource

      public String getPageSource()
      Description copied from interface: WebDriver
      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.

      Specified by:
      getPageSource in interface WebDriver
      Returns:
      The source of the current page
    • close

      public void close()
      Description copied from interface: WebDriver
      Close the current window, quitting the browser if it's the last window currently open.

      See W3C WebDriver specification for more details.

      Specified by:
      close in interface WebDriver
    • quit

      public void quit()
      Description copied from interface: WebDriver
      Quits this driver, closing every associated window.
      Specified by:
      quit in interface WebDriver
    • getWindowHandles

      public Set<String> getWindowHandles()
      Description copied from interface: WebDriver
      Return a set of window handles which can be used to iterate over all open windows of this WebDriver instance by passing them to WebDriver.switchTo().WebDriver.Options.window()

      See W3C WebDriver specification for more details.

      Specified by:
      getWindowHandles in interface WebDriver
      Returns:
      A set of window handles which can be used to iterate over all open windows.
    • getWindowHandle

      public String getWindowHandle()
      Description copied from interface: WebDriver
      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.

      Specified by:
      getWindowHandle in interface WebDriver
      Returns:
      the current window handle
    • executeScript

      public Object executeScript(String script, Object... args)
      Description copied from interface: JavascriptExecutor
      Executes JavaScript in the context of the currently selected frame or window. The script fragment provided will be executed as the body of an anonymous function.

      Within the script, use document to refer to the current document. Note that local variables will not be available once the script has finished executing, though global variables will persist.

      If the script has a return value (i.e. if the script contains a return statement), then the following steps will be taken:

      • For an HTML element, this method returns a WebElement
      • For a decimal, a Double is returned
      • For a non-decimal number, a Long is returned
      • For a boolean, a Boolean is returned
      • For all other cases, a String is returned.
      • For an array, return a List<Object> with each object following the rules above. We support nested lists.
      • For a map, return a Map<String, Object> with values following the rules above.
      • Unless the value is null or there is no return value, in which null is returned

      Arguments must be a number, a boolean, a String, WebElement, or a List of any combination of the above. An exception will be thrown if the arguments do not meet these criteria. The arguments will be made available to the JavaScript via the "arguments" magic variable, as if the function were called via "Function.apply"

      Specified by:
      executeScript in interface JavascriptExecutor
      Parameters:
      script - The JavaScript to execute
      args - The arguments to the script. May be empty
      Returns:
      One of Boolean, Long, Double, String, List, Map or WebElement. Or null.
    • executeAsyncScript

      public Object executeAsyncScript(String script, Object... args)
      Description copied from interface: JavascriptExecutor
      Execute an asynchronous piece of JavaScript in the context of the currently selected frame or window. Unlike executing synchronous JavaScript, scripts executed with this method must explicitly signal they are finished by invoking the provided callback. This callback is always injected into the executed function as the last argument.

      The first argument passed to the callback function will be used as the script's result. This value will be handled as follows:

      • For an HTML element, this method returns a WebElement
      • For a number, a Long is returned
      • For a boolean, a Boolean is returned
      • For all other cases, a String is returned.
      • For an array, return a List<Object> with each object following the rules above. We support nested lists.
      • For a map, return a Map<String, Object> with values following the rules above.
      • Unless the value is null or there is no return value, in which null is returned

      The default timeout for a script to be executed is 0ms. In most cases, including the examples below, one must set the script timeout WebDriver.Timeouts.scriptTimeout(java.time.Duration) beforehand to a value sufficiently large enough.

      Example #1: Performing a sleep in the browser under test.

      
       long start = System.currentTimeMillis();
       ((JavascriptExecutor) driver).executeAsyncScript(
           "window.setTimeout(arguments[arguments.length - 1], 500);");
       System.out.println(
           "Elapsed time: " + (System.currentTimeMillis() - start));
       

      Example #2: Synchronizing a test with an AJAX application:

      
       WebElement composeButton = driver.findElement(By.id("compose-button"));
       composeButton.click();
       ((JavascriptExecutor) driver).executeAsyncScript(
           "var callback = arguments[arguments.length - 1];" +
           "mailClient.getComposeWindowWidget().onload(callback);");
       driver.switchTo().frame("composeWidget");
       driver.findElement(By.id("to")).sendKeys("bog@example.com");
       

      Example #3: Injecting a XMLHttpRequest and waiting for the result:

      
       Object response = ((JavascriptExecutor) driver).executeAsyncScript(
           "var callback = arguments[arguments.length - 1];" +
           "var xhr = new XMLHttpRequest();" +
           "xhr.open('GET', '/resource/data.json', true);" +
           "xhr.onreadystatechange = function() {" +
           "  if (xhr.readyState == 4) {" +
           "    callback(xhr.responseText);" +
           "  }" +
           "};" +
           "xhr.send();");
       JsonObject json = new JsonParser().parse((String) response);
       assertEquals("cheese", json.get("food").getAsString());
       

      Script arguments must be a number, a boolean, a String, WebElement, or a List of any combination of the above. An exception will be thrown if the arguments do not meet these criteria. The arguments will be made available to the JavaScript via the "arguments" variable.

      Specified by:
      executeAsyncScript in interface JavascriptExecutor
      Parameters:
      script - The JavaScript to execute.
      args - The arguments to the script. May be empty.
      Returns:
      One of Boolean, Long, String, List, Map, WebElement, or null.
      See Also:
    • switchTo

      public WebDriver.TargetLocator switchTo()
      Description copied from interface: WebDriver
      Send future commands to a different frame or window.
      Specified by:
      switchTo in interface WebDriver
      Returns:
      A TargetLocator which can be used to select a frame or window
      See Also:
    • manage

      public WebDriver.Options manage()
      Description copied from interface: WebDriver
      Gets the Option interface
      Specified by:
      manage in interface WebDriver
      Returns:
      An option interface
      See Also:
    • getElementConverter

      protected JsonToWebElementConverter getElementConverter()
    • setElementConverter

      protected void setElementConverter(JsonToWebElementConverter converter)
    • setLogLevel

      public void setLogLevel(Level level)
      Sets the RemoteWebDriver's client log level.
      Parameters:
      level - The log level to use.
    • execute

      protected Response execute(CommandPayload payload)
    • execute

      protected Response execute(String driverCommand, Map<String,?> parameters)
    • execute

      protected Response execute(String command)
    • getExecuteMethod

      protected ExecuteMethod getExecuteMethod()
    • perform

      public void perform(Collection<Sequence> actions)
      Specified by:
      perform in interface Interactive
    • resetInputState

      public void resetInputState()
      Specified by:
      resetInputState in interface Interactive
    • addVirtualAuthenticator

      public VirtualAuthenticator addVirtualAuthenticator(VirtualAuthenticatorOptions options)
      Description copied from interface: HasVirtualAuthenticator
      Adds a virtual authenticator with the given options.
      Specified by:
      addVirtualAuthenticator in interface HasVirtualAuthenticator
      Returns:
      the new virtual authenticator.
    • removeVirtualAuthenticator

      public void removeVirtualAuthenticator(VirtualAuthenticator authenticator)
      Description copied from interface: HasVirtualAuthenticator
      Removes a previously added virtual authenticator. The authenticator is no longer valid after removal, so no methods may be called.
      Specified by:
      removeVirtualAuthenticator in interface HasVirtualAuthenticator
    • getDownloadableFiles

      public List<String> getDownloadableFiles()
      Retrieves the downloadable files as a map of file names and their corresponding URLs.
      Specified by:
      getDownloadableFiles in interface HasDownloads
      Returns:
      A map containing file names as keys and URLs as values.
      Throws:
      WebDriverException - if capability to enable downloads is not set
    • downloadFile

      public void downloadFile(String fileName, Path targetLocation) throws IOException
      Downloads a file from the specified location.
      Specified by:
      downloadFile in interface HasDownloads
      Parameters:
      fileName - the name of the file to download
      targetLocation - the location where the file should be downloaded
      Throws:
      IOException - if an I/O error occurs during the file download
    • deleteDownloadableFiles

      public void deleteDownloadableFiles()
      Deletes all downloadable files.
      Specified by:
      deleteDownloadableFiles in interface HasDownloads
      Throws:
      WebDriverException - capability to enable downloads must be set
    • setDelayEnabled

      public void setDelayEnabled(boolean enabled)
      Description copied from interface: HasFederatedCredentialManagement
      Disables the promise rejection delay.

      FedCM by default delays promise resolution in failure cases for privacy reasons (https://fedidcg.github.io/FedCM/#ref-for-setdelayenabled); this function allows turning it off to let tests run faster where this is not relevant.

      Specified by:
      setDelayEnabled in interface HasFederatedCredentialManagement
    • resetCooldown

      public void resetCooldown()
      Description copied from interface: HasFederatedCredentialManagement
      Resets the FedCM dialog cooldown.

      If a user agent triggers a cooldown when the account chooser is dismissed, this function resets that cooldown so that the dialog can be triggered again immediately.

      Specified by:
      resetCooldown in interface HasFederatedCredentialManagement
    • getFederatedCredentialManagementDialog

      public FederatedCredentialManagementDialog getFederatedCredentialManagementDialog()
      Description copied from interface: HasFederatedCredentialManagement
      Gets the currently open FedCM dialog, or null if there is no dialog.

      Can be used with WebDriverWait like: wait.until(driver -> ((HasFederatedCredentialManagement) driver). getFederatedCredentialManagementDialog() != null);

      Specified by:
      getFederatedCredentialManagementDialog in interface HasFederatedCredentialManagement
    • log

      protected void log(SessionId sessionId, String commandName, Object toLog, RemoteWebDriver.When when)
      Override this to be notified at key points in the execution of a command.
      Parameters:
      sessionId - the session id.
      commandName - the command that is being executed.
      toLog - any data that might be interesting.
      when - verb tense of "Execute" to prefix message
    • getFileDetector

      public FileDetector getFileDetector()
    • setFileDetector

      public void setFileDetector(FileDetector detector)
      Set the file detector to be used when sending keyboard input. By default, this is set to a file detector that does nothing.
      Parameters:
      detector - The detector to use. Must not be null.
      See Also:
    • toString

      public String toString()
      Overrides:
      toString in class Object