selenider_session: Start a session

In selenider: Concise, Lazy and Reliable Wrapper for 'chromote' and 'selenium'

Start a session

Description

Create a session in selenider. If you create a session in the global environment it will be made available to other functions (like open_url()) without having to pass it in, and will close automatically when the R session is closed. Alternatively, if it is created inside a function, it will be closed as soon as the function finishes executing. To customise this, use the .env and local arguments.

Usage

selenider_session(
  session = getOption("selenider.session"),
  browser = getOption("selenider.browser"),
  timeout = 4,
  options = NULL,
  driver = NULL,
  local = TRUE,
  .env = rlang::caller_env(),
  view = FALSE,
  selenium_manager = TRUE,
  quiet = TRUE
)

Arguments

session	The package to use as a backend: either "chromote", "selenium". By default, chromote is used, since this tends to be faster and more reliable. Change the default value using the selenider.session option.
browser	The name of the browser to run the session in; one of "chrome", "firefox", "edge", "safari", or another valid browser name. If NULL, the function will try to work out which browser you have installed. If we are using chromote, this option is ignored, since chromote only works on Chrome. Change the default value of this parameter using the selenider.browser option.
timeout	The default time to wait when collecting an element.
options	A chromote_options() or selenium_options() object, used to specify options that are specific to chromote or selenium. See Details for some useful examples of this.
driver	A driver object to use instead of creating one manually. This can be one of: A chromote::ChromoteSession object. A shinytest2::AppDriver object. An selenium::SeleniumSession object. A Selenium server object, created by selenium::selenium_server(). In this case, a client will be created using the server object. A list/environment containing the selenium::SeleniumSession object, the Selenium server object, or both.
local	Whether to set the session as the local session object, using local_session(). If this is FALSE, you will have to pass this into the session argument of other functions (like open_url()), and close the session manually using close_session().
.env	Passed into local_session(), to define the environment in which the session is used. Change this if you want to create the session inside a function and then use it outside the function (see Examples). Use rlang::caller_env() in this case.
view, selenium_manager, quiet	Use the options argument instead.

Value

A selenider_session object. Use session$driver to retrieve the driver object that controls the browser.

Useful session-specific options

See chromote_options() and selenium_options() for the full range.

Making a chromote session non-headless

By default, chromote will run in headless mode, meaning that you won't actually be able to see the browser as you control it. Use the view argument to chromote_options() to change this:

session <- selenider_session(
  options = chromote_options(view = TRUE)
)

Prevent creation of a selenium server

Sometimes, you want to manage the Selenium server separately, and only let selenider create client objects to attach to the server. You can do this by passing NULL into the server_options argument to selenium_options():

session <- selenider_session(
  "selenium",
  options = selenium_options(server_options = NULL)
)

If the port you are using is not 4444, you will need to pass in the port argument to selenium_client_options() as well:

session <- selenider_session(
  "selenium",
  options = selenium_options(
    client_options = selenium_client_options(port = YOUR_PORT),
    server_options = NULL
  )
)

One example of when this may be useful is when you are managing the Selenium server using Docker.

Store the Selenium server persistently

By default, selenium will download and store the Selenium server JAR file in a temporary directory, which will be deleted when the R session finishes. This means that every time you start a new R session, this file will be re-downloaded. You can store the JAR file permanently using the temp argument to selenium_server_options():

session <- selenider_session(
  "selenium",
  options = selenium_options(
    server_options = selenium_server_options(temp = TRUE)
  )
)

The downside of this is you may end up using a lot of storage, especially if a new version of Selenium is released and the old server file is left on the filesystem.

You can also use the path argument to selenium_server_options() to specify the directory where the JAR file should be stored.

Structure of a selenider session

A selenider_session object has several components that can be useful to access:

• session - The type of session, either "chromote" or "selenium".

• driver - The driver object used to control the browser. This is either a chromote::ChromoteSession or selenium::SeleniumSession object. This is useful if you want to do something with the driver that is not directly supported by selenider. See get_actual_element() for some examples of this.

• server - The Selenium server object, if one was created or passed in.

• id - A unique ID that can be used to identify the session.

Access these components using $ (e.g. session$driver).

Custom drivers

If you want complete manual control over creating the underlying driver, you can pass your own driver argument to stop selenider from creating the driver for you.

You can also supply a shinytest2::AppDriver object, allowing selenider and shinytest2 to share a session:

shiny_app <- shiny::shinyApp(
  ui = shiny::fluidPage(
    # ... Your UI
  ),
  server = function(input, output) {
    # ... Your server
  }
)

app <- shinytest2::AppDriver$new()

session <- selenider_session(
  driver = app
)

See Also

• close_session() to close the session. Note that this will not reset the result of get_session(), which is why withr::deferred_run() is preferred.

• local_session() and with_session() to manually set the local session object (and get_session() to get it).

• open_url(), s() and find_elements() to get started once you have created a session.

Examples

session_1 <- selenider_session(timeout = 10)
# session_1 is the local session here

get_session() # Returns session 1

my_function <- function() {
  session_2 <- selenider_session()

  # In here, session_2 is the local session
  get_session()
} # When the function finishes executing, the session is closed

my_function() # Returns `session_2`

# If we want to use a session outside the scope of a function,
# we need to use the `.env` argument.
create_session <- function(timeout = 10, .env = rlang::caller_env()) {
  # caller_env() is the environment where the function is called
  selenider_session(timeout = timeout, .env = .env)
}

my_session <- create_session()

# We can now use this session outside the `create_session()` function
get_session()

# `my_session` will be closed automatically.

selenider documentation built on April 3, 2025, 5:51 p.m.