man/Chrome.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/Chrome.R
\name{Chrome}
\alias{Chrome}
\title{Launch Chromium or Chrome}
\description{
This class aims to launch Chromium or Chrome in headless mode. It possesses
methods to manage connections to headless Chromium/Chrome using the
Chrome Debugging Protocol.
}
\section{Usage}{
\preformatted{remote <- Chrome$new(bin = NULL, debug_port = 9222L,
                     local = FALSE, extra_args = NULL, headless = TRUE,
                     retry_delay = 0.2, max_attempts = 15L)

remote$connect(callback = NULL)
remote$listConnections()
remote$closeConnections(callback = NULL)
remote$version()
remote$user_agent

remote$close(async = FALSE)
remote$view()
remote$is_alive()
}
}

\section{Arguments}{

\itemize{
\item \code{remote}: \code{Chrome} object representing a remote instance of headless
Chromium/Chrome.
\item \code{bin}: Character scalar, the path to Chromium or Chrome executable.
If not provided, \code{crrri} will try to find the chrome binary itself using
\code{find_chrome_binary()}. You can set a path in \code{HEADLESS_CHROME} environment
variable to indicate where it is located.
\item \code{debug_port}: Integer scalar, the Chromium/Chrome remote debugging port.
Note that headless Chromium/Chrome will be available at
\verb{http://localhost:<debug_port>}.
\item \code{local}: Logical scalar, indicating whether the local version of the
protocol (embedded in \code{crrri}) must be used or the protocol must be
fetched \emph{remotely}.
\item \code{extra_args}: Character vector, extra command line arguments passed to
Chromium/Chrome. You can know more about command line flags (or switches)
from \href{https://www.chromium.org/developers/how-tos/run-chromium-with-flags}{chromium developers}
\item \code{headless}: Logical scalar, indicating whether Chromium/Chrome is launched
in headless mode.
\item \code{retry_delay}: Number, delay in seconds between two successive tries to
connect to headless Chromium/Chrome.
\item \code{max_attempts}: Integer scalar, number of tries to connect to headless
Chromium/Chrome.
\item \code{callback}: Function with one argument.
\item \code{async}: Does the function return a promise?
}
}

\section{Details}{

\verb{$new()} opens a new headless Chromium/Chrome. You can deactivate verbose
from chrome process launching byt setting option \code{crrri.verbose} to FALSE.

\verb{$connect(callback = NULL)} connects the R session to the remote instance of
headless Chromium/Chrome. The returned value depends on the value of the
\code{callback} argument. When \code{callback} is a function, the returned value is a
connection object. When \code{callback} is \code{NULL} the returned value is a promise
which fulfills once R is connected to the remote instance of Chromium/Chrome.
Once fulfilled, the value of this promise is the connection object.

\verb{$listConnections()} returns a list of the connection objects succesfully
created using the \verb{$connect()} method.

\verb{$closeConnections(callback = NULL)} closes all the connections created using the
\verb{$connect()} method.  If \code{callback} is \code{NULL}, it returns a promise which
fulfills when all the connections are closed: once fulfilled, its value is the
remote object.
If \code{callback} is not \code{NULL}, it returns the remote object. In this case,
\code{callback} is called when all the connections are closed and the remote object is
passed to this function as the argument.

\verb{$version()} executes the DevTools \code{Version} method. It returns a list of
informations available at \verb{http://localhost:<debug_port>/json/version}.

\verb{$user_agent} returns a character scalar with the User Agent of the
headless Chromium/Chrome.

\verb{$close(async = FALSE)} closes the remote instance of headless
Chromium/Chrome. If \code{async} is \code{FALSE} this method returns the \code{remote}
object invisibly. Is \code{async} is \code{TRUE}, a promise is returned. This promise
fulfills when Chromium/Chrome is closed. Once fulfilled, its value is the
\code{remote} object.

\verb{$view()} opens a visible Chromium/Chrome browser at
\verb{http://localhost:<debug_port>}. This is useful to 'see' the headless
Chromium/Chrome instance. Returns the process of the visible browser.

\verb{$is_alive()} checks if the remote instance is alive. Returns a logical
scalar.

\verb{$listTargets()} returns a list with information about tabs.
}

\examples{
\dontrun{

remote <- Chrome$new()

remote$connect() \%...>\% (function(client) {
  Page <- client$Page
  Runtime <- client$Runtime

  Page$enable() \%...>\% {
    Page$navigate(url = 'http://r-project.org')
  } \%...>\% {
    Page$loadEventFired()
  } \%...>\% {
    Runtime$evaluate(
      expression = 'document.documentElement.outerHTML'
    )
  } \%...>\% (function(result) {
    cat(result$result$value, "\n")
  })
}) \%...!\% {
  cat("Error:", .$message, "\n")
} \%>\%
  promises::finally(~ remote$close())
}

}