From 41eff65b04cc7883d5135a79ef590ab9a8581577 Mon Sep 17 00:00:00 2001 From: Ashby Thorpe <61390103+ashbythorpe@users.noreply.github.com> Date: Tue, 8 Oct 2024 23:26:48 +0100 Subject: [PATCH] Hide RSelenium more in documentation (#31) * update roxygen2 * Move away from RSelenium in documentation --- DESCRIPTION | 2 +- R/session-options.R | 116 ++++++++++++++++++++---------------- R/session.R | 18 +++--- R/utils.R | 11 ++-- _pkgdown.yml | 3 +- man/chromote_options.Rd | 47 ++------------- man/selenider_available.Rd | 9 +-- man/selenider_session.Rd | 13 ++-- man/wdman_server_options.Rd | 64 ++++++++++++++++++++ 9 files changed, 162 insertions(+), 121 deletions(-) create mode 100644 man/wdman_server_options.Rd diff --git a/DESCRIPTION b/DESCRIPTION index b36f3092..0b87020b 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -11,7 +11,7 @@ Description: A user-friendly wrapper for web automation, using either resulting in reliable and reproducible code, with no visible impact on the experience of the programmer. License: MIT + file LICENSE -RoxygenNote: 7.3.1 +RoxygenNote: 7.3.2 URL: https://github.com/ashbythorpe/selenider, https://ashbythorpe.github.io/selenider/ BugReports: https://github.com/ashbythorpe/selenider/issues diff --git a/R/session-options.R b/R/session-options.R index 1d72d444..9ee20d56 100644 --- a/R/session-options.R +++ b/R/session-options.R @@ -9,24 +9,15 @@ #' #' `selenium_options()` allows you to control the creation of a selenium driver. #' -#' `selenium_server_options()` and `wdman_server_options()` should be passed to -#' the `server_options` argument of `selenium_options()`. By default, the former -#' is used, meaning that the server is created using -#' [selenium::selenium_server()]. If `wdman_server_options()` is used instead, -#' the server will be created using [wdman::selenium()]. +#' `selenium_server_options()` should be passed to the `server_options` +#' argument of `selenium_options()`, allowing you to control the creation of +#' the server using [selenium::selenium_server()]. #' #' `selenium_client_options()` should be passed to the `client_options` argument #' of `selenium_options()`, allowing you to control the creation of a Selenium #' client created using #' [selenium::SeleniumSession$new()][selenium::SeleniumSession]. #' -#' `r lifecycle::badge("superseded")` -#' -#' Instead of using `selenium_client_options()`, you can use -#' `rselenium_client_options()` to control the creation of an -#' [RSelenium::remoteDriver()] object instead. This is not recommended, since -#' RSelenium is incompatible with newer versions of Selenium. -#' #' @param headless Whether to run the browser in headless mode, meaning #' that you won't actually be able to see the browser as you control it. #' For debugging purposes and interactive use, it is often useful to set @@ -70,8 +61,7 @@ chromote_options <- function(headless = TRUE, #' @rdname chromote_options #' #' @param client_options A [selenium_client_options()] object. -#' @param server_options A [selenium_server_options()] or -#' [wdman_server_options()] object. +#' @param server_options A [selenium_server_options()] object. #' #' @export selenium_options <- function(client_options = selenium_client_options(), @@ -133,12 +123,70 @@ selenium_server_options <- function(version = "latest", result } + #' @rdname chromote_options #' +#' @param host,capabilities,request_body,timeout +#' Passed into [selenium::SeleniumSession$new()][selenium::SeleniumSession]. +#' +#' @export +selenium_client_options <- function(port = 4444L, + host = "localhost", + verbose = FALSE, + capabilities = NULL, + request_body = NULL, + timeout = 60) { + check_number_whole(port) + check_string(host) + check_bool(verbose) + check_list(capabilities, allow_null = TRUE) + check_list(request_body, allow_null = TRUE) + check_number_decimal(timeout) + + result <- list( + port = port, + host = host, + verbose = verbose, + capabilities = capabilities, + request_body = request_body, + timeout = timeout + ) + + class(result) <- "selenium_client_options" + + result +} + +#' RSelenium options +#' +#' `r lifecycle::badge("superseded")` +#' Instruct selenider to use RSelenium instead of selenium. Passed into +#' [selenium_options()]. This is not recommended, since RSelenium does not +#' support the latest version of Selenium, and wdman (the server manager that +#' RSelenium) uses, is not compatible with the latest version of Chrome. +#' +#' @param version The version of Selenium server to use. #' @param driver_version The version of the browser-specific driver to use. -#' @param check,retcommand,... +#' @param port The port to run selenium client/server on. +#' @param check,verbose,retcommand,... #' Passed into [wdman::selenium()]. #' +#' @details +#' In [selenium_options()], you can supply options to configure a server and +#' client run by RSelenium instead of selenium. +#' Instead of `selenium_server_options()`, you can use `wdman_server_options()` +#' to allow `wdman` to run the Selenium server using [wdman::selenium()]. +#' +#' Instead of using `selenium_client_options()`, you can use +#' `rselenium_client_options()` to control the creation of an +#' [RSelenium::remoteDriver()] object instead. +#' +#' Note that the `driver` option of `selenider_session()` also accepts these +#' objects in place of their selenium equivalents. +#' +#' @returns +#' An options object that can be passed into [selenium_options()]. +#' #' @export wdman_server_options <- function(version = "latest", driver_version = "latest", @@ -169,42 +217,10 @@ wdman_server_options <- function(version = "latest", result } -#' @rdname chromote_options -#' -#' @param host,capabilities,request_body,timeout -#' Passed into [selenium::SeleniumSession$new()][selenium::SeleniumSession]. -#' -#' @export -selenium_client_options <- function(port = 4444L, - host = "localhost", - verbose = FALSE, - capabilities = NULL, - request_body = NULL, - timeout = 60) { - check_number_whole(port) - check_string(host) - check_bool(verbose) - check_list(capabilities, allow_null = TRUE) - check_list(request_body, allow_null = TRUE) - check_number_decimal(timeout) - - result <- list( - port = port, - host = host, - verbose = verbose, - capabilities = capabilities, - request_body = request_body, - timeout = timeout - ) - - class(result) <- "selenium_client_options" - - result -} - -#' @rdname chromote_options +#' @rdname wdman_server_options #' -#' @param platform,javascript,native_events,extra_capabilities +#' @param host The host to connect to the selenium server over. +#' @param path,platform,javascript,native_events,extra_capabilities #' Passed into [RSelenium::remoteDriver()]. #' #' @export diff --git a/R/session.R b/R/session.R index b947b10d..4317f4d2 100644 --- a/R/session.R +++ b/R/session.R @@ -6,9 +6,9 @@ #' environment where it was defined. #' #' @param session The package to use as a backend: either "chromote", -#' "selenium" or "rselenium". By default, chromote is used, since this tends -#' to be faster and more reliable. Change the default value using the -#' `selenider.session` option. +#' "selenium". By default, chromote is used, since this tends to be faster +#' and more reliable. Change the default value using the `selenider.session` +#' option. #' @param 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 @@ -24,13 +24,10 @@ #' * A [chromote::ChromoteSession] object. #' * A [shinytest2::AppDriver] object. #' * An [selenium::SeleniumSession] object. -#' * A Selenium server object, created by [selenium::selenium_server()] or -#' [wdman::selenium()]. In this case, a client will be created using the -#' server 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. -#' * An [RSelenium::remoteDriver()] object can be used instead of a -#' [selenium::SeleniumSession] object. #' @param local Whether to set the session as the local session object, #' using [local_session()]. #' @param .env Passed into [local_session()], to define the @@ -362,6 +359,11 @@ check_options <- function(session, options, call = rlang::caller_env()) { "x" = "A {.cls {class(options$client_options)}} object was provided instead." )) } + } else { + cli::cli_abort( + "Session must be \"chromote\" or \"selenium\", not {.val {session}}.", + call = call + ) } options diff --git a/R/utils.R b/R/utils.R index 087b467f..5c79df98 100644 --- a/R/utils.R +++ b/R/utils.R @@ -51,7 +51,7 @@ retry_until_true <- function(timeout, .f, ...) { #' Specifically, the following is checked: #' #' * The `SELENIDER_AVAILABLE` environment variable. Set this to `"TRUE" `or -#' `"FALSE"` to override this function. +#' `"FALSE"` to override the return value of this function. #' * Whether we are on CRAN (using the `NOT_CRAN` environment variable). If we #' are, the function returns `FALSE`. #' * Whether an internet connection is available (using [curl::nslookup()]). @@ -64,7 +64,7 @@ retry_until_true <- function(timeout, .f, ...) { #' If `session` is `"selenium"`, we check: #' #' * Whether `selenium` is installed. -#' * Whether we can find a valid browser that is supported by `RSelenium`. +#' * Whether we can find a valid browser that is supported by `selenium`. #' #' @returns #' A boolean flag: `TRUE` or `FALSE`. @@ -74,10 +74,13 @@ retry_until_true <- function(timeout, .f, ...) { #' #' @export selenider_available <- function( - session = c("chromote", "selenium", "rselenium"), + session = c("chromote", "selenium"), online = TRUE) { check_bool(online) - session <- arg_match(session) + + if (!identical(session, "rselenium")) { + session <- arg_match(session) + } env_variable <- as.logical(Sys.getenv("SELENIDER_AVAILABLE")) if (isTRUE(env_variable)) { diff --git a/_pkgdown.yml b/_pkgdown.yml index f934b886..cc50fb52 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -56,8 +56,9 @@ reference: - title: Configuration - contents: - selenider-config - - title: Deprecated functions + - title: Superceded and deprecated functions - contents: + - wdman_server_options - create_chromote_session - element_list - print_lazy diff --git a/man/chromote_options.Rd b/man/chromote_options.Rd index 212762ef..e168d317 100644 --- a/man/chromote_options.Rd +++ b/man/chromote_options.Rd @@ -4,9 +4,7 @@ \alias{chromote_options} \alias{selenium_options} \alias{selenium_server_options} -\alias{wdman_server_options} \alias{selenium_client_options} -\alias{rselenium_client_options} \title{Driver options} \usage{ chromote_options( @@ -36,16 +34,6 @@ selenium_server_options( extra_args = c() ) -wdman_server_options( - version = "latest", - driver_version = "latest", - port = 4444L, - check = TRUE, - verbose = FALSE, - retcommand = FALSE, - ... -) - selenium_client_options( port = 4444L, host = "localhost", @@ -54,17 +42,6 @@ selenium_client_options( request_body = NULL, timeout = 60 ) - -rselenium_client_options( - port = 4444L, - host = "localhost", - path = "/wd/hub", - version = "", - platform = "ANY", - javascript = TRUE, - native_events = TRUE, - extra_capabilities = list() -) } \arguments{ \item{headless}{Whether to run the browser in headless mode, meaning @@ -79,8 +56,7 @@ this to \code{FALSE}.} \item{client_options}{A \code{\link[=selenium_client_options]{selenium_client_options()}} object.} -\item{server_options}{A \code{\link[=selenium_server_options]{selenium_server_options()}} or -\code{\link[=wdman_server_options]{wdman_server_options()}} object.} +\item{server_options}{A \code{\link[=selenium_server_options]{selenium_server_options()}} object.} \item{version}{The version of Selenium server to use.} @@ -88,13 +64,7 @@ this to \code{FALSE}.} \item{selenium_manager, verbose, temp, path, interactive, echo_cmd, extra_args}{Passed into \code{\link[selenium:selenium_server]{selenium::selenium_server()}}.} -\item{driver_version}{The version of the browser-specific driver to use.} - -\item{check, retcommand, ...}{Passed into \code{\link[wdman:selenium]{wdman::selenium()}}.} - \item{host, capabilities, request_body, timeout}{Passed into \link[selenium:SeleniumSession]{selenium::SeleniumSession$new()}.} - -\item{platform, javascript, native_events, extra_capabilities}{Passed into \code{\link[RSelenium:remoteDriver-class]{RSelenium::remoteDriver()}}.} } \description{ \code{chromote_options()} and \code{selenium_options()} return a list of options that @@ -105,21 +75,12 @@ created using \link[chromote:ChromoteSession]{chromote::ChromoteSession$new()}. \code{selenium_options()} allows you to control the creation of a selenium driver. -\code{selenium_server_options()} and \code{wdman_server_options()} should be passed to -the \code{server_options} argument of \code{selenium_options()}. By default, the former -is used, meaning that the server is created using -\code{\link[selenium:selenium_server]{selenium::selenium_server()}}. If \code{wdman_server_options()} is used instead, -the server will be created using \code{\link[wdman:selenium]{wdman::selenium()}}. +\code{selenium_server_options()} should be passed to the \code{server_options} +argument of \code{selenium_options()}, allowing you to control the creation of +the server using \code{\link[selenium:selenium_server]{selenium::selenium_server()}}. \code{selenium_client_options()} should be passed to the \code{client_options} argument of \code{selenium_options()}, allowing you to control the creation of a Selenium client created using \link[selenium:SeleniumSession]{selenium::SeleniumSession$new()}. - -\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#superseded}{\figure{lifecycle-superseded.svg}{options: alt='[Superseded]'}}}{\strong{[Superseded]}} - -Instead of using \code{selenium_client_options()}, you can use -\code{rselenium_client_options()} to control the creation of an -\code{\link[RSelenium:remoteDriver-class]{RSelenium::remoteDriver()}} object instead. This is not recommended, since -RSelenium is incompatible with newer versions of Selenium. } diff --git a/man/selenider_available.Rd b/man/selenider_available.Rd index dcb4bd9d..fdf184b1 100644 --- a/man/selenider_available.Rd +++ b/man/selenider_available.Rd @@ -5,10 +5,7 @@ \alias{skip_if_selenider_unavailable} \title{Check if selenider can be used} \usage{ -selenider_available( - session = c("chromote", "selenium", "rselenium"), - online = TRUE -) +selenider_available(session = c("chromote", "selenium"), online = TRUE) skip_if_selenider_unavailable(session = c("chromote", "selenium")) } @@ -32,7 +29,7 @@ environment where it makes sense to open a selenider session. Specifically, the following is checked: \itemize{ \item The \code{SELENIDER_AVAILABLE} environment variable. Set this to \code{"TRUE" }or -\code{"FALSE"} to override this function. +\code{"FALSE"} to override the return value of this function. \item Whether we are on CRAN (using the \code{NOT_CRAN} environment variable). If we are, the function returns \code{FALSE}. \item Whether an internet connection is available (using \code{\link[curl:nslookup]{curl::nslookup()}}). @@ -47,7 +44,7 @@ If \code{session} is \code{"chromote"}, we also check: If \code{session} is \code{"selenium"}, we check: \itemize{ \item Whether \code{selenium} is installed. -\item Whether we can find a valid browser that is supported by \code{RSelenium}. +\item Whether we can find a valid browser that is supported by \code{selenium}. } } \examples{ diff --git a/man/selenider_session.Rd b/man/selenider_session.Rd index d52d17a8..a9ddb553 100644 --- a/man/selenider_session.Rd +++ b/man/selenider_session.Rd @@ -19,9 +19,9 @@ selenider_session( } \arguments{ \item{session}{The package to use as a backend: either "chromote", -"selenium" or "rselenium". By default, chromote is used, since this tends -to be faster and more reliable. Change the default value using the -\code{selenider.session} option.} +"selenium". By default, chromote is used, since this tends to be faster +and more reliable. Change the default value using the \code{selenider.session} +option.} \item{browser}{The name of the browser to run the session in; one of "chrome", "firefox", "edge", "safari", or another valid browser name. @@ -42,13 +42,10 @@ can be one of: \item A \link[chromote:ChromoteSession]{chromote::ChromoteSession} object. \item A \link[shinytest2:AppDriver]{shinytest2::AppDriver} object. \item An \link[selenium:SeleniumSession]{selenium::SeleniumSession} object. -\item A Selenium server object, created by \code{\link[selenium:selenium_server]{selenium::selenium_server()}} or -\code{\link[wdman:selenium]{wdman::selenium()}}. In this case, a client will be created using the -server object. +\item A Selenium server object, created by \code{\link[selenium:selenium_server]{selenium::selenium_server()}}. In +this case, a client will be created using the server object. \item A list/environment containing the \link[selenium:SeleniumSession]{selenium::SeleniumSession} object, the Selenium server object, or both. -\item An \code{\link[RSelenium:remoteDriver-class]{RSelenium::remoteDriver()}} object can be used instead of a -\link[selenium:SeleniumSession]{selenium::SeleniumSession} object. }} \item{local}{Whether to set the session as the local session object, diff --git a/man/wdman_server_options.Rd b/man/wdman_server_options.Rd new file mode 100644 index 00000000..e6d9af8a --- /dev/null +++ b/man/wdman_server_options.Rd @@ -0,0 +1,64 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/session-options.R +\name{wdman_server_options} +\alias{wdman_server_options} +\alias{rselenium_client_options} +\title{RSelenium options} +\usage{ +wdman_server_options( + version = "latest", + driver_version = "latest", + port = 4444L, + check = TRUE, + verbose = FALSE, + retcommand = FALSE, + ... +) + +rselenium_client_options( + port = 4444L, + host = "localhost", + path = "/wd/hub", + version = "", + platform = "ANY", + javascript = TRUE, + native_events = TRUE, + extra_capabilities = list() +) +} +\arguments{ +\item{version}{The version of Selenium server to use.} + +\item{driver_version}{The version of the browser-specific driver to use.} + +\item{port}{The port to run selenium client/server on.} + +\item{check, verbose, retcommand, ...}{Passed into \code{\link[wdman:selenium]{wdman::selenium()}}.} + +\item{host}{The host to connect to the selenium server over.} + +\item{path, platform, javascript, native_events, extra_capabilities}{Passed into \code{\link[RSelenium:remoteDriver-class]{RSelenium::remoteDriver()}}.} +} +\value{ +An options object that can be passed into \code{\link[=selenium_options]{selenium_options()}}. +} +\description{ +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#superseded}{\figure{lifecycle-superseded.svg}{options: alt='[Superseded]'}}}{\strong{[Superseded]}} +Instruct selenider to use RSelenium instead of selenium. Passed into +\code{\link[=selenium_options]{selenium_options()}}. This is not recommended, since RSelenium does not +support the latest version of Selenium, and wdman (the server manager that +RSelenium) uses, is not compatible with the latest version of Chrome. +} +\details{ +In \code{\link[=selenium_options]{selenium_options()}}, you can supply options to configure a server and +client run by RSelenium instead of selenium. +Instead of \code{selenium_server_options()}, you can use \code{wdman_server_options()} +to allow \code{wdman} to run the Selenium server using \code{\link[wdman:selenium]{wdman::selenium()}}. + +Instead of using \code{selenium_client_options()}, you can use +\code{rselenium_client_options()} to control the creation of an +\code{\link[RSelenium:remoteDriver-class]{RSelenium::remoteDriver()}} object instead. + +Note that the \code{driver} option of \code{selenider_session()} also accepts these +objects in place of their selenium equivalents. +}