Hide RSelenium more in documentation (#31)

* update roxygen2

* Move away from RSelenium in documentation

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

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

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

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)) {

_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