This class represents the client to a Selenium session. It will only work
if a Selenium server instance is running. If you get an error, use
selenium_server_available() to check if a server is running. See the
package README for more information, or use selenium_server() to try and
start a server automatically.
Public fields
idThe id of the session, generated when the session is started.
browserThe browser that the session is using.
portThe port that the session is using.
hostThe host that the session is running on.
Methods
Method new()
Create a Selenium session: opening a browser which can be controlled by the Selenium client.
Usage
SeleniumSession$new(
browser = "firefox",
port = 4444L,
host = "localhost",
verbose = FALSE,
capabilities = NULL,
request_body = NULL,
timeout = 20
)Arguments
browserThe name of the browser to use (e.g. "chrome", "firefox", "edge").
portThe port that the Selenium server is using, so we can connect to it.
hostThe host that the Selenium server is running on. This is usually 'localhost' (i.e. your own machine).
verboseWhether to print the web requests that are being sent and any responses.
capabilitiesA list of capabilities to pass to the Selenium server, to combine with the defaults generated using
browser. Seechrome_options(),firefox_options(), andedge_options().request_bodyA list of request body parameters to pass to the Selenium server. Overrides
capabilities.timeoutHow long to wait for a request to recieve a response before throwing an error.
Method create_webelement()
Create a WebElement object using the parameters of the current session.
Returns
A WebElement object.
Method create_shadowroot()
Create a ShadowRoot object using the parameters of the current session.
Returns
A ShadowRoot object.
Method close()
Close the current session. Once a session is closed, its methods will no longer work. However, the Selenium server will still be running.
Method status()
Get the status of the Selenium server. Unlike all other methods, this
method is independent of the session itself (meaning it can be used
even after SeleniumSession$close() is called). It is
identical to get_server_status(), but uses the host, port and verbose
options passed to the session, for convenience.
Returns
A list that can (but may not always) contain the following fields:
ready: Whether the server is ready to be connected to. This should always be returned by the server.message: A message about the status of the server.uptime: How long the server has been running.nodes: Information about the slots that the server can take.
Method get_timeouts()
Get the timeouts of the current session. There are three types of timeouts:
session script timeout: The amount of time that the server will wait for scripts to run. Defaults to 3 seconds.
page load timeout: The amount of time that the server will wait for the page to load. Defaults to 30 seconds.
implicit wait: The amount of time that the server will wait for elements to be located, or for elements to become interactable when required. Defaults to 0 seconds.
Method set_timeouts()
Set the timeouts of the current session. The types of timeouts are
defined in SeleniumSession$get_timeouts().
Usage
SeleniumSession$set_timeouts(
script = NULL,
page_load = NULL,
implicit_wait = NULL,
request_body = NULL,
timeout = 20
)Arguments
scriptThe amount of time to wait for scripts. By default, this is not set.
page_loadThe amount of time to wait for the page to load.
implicit_waitThe amount of time to wait for elements on the page.
request_bodyA list of request body parameters to pass to the Selenium server, overriding the default body of the web request
timeoutHow long to wait for a request to recieve a response before throwing an error.
Method navigate()
Navigate to a URL.
Method title()
Get the title of the current page.
Method switch_to_window()
Switch to a specific window.
Method new_window()
Create a new window. Note that this window is not automatically switched to.
Usage
SeleniumSession$new_window(
type = c("tab", "window"),
request_body = NULL,
timeout = 20
)Arguments
typeWhether to create a tab or a window.
request_bodyA list of request body parameters to pass to the Selenium server, overriding the default body of the web request
timeoutHow long to wait for a request to recieve a response before throwing an error.
Method switch_to_frame()
Frames allow you to split a window into multiple sections, where each section can load a separate HTML document. This function allows you to switch to a specific frame, given its ID, meaning that frame will become the current browsing context.
Arguments
idThe ID of the frame to switch to. By default, the top-level browsing context is switched to (i.e. not a frame). This can also be a WebElement object, in which case the frame that contains said element will be switched to.
request_bodyA list of request body parameters to pass to the Selenium server, overriding the default body of the web request
timeoutHow long to wait for a request to recieve a response before throwing an error.
Method get_window_rect()
Get the size and position of the current window.
Method set_window_rect()
Set the size and position of the current window.
Usage
SeleniumSession$set_window_rect(
width = NULL,
height = NULL,
x = NULL,
y = NULL,
request_body = NULL,
timeout = 20
)Arguments
widthThe width of the window.
heightThe height of the window.
xThe x position of the window relative to the left of the screen.
yThe y position of the window relative to the top of the screen.
request_bodyA list of request body parameters to pass to the Selenium server, overriding the default body of the web request
timeoutHow long to wait for a request to recieve a response before throwing an error.
Method maximize_window()
Maximize the current window. This makes the window the maximum size it can be, without being full screen.
Method find_element()
Find the first element matching a selector.
Usage
SeleniumSession$find_element(
using = c("css selector", "xpath", "tag name", "link text", "partial link text"),
value,
request_body = NULL,
timeout = 20
)Arguments
usingThe type of selector to use.
valueThe value of the selector: a string.
request_bodyA list of request body parameters to pass to the Selenium server, overriding the default body of the web request
timeoutHow long to wait for a request to recieve a response before throwing an error.
Returns
A WebElement object.
Method find_elements()
Find all elements matching a selector.
Usage
SeleniumSession$find_elements(
using = c("css selector", "xpath", "tag name", "link text", "partial link text"),
value,
request_body = NULL,
timeout = 20
)Arguments
usingThe type of selector to use.
valueThe value of the selector: a string.
request_bodyA list of request body parameters to pass to the Selenium server, overriding the default body of the web request
timeoutHow long to wait for a request to recieve a response before throwing an error.
Returns
A list of WebElement objects.
Method execute_script()
Execute a JavaScript script.
Arguments
xThe script to execute. To return a value, do so explicitly, e.g.
return 1....Additional arguments to pass to the script. These can be accessed in the script using the
argumentsarray. Can be WebElement objects or lists of such objects, which will be converted to nodes.request_bodyA list of request body parameters to pass to the Selenium server, overriding the default body of the web request
timeoutHow long to wait for a request to recieve a response before throwing an error.
Returns
The return value of the script. Nodes or lists of nodes will be converted to WebElement objects.
Method execute_async_script()
Execute an asynchronous JavaScript script, waiting for a value to be returned.
Arguments
xThe script to execute. Unlike
execute_script(). You return an value using the callback function, which can be accessed usingarguments[arguments.length - 1]. For example, to return 1, you would writearguments[arguments.length - 1](1). This allows you to write asynchronous JavaScript, but treat it like synchronous R code....Additional arguments to pass to the script. Can be WebElement objects or lists of such objects, which will be converted to nodes.
request_bodyA list of request body parameters to pass to the Selenium server, overriding the default body of the web request
timeoutHow long to wait for a request to recieve a response before throwing an error.
Returns
The return value of the script. Nodes or lists of nodes will be converted to WebElement objects.
Method get_cookies()
Get all cookies.
Method get_cookie()
Get a specific cookie using its name.
Method add_cookie()
Add a cookie to the cookie store of the current document.
Arguments
cookieThe cookie object to add: a list which must contain a
nameandvaluefield.request_bodyA list of request body parameters to pass to the Selenium server, overriding the default body of the web request
timeoutHow long to wait for a request to recieve a response before throwing an error.
Method delete_cookie()
Delete a cookie using its name.
Method perform_actions()
Perform a sequence of actions.
Usage
SeleniumSession$perform_actions(
actions,
release_actions = TRUE,
request_body = NULL,
timeout = 20
)Arguments
actionsA
selenium_actions_streamobject, created usingactions_stream().release_actionsWhether to call
release_actions()after performing the actions.request_bodyA list of request body parameters to pass to the Selenium server, overriding the default body of the web request
timeoutHow long to wait for a request to recieve a response before throwing an error.
Method send_alert_text()
Send text to the current alert, if present. Useful if the alert is a prompt.
Method print_page()
Render the current page as a PDF.
Usage
SeleniumSession$print_page(
orientation = c("portrait", "landscape"),
scale = 1,
background = FALSE,
width = NULL,
height = NULL,
margin = NULL,
footer = NULL,
header = NULL,
shrink_to_fit = NULL,
page_ranges = NULL,
request_body = NULL,
timeout = 20
)Arguments
orientationThe page orientation, either
"portrait"or"landscape".scaleThe page scale, a number between 0.1 and 2.
backgroundWhether to print the background of the page.
widthThe page width, in inches.
heightThe page height, in inches.
marginThe page margin, in inches. Either a number, in which case the margin on all sides are set to that value, or a list of four numbers, with names
left,right,top, andbottom, in which case the margin on each side is set individually.footerThe page footer, as a string.
headerThe page header, as a string.
shrink_to_fitWhether to shrink the page to fit the width and height.
page_rangesA list of page ranges (e.g.
"1","1-3") to print.request_bodyA list of request body parameters to pass to the Selenium server, overriding the default body of the web request
timeoutHow long to wait for a request to recieve a response before throwing an error.
Examples
## ------------------------------------------------
## Method `SeleniumSession$new`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new(verbose = TRUE)
session$close()
} # }
## ------------------------------------------------
## Method `SeleniumSession$create_webelement`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new()
element <- session$find_element(using = "css selector", value = "*")
element2 <- session$create_webelement(id = element$id)
session$close()
} # }
## ------------------------------------------------
## Method `SeleniumSession$create_shadowroot`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new()
shadow_root <- session$create_shadowroot(id = "foo")
session$close()
} # }
## ------------------------------------------------
## Method `SeleniumSession$close`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new()
session$close()
} # }
## ------------------------------------------------
## Method `SeleniumSession$status`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new()
session$status()
session$close()
session$status()
} # }
## ------------------------------------------------
## Method `SeleniumSession$get_timeouts`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new()
session$get_timeouts()
session$close()
} # }
## ------------------------------------------------
## Method `SeleniumSession$set_timeouts`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new()
session$set_timeouts(script = 100)
session$get_timeouts()
session$close()
} # }
## ------------------------------------------------
## Method `SeleniumSession$navigate`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new()
session$navigate("https://www.r-project.org")
session$close()
} # }
## ------------------------------------------------
## Method `SeleniumSession$current_url`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new()
session$navigate("https://www.r-project.org")
session$current_url()
session$close()
} # }
## ------------------------------------------------
## Method `SeleniumSession$back`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new()
session$navigate("https://www.r-project.org")
session$navigate("https://www.tidyverse.org")
session$back()
session$current_url()
session$close()
} # }
## ------------------------------------------------
## Method `SeleniumSession$forward`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new()
session$navigate("https://www.r-project.org")
session$navigate("https://www.tidyverse.org")
session$back()
session$forward()
session$current_url()
session$close()
} # }
## ------------------------------------------------
## Method `SeleniumSession$refresh`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new()
session$navigate("https://www.r-project.org")
session$refresh()
session$close()
} # }
## ------------------------------------------------
## Method `SeleniumSession$title`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new()
session$navigate("https://www.r-project.org")
session$title()
session$close()
} # }
## ------------------------------------------------
## Method `SeleniumSession$window_handle`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new()
session$window_handle()
session$close()
} # }
## ------------------------------------------------
## Method `SeleniumSession$close_window`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new()
session$new_window()
session$close_window()
session$close()
} # }
## ------------------------------------------------
## Method `SeleniumSession$switch_to_window`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new()
handle <- session$window_handle()
handle2 <- session$new_window()$handle
session$switch_to_window(handle)
session$switch_to_window(handle2)
session$close()
} # }
## ------------------------------------------------
## Method `SeleniumSession$window_handles`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new()
handles <- session$window_handles()
session$close()
} # }
## ------------------------------------------------
## Method `SeleniumSession$new_window`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new()
handle <- session$new_window()$handle
session$switch_to_window(handle)
session$close()
} # }
## ------------------------------------------------
## Method `SeleniumSession$switch_to_frame`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new()
session$navigate("https://www.r-project.org")
session$switch_to_frame()
session$close()
} # }
## ------------------------------------------------
## Method `SeleniumSession$switch_to_parent_frame`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new()
session$navigate("https://www.r-project.org")
session$switch_to_frame()
session$switch_to_parent_frame()
session$close()
} # }
## ------------------------------------------------
## Method `SeleniumSession$get_window_rect`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new()
session$get_window_rect()
session$close()
} # }
## ------------------------------------------------
## Method `SeleniumSession$set_window_rect`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new()
session$navigate("https://www.r-project.org")
session$set_window_rect(width = 800, height = 600, x = 2, y = 3)
session$close()
} # }
## ------------------------------------------------
## Method `SeleniumSession$maximize_window`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new()
session$maximize_window()
session$close()
} # }
## ------------------------------------------------
## Method `SeleniumSession$minimize_window`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new()
session$minimize_window()
session$close()
} # }
## ------------------------------------------------
## Method `SeleniumSession$fullscreen_window`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new()
session$fullscreen_window()
session$close()
} # }
## ------------------------------------------------
## Method `SeleniumSession$get_active_element`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new()
session$navigate("https://www.r-project.org")
session$get_active_element()
session$close()
} # }
## ------------------------------------------------
## Method `SeleniumSession$find_element`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new()
session$navigate("https://www.r-project.org")
session$find_element(using = "css selector", value = "#download")
session$find_element(using = "xpath", value = "//div[contains(@class, 'col-xs')]/h1")
session$close()
} # }
## ------------------------------------------------
## Method `SeleniumSession$find_elements`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new()
session$navigate("https://www.r-project.org")
session$find_elements(using = "css selector", value = "h1")
session$find_elements(using = "xpath", value = "//h1")
session$close()
} # }
## ------------------------------------------------
## Method `SeleniumSession$get_page_source`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new()
session$navigate("https://www.r-project.org")
session$get_page_source()
session$close()
} # }
## ------------------------------------------------
## Method `SeleniumSession$execute_script`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new()
session$execute_script("return 1")
session$execute_script("return arguments[0] + arguments[1]", 1, 2)
element <- session$find_element(value = "*")
session$execute_script("return arguments[0]", element)
session$close()
} # }
## ------------------------------------------------
## Method `SeleniumSession$execute_async_script`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new()
session$execute_async_script("
let callback = arguments[arguments.length - 1];
callback(1)
")
session$close()
} # }
## ------------------------------------------------
## Method `SeleniumSession$get_cookies`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new()
session$navigate("https://www.r-project.org")
session$get_cookies()
session$close()
} # }
## ------------------------------------------------
## Method `SeleniumSession$get_cookie`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new()
session$navigate("https://www.r-project.org")
session$add_cookie(list(name = "foo", value = "bar"))
session$get_cookie("foo")
session$close()
} # }
## ------------------------------------------------
## Method `SeleniumSession$add_cookie`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new()
session$navigate("https://www.r-project.org")
session$add_cookie(list(name = "my_cookie", value = "1"))
session$close()
} # }
## ------------------------------------------------
## Method `SeleniumSession$delete_cookie`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new()
session$navigate("https://www.r-project.org")
session$add_cookie(list(name = "foo", value = "bar"))
session$delete_cookie("foo")
session$close()
} # }
## ------------------------------------------------
## Method `SeleniumSession$delete_all_cookies`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new()
session$navigate("https://www.r-project.org")
session$delete_all_cookies()
session$close()
} # }
## ------------------------------------------------
## Method `SeleniumSession$perform_actions`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new()
session$navigate("https://www.r-project.org")
actions <- actions_stream(
actions_press(keys$enter),
actions_pause(0.5),
actions_release(keys$enter)
)
session$perform_actions(actions)
session$close()
} # }
## ------------------------------------------------
## Method `SeleniumSession$release_actions`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new()
session$navigate("https://www.r-project.org")
actions <- actions_stream(
actions_press("a")
)
session$perform_actions(actions, release_actions = FALSE)
session$release_actions()
session$close()
} # }
## ------------------------------------------------
## Method `SeleniumSession$dismiss_alert`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new()
session$execute_script("alert('hello')")
session$dismiss_alert()
session$close()
} # }
## ------------------------------------------------
## Method `SeleniumSession$accept_alert`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new()
session$execute_script("alert('hello')")
session$accept_alert()
session$close()
} # }
## ------------------------------------------------
## Method `SeleniumSession$get_alert_text`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new()
session$execute_script("alert('hello')")
session$get_alert_text()
session$close()
} # }
## ------------------------------------------------
## Method `SeleniumSession$send_alert_text`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new()
session$execute_script("prompt('Enter text:')")
session$send_alert_text("hello")
session$close()
} # }
## ------------------------------------------------
## Method `SeleniumSession$screenshot`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new()
session$navigate("https://www.r-project.org")
session$screenshot()
session$close()
} # }
## ------------------------------------------------
## Method `SeleniumSession$print_page`
## ------------------------------------------------
if (FALSE) { # \dontrun{
session <- SeleniumSession$new()
session$navigate("https://www.r-project.org")
session$print_page()
session$close()
} # }