ChromoteSession class

This represents one session in a Chromote object. Note that in the Chrome DevTools Protocol a session is a debugging session connected to a target, which is a browser window/tab or an iframe.

A single target can potentially have more than one session connected to it, but this is not currently supported by chromote.

Public fields

parent: Chromote object
default_timeout: Default timeout in seconds for chromote to wait for a Chrome DevTools Protocol response.
protocol: Dynamic protocol implementation. For expert use only!

Methods

Method `new()`

Create a new ChromoteSession object.

Examples

# Create a new `ChromoteSession` object.
b <- ChromoteSession$new()

# Create a ChromoteSession with a specific height,width
b <- ChromoteSession$new(height = 1080, width = 1920)

# Navigate to page
b$Page$navigate("http://www.r-project.org/")

# View current chromote session
if (interactive()) b$view()

Usage

ChromoteSession$new(
  parent = default_chromote_object(),
  width = 992,
  height = 1323,
  targetId = NULL,
  wait_ = TRUE,
  auto_events = NULL
)

Arguments

parent: Chromote object to use; defaults to default_chromote_object()
width, height: Width and height of the new window.
targetId: Target ID of an existing target to attach to. When a targetId is provided, the width and height arguments are ignored. If NULL (the default) a new target is created and attached to, and the width and height arguments determine its viewport size.
wait_: If FALSE, return a promises::promise() of a new ChromoteSession object. Otherwise, block during initialization, and return a ChromoteSession object directly.
auto_events: If NULL (the default), use the auto_events setting from the parent Chromote object. If TRUE, enable automatic event enabling/disabling; if FALSE, disable automatic event enabling/disabling.

Returns

A new ChromoteSession object.

Method `view()`

Display the current session in the Chromote browser.

If a Chrome browser is being used, this method will open a new tab using your Chrome browser. When not using a Chrome browser, set options(browser=) to change the default behavior of browseURL().

Examples

# Create a new `ChromoteSession` object.
b <- ChromoteSession$new()

# Navigate to page
b$Page$navigate("http://www.r-project.org/")

# View current chromote session
if (interactive()) b$view()

Usage

ChromoteSession$view()

Method `close()`

Close the Chromote session.

Examples

# Create a new `ChromoteSession` object.
b <- ChromoteSession$new()

# Navigate to page
b$Page$navigate("http://www.r-project.org/")

# Close current chromote session
b$close()

Usage

ChromoteSession$close(wait_ = TRUE)

Arguments

wait_: If FALSE, return a promises::promise() that will resolve when the ChromoteSession is closed. Otherwise, block until the ChromoteSession has closed.

Method `screenshot()`

Take a PNG screenshot

Examples

# Create a new `ChromoteSession` object.
b <- ChromoteSession$new()

# Navigate to page
b$Page$navigate("http://www.r-project.org/")

# Take screenshot
tmppngfile <- tempfile(fileext = ".png")
is_interactive <- interactive() # Display screenshot if interactive
b$screenshot(tmppngfile, show = is_interactive)

# Show screenshot file info
unlist(file.info(tmppngfile))


# Take screenshot using a selector
sidebar_file <- tempfile(fileext = ".png")
b$screenshot(sidebar_file, selector = ".sidebar", show = is_interactive)

# ----------------------------
# Take screenshots in parallel

urls <- c(
  "https://www.r-project.org/",
  "https://github.com/",
  "https://news.ycombinator.com/"
)
# Helper method that:
# 1. Navigates to the given URL
# 2. Waits for the page loaded event to fire
# 3. Takes a screenshot
# 4. Prints a message
# 5. Close the ChromoteSession
screenshot_p <- function(url, filename = NULL) {
  if (is.null(filename)) {
    filename <- gsub("^.*://", "", url)
    filename <- gsub("/", "_", filename)
    filename <- gsub("\\.", "_", filename)
    filename <- sub("_$", "", filename)
    filename <- paste0(filename, ".png")
  }

  b2 <- b$new_session()
  b2$Page$navigate(url, wait_ = FALSE)
  b2$Page$loadEventFired(wait_ = FALSE)$
    then(function(value) {
      b2$screenshot(filename, wait_ = FALSE)
    })$
    then(function(value) {
      message(filename)
    })$
    finally(function() {
      b2$close()
    })
}

# Take multiple screenshots simultaneously
ps <- lapply(urls, screenshot_p)
pa <- promises::promise_all(.list = ps)$then(function(value) {
  message("Done!")
})

# Block the console until the screenshots finish (optional)
b$wait_for(pa)
#> www_r-project_org.png
#> github_com.png
#> news_ycombinator_com.png
#> Done!

Usage

ChromoteSession$screenshot(
  filename = "screenshot.png",
  selector = "html",
  cliprect = NULL,
  region = c("content", "padding", "border", "margin"),
  expand = NULL,
  scale = 1,
  show = FALSE,
  delay = 0.5,
  options = list(),
  wait_ = TRUE
)

Arguments

filename: File path of where to save the screenshot. The format of the screenshot is inferred from the file extension; use options = list(format = "jpeg") to manually choose the format. See Page.captureScreenshot for supported formats; at the time of this release the format options were "png" (default), "jpeg", or "webp".
selector: CSS selector to use for the screenshot.
cliprect: An unnamed vector or list containing values for top, left, width, and height, in that order. See Page.Viewport for more information. If provided, selector and expand will be ignored. To provide a scale, use the scale parameter.
region: CSS region to use for the screenshot.
expand: Extra pixels to expand the screenshot. May be a single value or a numeric vector of top, right, bottom, left values.
scale: Page scale factor
show: If TRUE, the screenshot will be displayed in the viewer.
delay: The number of seconds to wait before taking the screenshot after resizing the page. For complicated pages, this may need to be increased.
options: Additional options passed to Page.captureScreenshot.
wait_: If FALSE, return a promises::promise() that will resolve when the ChromoteSession has saved the screenshot. Otherwise, block until the ChromoteSession has saved the screenshot.

Method `screenshot_pdf()`

Take a PDF screenshot

Examples

# Create a new `ChromoteSession` object.
b <- ChromoteSession$new()

# Navigate to page
b$Page$navigate("http://www.r-project.org/")

# Take screenshot
tmppdffile <- tempfile(fileext = ".pdf")
b$screenshot_pdf(tmppdffile)

# Show PDF file info
unlist(file.info(tmppdffile))

Usage

ChromoteSession$screenshot_pdf(
  filename = "screenshot.pdf",
  pagesize = "letter",
  margins = 0.5,
  units = c("in", "cm"),
  landscape = FALSE,
  display_header_footer = FALSE,
  print_background = FALSE,
  scale = 1,
  wait_ = TRUE
)

Arguments

filename: File path of where to save the screenshot.
pagesize: A single character value in the set "letter", "legal", "tabloid", "ledger" and "a0" through "a1". Or a numeric vector c(width, height) specifying the page size.
margins: A numeric vector c(top, right, bottom, left) specifying the page margins.
units: Page and margin size units. Either "in" or "cm" for inches and centimeters respectively.
landscape: Paper orientation.
display_header_footer: Display header and footer.
print_background: Print background graphics.
scale: Page scale factor.
wait_: If FALSE, return a promises::promise() that will resolve when the ChromoteSession has saved the screenshot. Otherwise, block until the ChromoteSession has saved the screnshot.

Method `new_session()`

Create a new tab / window

Examples

b1 <- ChromoteSession$new()
b1$Page$navigate("http://www.google.com")
b2 <- b1$new_session()
b2$Page$navigate("http://www.r-project.org/")
b1$Runtime$evaluate("window.location", returnByValue = TRUE)$result$value$href
#> [1] "https://www.google.com/"
b2$Runtime$evaluate("window.location", returnByValue = TRUE)$result$value$href
#> [1] "https://www.r-project.org/"

Usage

ChromoteSession$new_session(
  width = 992,
  height = 1323,
  targetId = NULL,
  wait_ = TRUE
)

Arguments

width, height: Width and height of the new window.
targetId: Target ID of an existing target to attach to. When a targetId is provided, the width and height arguments are ignored. If NULL (the default) a new target is created and attached to, and the width and height arguments determine its viewport size.
wait_: If FALSE, return a promises::promise() that will resolve when the ChromoteSession has created a new session. Otherwise, block until the ChromoteSession has created a new session.

Method `get_session_id()`

Retrieve the session id

Usage

ChromoteSession$get_session_id()

Method `respawn()`

Create a new session that connects to the same target (i.e. page) as this session. This is useful if the session has been closed but the target still exists.

Usage

ChromoteSession$respawn()

Method `get_target_id()`

Retrieve the target id

Usage

ChromoteSession$get_target_id()

Method `wait_for()`

Wait for a Chromote Session to finish. This method will block the R session until the provided promise resolves. The loop from $get_child_loop() will only advance just far enough for the promise to resolve.

Examples

b <- ChromoteSession$new()

# Async with promise
p <- b$Browser$getVersion(wait_ = FALSE)
p$then(str)

# Async with callback
b$Browser$getVersion(wait_ = FALSE, callback_ = str)

Usage

ChromoteSession$wait_for(p)

Arguments

p: A promise to resolve.

Method `debug_log()`

Send a debug log message to the parent Chromote object

Examples

b <- ChromoteSession$new()
b$parent$debug_messages(TRUE)
b$Page$navigate("https://www.r-project.org/")
#> SEND {"method":"Page.navigate","params":{"url":"https://www.r-project.org/"}| __truncated__}
# Turn off debug messages
b$parent$debug_messages(FALSE)

Usage

ChromoteSession$debug_log(...)

Arguments

...: Arguments pasted together with paste0(..., collapse = "").

Method `get_child_loop()`

later loop.

For expert async usage only.

Usage

ChromoteSession$get_child_loop()

Method `send_command()`

Send command through Chrome DevTools Protocol.

For expert use only.

Usage

ChromoteSession$send_command(
  msg,
  callback = NULL,
  error = NULL,
  timeout = NULL
)

Arguments

msg: A JSON-serializable list containing method, and params.
callback: Method to run when the command finishes successfully.
error: Method to run if an error occurs.
timeout: Number of milliseconds for Chrome DevTools Protocol execute a method.

Method `get_auto_events()`

Resolved auto_events value.

For internal use only.

Usage

ChromoteSession$get_auto_events()

Method `invoke_event_callbacks()`

Immediately call all event callback methods.

For internal use only.

Usage

ChromoteSession$invoke_event_callbacks(event, params)

Arguments

event: A single event string
params: A list of parameters to pass to the event callback methods.

Method `mark_closed()`

Mark a session, and optionally, the underlying target, as closed. For internal use only.

Usage

ChromoteSession$mark_closed(target_closed)

Arguments

target_closed: Has the underlying target been closed as well as the active debugging session?

Method `is_active()`

Retrieve active status Once initialized, the value returned is TRUE. If $close() has been called, this value will be FALSE.

Usage

ChromoteSession$is_active()

Method `check_active()`

Check that a session is active, erroring if not.

Usage

ChromoteSession$check_active()

Method `get_init_promise()`

Initial promise

For internal use only.

Usage

ChromoteSession$get_init_promise()

Method `print()`

Summarise the current state of the object.

Usage

ChromoteSession$print(..., verbose = FALSE)

Arguments

...: Passed on to format() when verbose = TRUE
verbose: The print method defaults to a brief summary of the most important debugging info; use verbose = TRUE tp see the complex R6 object.

Public fields

Methods

Public methods

Method new()

Examples

Usage

Arguments

Returns

Method view()

Examples

Usage

Method close()

Examples

Usage

Arguments

Method screenshot()

Examples

Usage

Arguments

Method screenshot_pdf()

Examples

Usage

Arguments

Method new_session()

Examples

Usage

Arguments

Method get_session_id()

Usage

Method respawn()

Usage

Method get_target_id()

Usage

Method wait_for()

Examples

Usage

Arguments

Method debug_log()

Examples

Usage

Arguments

Method get_child_loop()

Usage

Method send_command()

Usage

Arguments

Method get_auto_events()

Usage

Method invoke_event_callbacks()

Usage

Arguments

Method mark_closed()

Usage

Arguments

Method is_active()

Usage

Method check_active()

Usage

Method get_init_promise()

Usage

Method print()

Usage

Arguments

Method `new()`

Method `view()`

Method `close()`

Method `screenshot()`

Method `screenshot_pdf()`

Method `new_session()`

Method `get_session_id()`

Method `respawn()`

Method `get_target_id()`

Method `wait_for()`

Method `debug_log()`

Method `get_child_loop()`

Method `send_command()`

Method `get_auto_events()`

Method `invoke_event_callbacks()`

Method `mark_closed()`

Method `is_active()`

Method `check_active()`

Method `get_init_promise()`

Method `print()`