Package 'paparazzi'

Description

The contract shared by the ⁠pz_act_*()⁠ functions.

Acting on the page

The ⁠pz_act_*()⁠ functions use the page the way a person would. They send real browser input, such as pointer moves, clicks and key presses, or use the browser's own focus and text-selection methods. They never set a form value directly.

An action with a target looks for it in the current scope and waits until it matches an element. Inside a scope, target = NULL acts on the scope's element, and scrolling with by or to scrolls the scope's container. An explicit target is scrolled into view first when needed. A few actions, like pz_act_press(), take no target and act on the focused element instead.

While the page is recording, actions are staged as pz_stage() sets them up: the cursor glides to pointer targets, typing is paced, scrolls normally use the mouse wheel, and the page holds for the staged pause afterward. Without a recording, actions go straight to their final state.

To set a value directly instead, without staging, use pz_set_value(), pz_set_files(), or pz_set_shiny_input().

Description

Removes focus from the current scope's element, or at the root context from whatever element currently has focus (⁠document .activeElement⁠). A no-op when the body is focused. Useful to clear focus rings before a screenshot.

Usage

pz_act_blur(ctx, ...)

Arguments

Value

ctx, invisibly.

Acting on the page

The ⁠pz_act_*()⁠ functions use the page the way a person would. They send real browser input, such as pointer moves, clicks and key presses, or use the browser's own focus and text-selection methods. They never set a form value directly.

An action with a target looks for it in the current scope and waits until it matches an element. Inside a scope, target = NULL acts on the scope's element, and scrolling with by or to scrolls the scope's container. An explicit target is scrolled into view first when needed. A few actions, like pz_act_press(), take no target and act on the focused element instead.

While the page is recording, actions are staged as pz_stage() sets them up: the cursor glides to pointer targets, typing is paced, scrolls normally use the mouse wheel, and the page holds for the staged pause afterward. Without a recording, actions go straight to their final state.

To set a value directly instead, without staging, use pz_set_value(), pz_set_files(), or pz_set_shiny_input().

See Also

pz_act_focus()

Examples

page <- pz_open(pz_example("tasks"))
page |> pz_act_focus("#task-title")

# Remove the focus ring, e.g. before a screenshot
page |> pz_act_blur()
pz_expect_focused(page, target = "#task-title", not = TRUE)
pz_close(page)

Description

Auto-waits for the element to be actionable – visible with a non-empty box, the same "visible" pz_expect_visible() uses, and receiving pointer events at its center (not covered by another element) – then scrolls it into view and clicks the center of it with real browser input events: a mouse move to the point, then a left-button press and release. The page sees a trusted pointer sequence – exactly what a user's click produces – so ⁠:hover⁠ state, focus, and click handlers all behave as they would live. While recording, the staging settings (pz_stage()) animate the scroll, the cursor glide, and the press; otherwise everything runs straight to the final state.

Usage

pz_act_click(ctx, target = NULL, ..., effect = NULL, effect_color = NULL)

Arguments

Value

ctx, invisibly.

Acting on the page

The ⁠pz_act_*()⁠ functions use the page the way a person would. They send real browser input, such as pointer moves, clicks and key presses, or use the browser's own focus and text-selection methods. They never set a form value directly.

An action with a target looks for it in the current scope and waits until it matches an element. Inside a scope, target = NULL acts on the scope's element, and scrolling with by or to scrolls the scope's container. An explicit target is scrolled into view first when needed. A few actions, like pz_act_press(), take no target and act on the focused element instead.

While the page is recording, actions are staged as pz_stage() sets them up: the cursor glides to pointer targets, typing is paced, scrolls normally use the mouse wheel, and the page holds for the staged pause afterward. Without a recording, actions go straight to their final state.

To set a value directly instead, without staging, use pz_set_value(), pz_set_files(), or pz_set_shiny_input().

See Also

pz_act_hover(), pz_act_type(), pz_act_press()

Examples

page <- pz_open(pz_example("tasks"))
page |> pz_act_click("#toggle-help")
pz_get_text(page, target = "#toggle-help")

# In a scoped context, target = NULL clicks the scope element
page |>
  pz_find(pz_loc(".task-done", within = pz_loc(".task", has_text = "bank"))) |>
  pz_act_click()
pz_get_count(page, target = ".task.done")
pz_close(page)

Description

Auto-waits for the source to be actionable: visible, non-empty, and receiving pointer events at its center (not covered by another element). With to, the destination is checked for visibility and that it receives the drop at its center after the source is brought into view. It then drags with real mouse input: press at the source's center, move to the destination, release. When the source is a real HTML5 drag source (draggable, including inherited draggable or the image/⁠<a href>⁠ defaults), the drag runs through the browser's drag pipeline instead: the press and move start a genuine dragstart (so dataTransfer holds whatever the page put there), and the drop is delivered to the destination as trusted dragenter/dragover/drop events with that payload.

While recording, the staging (pz_stage()) shows the press at the source and glides the cursor while holding from the source to the destination, streaming the path's real input events (held moves, or dragenter/dragover on the HTML5 path) along the glide, so pointer-following content tracks the cursor and intermediate elements see the drag pass. The drop lands as the cursor arrives. On the HTML5 path the carry runs between the page's dragstart and the replayed drop, so dragstart styling stays visible through the carry, and the real pointer stays by the source until the release, so the destination shows no hover during the carry.

to names the element to drop onto; by = c(x, y) drops at that offset in pixels from the source's center. Supply exactly one.

Usage

pz_act_drag(ctx, target, to = NULL, ..., by = NULL, preview = TRUE)

Arguments

Value

ctx, invisibly.

Drag preview

With preview = TRUE, paparazzi carries a static image of the HTML5 drag source during an active, unpaused recording with a visible cursor. Paparazzi captures the image before dragstart styling; a handle inside a draggable element previews that element. After the drop, the image briefly settles to the same source node's new bounds if it survives with a supported, unchanged size. Paparazzi never hides or replaces the page's source. The preview is not the browser's native drag image and does not reproduce custom DataTransfer.setDragImage() feedback.

Paparazzi disables the optional preview with a warning in these cases. The drag continues without the preview.

• Unreadable stylesheets, often on ⁠file://⁠ pages: open the page over HTTP. pz_open() serves local .html paths over HTTP when httpuv is installed and loads. You can also serve the page with pz_serve_static() and open the server handle with pz_open(). Cross-origin stylesheets must also allow the browser to read their rules.

• Iframes or SVG ⁠<use>⁠ references in the source: use a source without these references; they can copy content outside the source subtree.

• Unsupported CSS rule groups, imported stylesheets, or font sources: move rules out of unsupported groups or imports and embed font sources as data URLs in ⁠@font-face⁠ rules. Registered fonts also need a readable embedded CSS representation.

• Source-related or overlapping paparazzi redactions, or uncertain redaction state: keep redactions separate from the source or turn off the preview. Paparazzi permits capture only when it can verify that redactions are separate; do not remove redactions from sensitive content for a preview.

• Unsupported source geometry or content: use a source without transforms, filters, clipping, overflowing content, shadow DOM, or generated content. Fixed or sticky descendants and out-of-box positioned content are also unsupported.

Other preview failures report the underlying error message. Use preview = FALSE to turn off capture, carry imagery, and settling. Unrecorded, paused, hidden-cursor, and ordinary mouse drags do no preview work.

Acting on the page

The ⁠pz_act_*()⁠ functions use the page the way a person would. They send real browser input, such as pointer moves, clicks and key presses, or use the browser's own focus and text-selection methods. They never set a form value directly.

An action with a target looks for it in the current scope and waits until it matches an element. Inside a scope, target = NULL acts on the scope's element, and scrolling with by or to scrolls the scope's container. An explicit target is scrolled into view first when needed. A few actions, like pz_act_press(), take no target and act on the focused element instead.

While the page is recording, actions are staged as pz_stage() sets them up: the cursor glides to pointer targets, typing is paced, scrolls normally use the mouse wheel, and the page holds for the staged pause afterward. Without a recording, actions go straight to their final state.

To set a value directly instead, without staging, use pz_set_value(), pz_set_files(), or pz_set_shiny_input().

See Also

pz_act_click(), pz_act_hover()

Examples

page <- pz_open(pz_example("tasks"))
pz_get_text(page, target = ".task-title")

# The tasks are HTML5 drag sources; drop "Water the plants" on the first task
page |>
  pz_act_drag(
    pz_loc(".task", has_text = "plants"),
    to = pz_loc(".task", which = "first")
  )
pz_get_text(page, target = ".task-title")
pz_close(page)

Description

Scrolls the element into view (instantly) and focuses it via the browser's element focus method, so the page shows focus rings and enabled-input styles exactly as a user would see them. Focus is an element-state change, not an input event, so the direct method call is the faithful implementation (Playwright does the same).

Usage

pz_act_focus(ctx, target = NULL, ...)

Arguments

Value

ctx, invisibly.

Acting on the page

The ⁠pz_act_*()⁠ functions use the page the way a person would. They send real browser input, such as pointer moves, clicks and key presses, or use the browser's own focus and text-selection methods. They never set a form value directly.

An action with a target looks for it in the current scope and waits until it matches an element. Inside a scope, target = NULL acts on the scope's element, and scrolling with by or to scrolls the scope's container. An explicit target is scrolled into view first when needed. A few actions, like pz_act_press(), take no target and act on the focused element instead.

While the page is recording, actions are staged as pz_stage() sets them up: the cursor glides to pointer targets, typing is paced, scrolls normally use the mouse wheel, and the page holds for the staged pause afterward. Without a recording, actions go straight to their final state.

To set a value directly instead, without staging, use pz_set_value(), pz_set_files(), or pz_set_shiny_input().

See Also

pz_act_blur(), pz_act_type()

Examples

page <- pz_open(pz_example("tasks"))
page |> pz_act_focus("#task-title")
pz_expect_focused(page, target = "#task-title")
pz_close(page)

Description

Auto-waits for the element to be actionable – visible with a non-empty box and receiving pointer events at its center (not covered by another element) – then scrolls it into view and moves the pointer to the center of it with a real mousemove event, without pressing any button. This is what drives ⁠:hover⁠ styles and mouseenter/mouseover handlers.

Usage

pz_act_hover(ctx, target = NULL, ...)

Arguments

Value

ctx, invisibly.

Acting on the page

The ⁠pz_act_*()⁠ functions use the page the way a person would. They send real browser input, such as pointer moves, clicks and key presses, or use the browser's own focus and text-selection methods. They never set a form value directly.

An action with a target looks for it in the current scope and waits until it matches an element. Inside a scope, target = NULL acts on the scope's element, and scrolling with by or to scrolls the scope's container. An explicit target is scrolled into view first when needed. A few actions, like pz_act_press(), take no target and act on the focused element instead.

While the page is recording, actions are staged as pz_stage() sets them up: the cursor glides to pointer targets, typing is paced, scrolls normally use the mouse wheel, and the page holds for the staged pause afterward. Without a recording, actions go straight to their final state.

To set a value directly instead, without staging, use pz_set_value(), pz_set_files(), or pz_set_shiny_input().

See Also

pz_act_click()

Examples

page <- pz_open(pz_example("tasks"))
passport <- pz_loc(".task", has_text = "passport")

# Tasks change colour on :hover
pz_get_style(page, "background-color", target = passport)
page |> pz_act_hover(passport)
pz_get_style(page, "background-color", target = passport)
pz_close(page)

Description

Presses one or more key combinations against whatever the page currently has focused, e.g. "Enter", "Control+A", c("Shift+Tab", "Escape"). A vector presses each combination fully (down then up) in order. Specs are "Mod+Mod+Key" strings with the modifiers Control, Shift, Alt, Meta, and Mod (matched case-insensitively) and a named key (Enter, Tab, Escape, Backspace, arrows, F1-F12, ...) or a single printable character. Mod resolves to Meta on browsers reporting a Mac platform (navigator.userAgentData.platform or navigator.platform), and Control otherwise. Following Playwright, an uppercase letter or shifted symbol implies Shift: "Control+A" sends Control+Shift+A.

Keys only reach focused elements; call pz_act_click() or pz_act_focus() first to focus the element you're typing into.

Usage

pz_act_press(ctx, key, ..., show_keys = NULL)

Arguments

Value

ctx, invisibly.

Acting on the page

The ⁠pz_act_*()⁠ functions use the page the way a person would. They send real browser input, such as pointer moves, clicks and key presses, or use the browser's own focus and text-selection methods. They never set a form value directly.

An action with a target looks for it in the current scope and waits until it matches an element. Inside a scope, target = NULL acts on the scope's element, and scrolling with by or to scrolls the scope's container. An explicit target is scrolled into view first when needed. A few actions, like pz_act_press(), take no target and act on the focused element instead.

While the page is recording, actions are staged as pz_stage() sets them up: the cursor glides to pointer targets, typing is paced, scrolls normally use the mouse wheel, and the page holds for the staged pause afterward. Without a recording, actions go straight to their final state.

To set a value directly instead, without staging, use pz_set_value(), pz_set_files(), or pz_set_shiny_input().

See Also

pz_act_type() to insert text.

Examples

page <- pz_open(pz_example("tasks"))
page |>
  pz_act_type("Buy milkk", target = "#task-title") |>
  pz_act_press("Backspace")
pz_get_value(page, target = "#task-title")

# Enter submits the form; the page shows "Saving..." before the task appears
page |> pz_act_press("Enter")
pz_expect_text(page, "Saved", target = "#status")
pz_get_text(page, target = pz_loc(".task-title", which = "first"))

# A vector presses keys in sequence; + joins keys pressed together
page |> pz_act_press(c("Tab", "Shift+Tab"))
pz_expect_focused(page, target = "#task-title")
pz_close(page)

Description

Exactly one of target, by, and to:

• target: auto-waits for a match, then scrolls it into view (instantly outside a recording).

• by = c(x, y): scrolls the current scope's scroll container – the scope element or its nearest scrollable ancestor, or the page itself at the root context – by that many pixels.

• to: scrolls that same container to an edge or corner from the direction vocabulary: "top", "bottom", "left", "right", the four corners, or "center" (e.g. "bottom" scrolls to the end; "top right" to the top-right corner).

Scrolling is instant outside a recording; while recording it is staged as real mouse wheel events with the cursor over the container, so the video shows the scroll. Wheel scrolling is best-effort: if the page swallows the events, the instant scroll still guarantees the final position.

Usage

pz_act_scroll(ctx, target = NULL, ..., by = NULL, to = NULL, duration = NULL)

Arguments

Value

ctx, invisibly.

Acting on the page

The ⁠pz_act_*()⁠ functions use the page the way a person would. They send real browser input, such as pointer moves, clicks and key presses, or use the browser's own focus and text-selection methods. They never set a form value directly.

An action with a target looks for it in the current scope and waits until it matches an element. Inside a scope, target = NULL acts on the scope's element, and scrolling with by or to scrolls the scope's container. An explicit target is scrolled into view first when needed. A few actions, like pz_act_press(), take no target and act on the focused element instead.

While the page is recording, actions are staged as pz_stage() sets them up: the cursor glides to pointer targets, typing is paced, scrolls normally use the mouse wheel, and the page holds for the staged pause afterward. Without a recording, actions go straight to their final state.

To set a value directly instead, without staging, use pz_set_value(), pz_set_files(), or pz_set_shiny_input().

See Also

pz_find(), pz_act_click()

Examples

page <- pz_open(pz_example("tasks"), height = 600)

# With a target, scroll it into view
page |> pz_act_scroll("#toggle-help")
pz_expect_in_viewport(page, target = "#toggle-help")

# With `to` or `by`, scroll the current scope's container: here the list
page |>
  pz_find(".task-list") |>
  pz_act_scroll(to = "bottom")
pz_expect_in_viewport(page, target = pz_loc(".task", which = "last"))

# At the root, the container is the page itself
page |> pz_act_scroll(to = "top")
pz_evaluate(page, "window.scrollY")
pz_close(page)

Description

Auto-waits for a match, then highlights the exact text inside it. paparazzi finds the substring among the element's text nodes and sets the page's real window selection, even when the match spans inline tags such as ⁠<em>⁠ and ⁠<strong>⁠. Typing afterwards replaces it – call pz_act_type() with target = NULL, which inserts into whatever has focus.

Usage

pz_act_select_text(ctx, text, ..., target = NULL)

Arguments

Details

While recording with a visible cursor, paparazzi animates a drag across the text, then sets the exact selection with the browser's Range API. The drag sends real mouse-move events, which can trigger page hover effects such as tooltips or hover menus. Outside a recording, selection is instant and leaves the cursor where it was, without sending mouse-move events.

A contenteditable target is focused too (dragging across editable text focuses it, and that focus is where the typing lands); a static target is not.

Value

ctx, invisibly.

Acting on the page

The ⁠pz_act_*()⁠ functions use the page the way a person would. They send real browser input, such as pointer moves, clicks and key presses, or use the browser's own focus and text-selection methods. They never set a form value directly.

An action with a target looks for it in the current scope and waits until it matches an element. Inside a scope, target = NULL acts on the scope's element, and scrolling with by or to scrolls the scope's container. An explicit target is scrolled into view first when needed. A few actions, like pz_act_press(), take no target and act on the focused element instead.

While the page is recording, actions are staged as pz_stage() sets them up: the cursor glides to pointer targets, typing is paced, scrolls normally use the mouse wheel, and the page holds for the staged pause afterward. Without a recording, actions go straight to their final state.

To set a value directly instead, without staging, use pz_set_value(), pz_set_files(), or pz_set_shiny_input().

See Also

pz_act_type(), pz_set_value()

Examples

page <- pz_open(pz_example("tasks"))

# Typing replaces the selection
page |>
  pz_find(pz_loc(".task", has_text = "Renew passport")) |>
  pz_act_click(".task-edit") |>
  pz_find(".task-title") |>
  pz_act_select_text("passport") |>
  pz_act_type("driving licence") |>
  pz_act_press("Enter") |>
  pz_get_text()
pz_close(page)

Description

With a target, auto-waits for the element to be actionable – visible with a non-empty box and receiving pointer events at its center (not covered by another element) – then scrolls it into view, clicks the center of it (real mouse events, so the element genuinely gains focus), and inserts text at the caret – the caret lands where the click lands, just like a real user. With target = NULL at the root context, inserts into whatever element currently has focus; if nothing editable is focused, the text goes nowhere, exactly like typing into a page with no focused field.

Insertion is instant (one insertText), except while recording with typing = "natural" (the default; see pz_stage()): one insertText per character with randomized delays around typing_speed, so the video shows the text appearing. While recording, paparazzi fades the cursor out during typing so it doesn't cover the text. The next pointer action fades it back in. For a value-setting primitive that works on selects, checkboxes, and range inputs, see pz_set_value().

Usage

pz_act_type(ctx, text, ..., target = NULL)

Arguments

Value

ctx, invisibly.

Acting on the page

The ⁠pz_act_*()⁠ functions use the page the way a person would. They send real browser input, such as pointer moves, clicks and key presses, or use the browser's own focus and text-selection methods. They never set a form value directly.

An action with a target looks for it in the current scope and waits until it matches an element. Inside a scope, target = NULL acts on the scope's element, and scrolling with by or to scrolls the scope's container. An explicit target is scrolled into view first when needed. A few actions, like pz_act_press(), take no target and act on the focused element instead.

While the page is recording, actions are staged as pz_stage() sets them up: the cursor glides to pointer targets, typing is paced, scrolls normally use the mouse wheel, and the page holds for the staged pause afterward. Without a recording, actions go straight to their final state.

To set a value directly instead, without staging, use pz_set_value(), pz_set_files(), or pz_set_shiny_input().

See Also

pz_act_press() for key combos (Enter, Control+A, ...) and pz_act_click().

Examples

page <- pz_open(pz_example("tasks"))
page |> pz_act_type("Buy milk", target = "#task-title")
pz_get_value(page, target = "#task-title")

# Typing fires input events, so the page reacts: Add is now enabled
pz_expect_enabled(page, target = "#add-task")

# At the root, target = NULL types into the focused element
page |> pz_act_type(" and eggs")
pz_get_value(page, target = "#task-title")
pz_close(page)

Description

Draws an annotation for each element matched by target. Annotations follow their elements as the page scrolls or changes layout, and appear in screenshots and recordings until cleared with pz_annotate_clear(). Annotations belong to the current document; navigating away removes them. Marks respect the target's overflow containers (axis-aligned clipping only, not a custom overflow-clip-margin). Badges prefer a position above the visible mark's top-left corner, outside those clips. For targets inside the viewport, paparazzi shifts settled badges just enough to fit, overlapping the target if needed at the top edge. Badges larger than the viewport align with its top or left edge and may still be clipped; paparazzi does not resize them. Off-viewport targets keep their badges attached, and a screenshot's frame crop can still exclude a badge. Badges size to their labels, wrapping long labels at 20em rather than at the target's width. On sides where the target is not cut off, the clip leaves room for the mark's pad so its outline stays intact. A mark and its badge hide while the target is disconnected, not rendered, visibility: hidden with no visible descendants, or entirely clipped, even if its padding would reach into view. Zero-size targets on a clipping edge also stay hidden.

Usage

pz_annotate(
  ctx,
  target = NULL,
  ...,
  type = "box",
  label = NULL,
  pad = 0,
  reveal = c("auto", "fade", "draw", "pop", "slide", "wipe", "none"),
  id = NULL,
  color = NULL,
  label_fill = NULL,
  label_text_color = NULL,
  stroke_width = NULL,
  font_family = NULL,
  font_size = NULL
)

Arguments

Value

ctx, invisibly.

See Also

pz_annotate_clear(), pz_stage_annotate()

Description

Draws one callout per matching element, repeating text for every match. Callouts follow their targets during scrolling and layout changes, and appear in screenshots and recordings until cleared with pz_annotate_clear(). They belong to the current document and disappear on navigation. A bubble is kept within the viewport even if this moves it away from the requested side; text that cannot fit a tiny viewport is clipped. A viewport resize does not rewrap an existing callout. A callout hides while its target isn't rendered, is visibility: hidden with no visible descendants, or is entirely clipped by an overflow container. When the target is partly clipped, the leader points at its visible part; the bubble itself is never clipped.

Usage

pz_annotate_callout(
  ctx,
  text,
  ...,
  target = NULL,
  side = NULL,
  leader = TRUE,
  label = NULL,
  reveal = c("pop", "fade", "draw", "slide", "wipe", "none"),
  id = NULL,
  color = NULL,
  fill = NULL,
  text_color = NULL,
  stroke_width = NULL,
  distance = NULL,
  font_family = NULL,
  font_size = NULL
)

Arguments

Value

ctx, invisibly.

See Also

pz_annotate(), pz_annotate_clear()

Description

A caption stays on the page until replaced or cleared with pz_annotate_clear(id = "caption"). It persists through navigation and across recordings, and appears on stills. In a recording, a caption fades out when it is cleared or replaced; one that is still showing at pz_record_stop() stays on through the last frame.

Usage

pz_annotate_caption(
  ctx,
  text,
  ...,
  side = NULL,
  color = "white",
  font_family = NULL,
  font_size = 20
)

Arguments

Value

ctx, invisibly.

See Also

pz_annotate_clear(), pz_record_start(), pz_screenshot()

Description

Remove an annotation by id, or remove every annotation when id is NULL. During an active recording, marks play their reveal in reverse before removal; paused recordings and stills clear instantly.

Usage

pz_annotate_clear(ctx, id = NULL, ...)

Arguments

Value

ctx, invisibly.

Description

Covers every element matched by target with an instant opaque fill or backdrop blur in screenshots and recordings. Fill is the safe choice for secrets: blur can leave text partly legible. Redactions follow elements as they move and respect axis-aligned overflow clipping, except custom overflow-clip-margin. If a target disconnects, stops rendering, or is entirely clipped, its redaction hides until it becomes visible again. They belong to the current document and are lost on navigation. Redaction covers each element's border box plus pad, not overflowing descendants; target the overflowing element or add padding. Later top-layer UI (modal dialogs and popovers) paints above redactions, so targets inside an open modal or popover are rejected.

Usage

pz_annotate_redact(
  ctx,
  target = NULL,
  ...,
  method = c("fill", "blur"),
  pad = 0,
  id = NULL,
  color = NULL
)

Arguments

Value

ctx, invisibly.

See Also

pz_annotate(), pz_annotate_clear()

Description

Dims the page except for a rounded cutout around each matched element. The scrim covers the document, including below-fold areas captured in screenshots. The spotlight follows its elements through scrolling and layout changes. Disconnected or zero-size elements lose their cutouts, and so do visibility: hidden elements with no visible descendants. Cutouts are clipped by the target's overflow containers (axis-aligned clipping only, not a custom overflow-clip-margin), so a target scrolled out of a scrolling container gets no cutout. It appears in screenshots and recordings until cleared, and is lost on navigation. Only one spotlight exists per page: a new call replaces the previous one, and pz_annotate_clear() removes it by the reserved id "spotlight" or with a clear-all call. The cutout covers each target's padded border box; overflowing descendants and top-layer dialogs/popovers are not covered.

Usage

pz_annotate_spotlight(
  ctx,
  target = NULL,
  ...,
  pad = 0,
  dim = 0.6,
  reveal = c("fade", "none")
)

Arguments

Value

ctx, invisibly.

See Also

pz_annotate(), pz_annotate_clear()

Description

Moves an encode-time camera over a recording. The shot comes from frame: a pz_frame() spec, or a bare locator (a CSS selector string, a pz_loc() spec, or a list of either) promoted to one, whose union is the shot. In a scoped context frame may be omitted or NULL to shoot the scope's box; at the root it is required (pz_camera_reset() returns to the home view). frame = FALSE shoots the scope's box, or the viewport at the root, unframed. The camera does not change the live page or still screenshots. Outside a recording it does nothing, and each pz_record_start() begins at the recording frame.

Usage

pz_camera(ctx, frame, ..., duration = NULL, wait = FALSE)

Arguments

Value

ctx, invisibly.

Description

Returns the camera to the recording frame (or the full viewport). Outside a recording it does nothing.

Usage

pz_camera_reset(ctx, ..., wait = FALSE)

Arguments

Value

ctx, invisibly.

Description

Escape hatch for raw Chrome DevTools Protocol calls.

Usage

pz_chromote(ctx)

Arguments

Value

The chromote::ChromoteSession backing the page.

Examples

page <- pz_open(pz_example("tasks"))
session <- pz_chromote(page)

# Make raw Chrome DevTools Protocol calls
session$Browser$getVersion()$product
session$Performance$enable()
metrics <- session$Performance$getMetrics()$metrics
Filter(function(m) m$name == "Nodes", metrics)[[1]]$value
pz_close(page)

Description

Closes the page's browser session and any server it started. A page opened from a shared serving handle leaves the server running. Closing an already-closed page is a no-op.

Usage

pz_close(page)

Arguments

Value

The page, invisibly.

Examples

page <- pz_open(pz_example("tasks"))
pz_close(page)

# Closing a closed page does nothing
pz_close(page)

Description

Hides the cursor set up by pz_cursor_show() or shown implicitly while recording. The cursor keeps its last position; showing it again returns it there. The hide is explicit and sticky: the cursor stays hidden until pz_cursor_show() or pz_cursor_move() shows it again – neither a recorded pointer action nor the cursor staging setting brings it back. That is what distinguishes pz_cursor_hide() from pz_cursor_leave(), which keeps the cursor visible and glides back in on the next action.

Usage

pz_cursor_hide(ctx, ...)

Arguments

Value

ctx, invisibly.

See Also

pz_cursor_show(), pz_cursor_leave()

Examples

page <- pz_open(pz_example("tasks"))
page |>
  pz_cursor_show("#add-task") |>
  pz_cursor_hide() |>
  pz_screenshot(file.path(tempdir(), "no-cursor.png"))
pz_screenshot(page, frame = pz_frame("#new-task", pad = 24))
pz_close(page)

Description

Sends the cursor out of the frame through side: while recording it glides out, otherwise it leaves immediately. The cursor is still visible (just off-frame); the next pointer action or cursor call glides it back in from that side.

Usage

pz_cursor_leave(ctx, side = "right", icon = NULL)

Arguments

Value

ctx, invisibly.

See Also

pz_cursor_show()

Examples

page <- pz_open(pz_example("tasks"))
path <- file.path(tempdir(), "help.mp4")
page |>
  pz_record(path, {
    page |>
      pz_act_click("#toggle-help") |>
      # Move the cursor out of the way so the help text is unobstructed
      pz_cursor_leave("right", icon = "default") |>
      pz_record_hold(1)
  })
pz_close(page)

Description

Moves the cursor over target, showing it first if hidden. While recording the move is a glide whose duration scales with distance (see pz_stage()); pass duration to override it. Without a recording the cursor jumps.

Usage

pz_cursor_move(
  ctx,
  target,
  ...,
  duration = NULL,
  icon = NULL,
  offset = c(0, 0)
)

Arguments

Value

ctx, invisibly.

See Also

pz_cursor_show(), pz_cursor_leave()

Examples

page <- pz_open(pz_example("tasks"))
path <- file.path(tempdir(), "tour.mp4")

# While recording, the cursor glides between elements
page |>
  pz_record(path, {
    page |>
      pz_cursor_show(".filters", from = "left") |>
      pz_cursor_move("#toggle-help", duration = 1) |>
      pz_cursor_move("#add-task", icon = "crosshair")
  })
pz_close(page)

Description

Shows paparazzi's overlay cursor, optionally over a target element. While recording, the cursor appears with staging: it glides from its last position, fades in on the target when it has never been shown, or glides in from from (or the enter side set with pz_stage()) when entering the frame. Without a recording the cursor appears statically, which is how a cursor lands in a screenshot. Its default size is 1.75 times the original artwork; set cursor_scale with pz_stage() to change the size in videos and stills.

Usage

pz_cursor_show(ctx, target = NULL, ..., from = NULL, icon = NULL)

Arguments

Value

ctx, invisibly.

See Also

pz_stage() for cursor settings, pz_cursor_hide(), pz_cursor_move(), pz_cursor_leave()

Examples

page <- pz_open(pz_example("tasks"))
path <- file.path(tempdir(), "add-button.png")

# Outside a recording the cursor appears at once, ready for a still
page |>
  pz_cursor_show("#add-task", icon = "pointer") |>
  pz_screenshot(path, frame = pz_frame("#new-task", pad = 24))
pz_screenshot(page, frame = pz_frame("#new-task", pad = 24))
pz_close(page)

Description

Configures device emulation for the page: viewport size, device scale factor, mobile-ness, zoom, color scheme, reduced motion, locale and time zone. Only supplied arguments change state: NULL (the default) means "leave this setting alone", so zoom = 1, not zoom = NULL, disables an active zoom.

Usage

pz_device(
  ctx,
  ...,
  width = NULL,
  height = NULL,
  scale = NULL,
  mobile = NULL,
  zoom = NULL,
  zoom_method = NULL,
  color_scheme = NULL,
  reduced_motion = NULL,
  locale = NULL,
  timezone = NULL
)

Arguments

Details

The two zoom methods trade off differently:

• zoom_method = "viewport" (the default) shrinks the CSS viewport and raises the device scale factor, so vh stays correct but media queries can start (or stop) matching.

• zoom_method = "css" applies a CSS zoom to the page instead – on every document, so it survives navigation and reload: layout and media queries are untouched, but vh-sized elements no longer fit the viewport (a 50vh element covers the whole viewport at zoom 2).

reduced_motion = TRUE gives deterministic stills (animations stop); it's opt-in because it's usually wrong for videos.

Value

ctx, invisibly.

See Also

pz_open() forwards its ... here.

Examples

page <- pz_open(pz_example("tasks"))

# Only the settings you supply change
page |> pz_device(width = 390, height = 844, mobile = TRUE)
pz_evaluate(page, "[window.innerWidth, window.devicePixelRatio]")

page |> pz_device(color_scheme = "dark")
pz_get_style(page, "background-color", target = "body")
pz_close(page)

Description

Evaluates expr in the page, optionally awaiting a returned promise, and returns the resulting value. This is paparazzi's equivalent of Playwright's page.evaluate() (and likewise Puppeteer and the CDP Runtime.evaluate). It is the primitive all element work uses and an escape hatch for one-off scripts. Unlike most ⁠pz_*()⁠ functions it ends the chain: it returns the value, not the context.

Usage

pz_evaluate(ctx, expr, ..., await = TRUE, timeout = NULL)

Arguments

Value

The value produced by expr (converted to R), or NULL.

Examples

page <- pz_open(pz_example("tasks"))
pz_evaluate(page, "document.querySelectorAll('.task').length")

# Arrays come back as lists
pz_evaluate(page, "[...document.querySelectorAll('.task-priority')].map(el => el.textContent)")

# Returned promises are awaited
pz_evaluate(page, "new Promise(resolve => setTimeout(() => resolve('done'), 100))")
pz_close(page)

Description

paparazzi ships a few small pages and apps for its examples and articles. pz_example() returns the path to one of them, ready to pass to pz_open() or pz_serve_shiny(). The examples are:

Usage

pz_example(name = NULL)

Arguments

Details

• "tasks": a static task tracker page (an HTML file) with a form, a scrollable list of draggable tasks, filter links that change the URL fragment, inline title editing, an attachment input for new tasks, a help panel that starts hidden, and a "Start over" link that loads the page again. Adding a task shows "Saving..." for 400ms before the task appears.

• "tasks-app": a Shiny app directory with a text input, a selectize priority input, an Add button, and a task list whose output takes half a second to render. Running it requires the shiny package.

Value

The absolute path to the example's file or directory, or a character vector of example names when name is NULL.

Examples

pz_example()
pz_example("tasks")


page <- pz_open(pz_example("tasks"))
pz_get_title(page)
pz_close(page)

Description

pz_expect_attr() passes when at least one element matches and every matched element satisfies every named attribute/value pair in .... Missing attributes satisfy no pair. Comparisons are exact by default; .match = "contains" or "regex" applies to all pairs in the call.

A length-1 value applies to every element. A vector requires exactly that many matches and compares pairwise, in order. With .not = TRUE, the expectation passes when the combined condition does not hold, including when no element matches.

Outside of testthat, a failure aborts with a classed error of class "paparazzi_expectation_failure"; inside testthat, the failure is reported as a test failure. See pz_expect_exists() for the retry, timeout, and bridge behavior shared by all expectations.

Usage

pz_expect_attr(
  ctx,
  .target = NULL,
  ...,
  .match = c("exact", "contains", "regex"),
  .not = FALSE,
  .timeout = NULL
)

Arguments

Value

ctx, invisibly.

Examples

page <- pz_open(pz_example("tasks"))
page |> pz_expect_attr(
  pz_loc(".task", has_text = "tax"), `data-priority` = "high"
)

page |>
  pz_act_click("#toggle-help") |>
  pz_expect_attr("#toggle-help", `aria-expanded` = "true")
pz_close(page)

Description

pz_expect_checked() passes when at least one element matches and every match is checked (the browser's ⁠:checked⁠ selector, so checkboxes, radios, and select options all count). Toggle with pz_act_click() or pz_set_value().

Outside of testthat, a failure aborts with a classed error of class "paparazzi_expectation_failure"; inside testthat, the failure is reported as a test failure instead. See pz_expect_exists() for the retry, timeout, and bridge behavior shared by all expectations.

Usage

pz_expect_checked(ctx, target = NULL, ..., not = FALSE, timeout = NULL)

Arguments

Value

ctx, invisibly.

Examples

page <- pz_open(pz_example("tasks"))
page |> pz_expect_checked(target = "#task-urgent", not = TRUE)
page |>
  pz_act_click("#task-urgent") |>
  pz_expect_checked(target = "#task-urgent")
pz_close(page)

Description

pz_expect_class() passes when at least one element matches and every match carries class. With not = TRUE it passes when no match does, including when nothing matches. class is one class name, not a space-separated list: expect each class with its own call.

Outside of testthat, a failure aborts with a classed error of class "paparazzi_expectation_failure"; inside testthat, the failure is reported as a test failure instead. See pz_expect_exists() for the retry, timeout, and bridge behavior shared by all expectations.

Usage

pz_expect_class(ctx, class, target = NULL, ..., not = FALSE, timeout = NULL)

Arguments

Value

ctx, invisibly.

Examples

page <- pz_open(pz_example("tasks"))
water <- pz_loc(".task", has_text = "Water")
page |> pz_expect_class("done", target = water, not = TRUE)

page |>
  pz_find(water) |>
  pz_act_click(".task-done") |>
  pz_expect_class("done")
pz_close(page)

Description

pz_expect_count() passes when the number of elements matching target satisfies the requirement: n is exact, or min and/or max give an inclusive range (either may be NULL, meaning unbounded). With not = TRUE it passes when the count does anything else. Specify exactly one of n or min/max.

Outside of testthat, a failure aborts with a classed error of class "paparazzi_expectation_failure"; inside testthat, the failure is reported as a test failure instead. See pz_expect_exists() for the retry, timeout, and bridge behavior shared by all expectations.

Usage

pz_expect_count(
  ctx,
  n = NULL,
  target = NULL,
  ...,
  min = NULL,
  max = NULL,
  not = FALSE,
  timeout = NULL
)

Arguments

Value

ctx, invisibly.

Examples

page <- pz_open(pz_example("tasks"))
page |> pz_expect_count(7, target = ".task")
page |> pz_expect_count(min = 1, max = 2, target = ".task.done")

# Expectations retry, so they wait for the page to catch up: the new task
# appears after a short "Saving..." delay
page |>
  pz_act_type("Buy milk", target = "#task-title") |>
  pz_act_click("#add-task") |>
  pz_expect_count(8, target = ".task")
pz_close(page)

Description

pz_expect_enabled() passes when at least one element matches and every match is enabled. An element counts as disabled when it matches the browser's ⁠:disabled⁠ selector, so inputs inside a disabled ⁠<fieldset>⁠ are disabled too.

Outside of testthat, a failure aborts with a classed error of class "paparazzi_expectation_failure"; inside testthat, the failure is reported as a test failure instead. See pz_expect_exists() for the retry, timeout, and bridge behavior shared by all expectations.

Usage

pz_expect_enabled(ctx, target = NULL, ..., not = FALSE, timeout = NULL)

Arguments

Value

ctx, invisibly.

Examples

page <- pz_open(pz_example("tasks"))

# Add is disabled until the title has text
page |> pz_expect_enabled(target = "#add-task", not = TRUE)
page |>
  pz_act_type("Buy milk", target = "#task-title") |>
  pz_expect_enabled(target = "#add-task")
pz_close(page)

Description

pz_expect_exists() passes when at least one element matching target is in the DOM, visible or not. It's the one expectation where multiple matches don't all have to satisfy the check: existence needs only one. With not = TRUE it passes when nothing matches.

Expectations retry until they pass or timeout elapses, then return ctx invisibly. Outside of testthat, a failure aborts with a classed error of class "paparazzi_expectation_failure" showing the target, the last observed value, and the time waited; inside testthat, the failure is instead reported as a test failure, and a pass counts as a successful testthat expectation.

Usage

pz_expect_exists(ctx, target = NULL, ..., not = FALSE, timeout = NULL)

Arguments

Value

ctx, invisibly.

Examples

page <- pz_open(pz_example("tasks"))
page |> pz_expect_exists(target = ".task")

# The help panel is in the page even while it's hidden
page |> pz_expect_exists(target = "#help")
page |> pz_expect_exists(target = ".error-message", not = TRUE)

# A failing expectation retries until the timeout, then errors
try(pz_expect_exists(page, target = ".error-message", timeout = 0.5))
pz_close(page)

Description

pz_expect_focused() passes when at least one element matches and every match is the page's focused element (document.activeElement). Focus it with pz_act_focus() or a pz_act_click(), and remove it with pz_act_blur().

Outside of testthat, a failure aborts with a classed error of class "paparazzi_expectation_failure"; inside testthat, the failure is reported as a test failure instead. See pz_expect_exists() for the retry, timeout, and bridge behavior shared by all expectations.

Usage

pz_expect_focused(ctx, target = NULL, ..., not = FALSE, timeout = NULL)

Arguments

Value

ctx, invisibly.

Examples

page <- pz_open(pz_example("tasks"))
page |>
  pz_act_click("#task-title") |>
  pz_expect_focused(target = "#task-title")

page |>
  pz_act_press("Tab") |>
  pz_expect_focused(target = "#task-priority")
pz_close(page)

Description

pz_expect_in_viewport() passes when at least one element matches and every match overlaps the viewport: its bounding box crosses the visible area by any amount. Elements entirely above, below, or beside the fold fail; visibility itself is a separate expectation, pz_expect_visible().

Outside of testthat, a failure aborts with a classed error of class "paparazzi_expectation_failure"; inside testthat, the failure is reported as a test failure instead. See pz_expect_exists() for the retry, timeout, and bridge behavior shared by all expectations.

Usage

pz_expect_in_viewport(ctx, target = NULL, ..., not = FALSE, timeout = NULL)

Arguments

Value

ctx, invisibly.

Examples

page <- pz_open(pz_example("tasks"), height = 500)

# The last task is inside the scrolling list, below its visible area
last_task <- pz_loc(".task", which = "last")
page |> pz_expect_in_viewport(target = last_task, not = TRUE)
page |>
  pz_act_scroll(last_task) |>
  pz_expect_in_viewport(target = last_task)
pz_close(page)

Description

pz_expect_js() passes when at least one element matches and the predicate holds for every match: expr is evaluated as a function receiving the element, e.g. "el => el.scrollTop > 0". It's the escape hatch for conditions the catalog doesn't cover. A predicate that throws is a JavaScript error, not a failed check.

Outside of testthat, a failure aborts with a classed error of class "paparazzi_expectation_failure"; inside testthat, the failure is reported as a test failure instead. See pz_expect_exists() for the retry, timeout, and bridge behavior shared by all expectations.

Usage

pz_expect_js(ctx, expr, target = NULL, ..., not = FALSE, timeout = NULL)

Arguments

Value

ctx, invisibly.

Examples

page <- pz_open(pz_example("tasks"))

# The predicate receives each matching element
page |> pz_expect_js("el => el.scrollHeight > el.clientHeight", target = ".task-list")
page |> pz_expect_js("el => el.draggable", target = ".task")
pz_close(page)

Description

pz_expect_style() passes when at least one element matches .target and every match has every named property set to the expected value, comparing computed styles – what the browser actually applied, the same values Playwright's toHaveCSS() and jQuery's .css() read.

Property names accept snake_case, converted to the CSS kebab-case spelling (font_size becomes font-size); custom properties (`--bs-primary` = "#0d6efd") pass through unchanged. By default the expected values are normalized in the browser: what you write ("1.5rem", "#0d6efd", "50%", "currentColor") is resolved against the same context the target sees, so it matches the computed value the browser reports. Numeric pixel values compare with a 0.5px tolerance.

Outside of testthat, a failure aborts with a classed error of class "paparazzi_expectation_failure"; inside testthat, the failure is reported as a test failure instead. See pz_expect_exists() for the retry, timeout, and bridge behavior shared by all expectations.

Usage

pz_expect_style(
  ctx,
  .target = NULL,
  ...,
  .not = FALSE,
  .timeout = NULL,
  .normalize = TRUE
)

Arguments

Details

With .not = TRUE the expectation passes when at least one property/value pair doesn't match (including when nothing matches). With .normalize = FALSE the expected values are compared as raw strings against the browser's computed output, for contexts the probe can't reproduce (unusual ⁠%⁠ cases, container query units); the pixel tolerance still applies.

Shorthand properties (margin, border, background, ...) are unreliable in computed styles and error with a longhand suggestion; check the longhand properties instead. A value the browser rejects errors immediately as invalid CSS, without retrying (only detected with .normalize = TRUE).

Value

ctx, invisibly.

Examples

page <- pz_open(pz_example("tasks"))

# Expected values are written as you'd write them in CSS
page |> pz_expect_style("#add-task", background_color = "#0d6efd")
page |> pz_expect_style("h1", font_size = "1.5rem")
page |> pz_expect_style("#help", display = "none")

page |>
  pz_act_click("#toggle-help") |>
  pz_expect_style("#help", display = "none", .not = TRUE)
pz_close(page)

Description

pz_expect_text() passes when at least one element matches and the text of every match satisfies text. Whitespace collapses on both sides before comparing, so "Save now" matches text reading "Save now".

A length-1 text applies to every match. A length-n text requires exactly n matches and compares pairwise, in order. With not = TRUE, the expectation passes when no match satisfies text, including when nothing matches.

Outside of testthat, a failure aborts with a classed error of class "paparazzi_expectation_failure"; inside testthat, the failure is reported as a test failure instead. See pz_expect_exists() for the retry, timeout, and bridge behavior shared by all expectations.

Usage

pz_expect_text(
  ctx,
  text,
  target = NULL,
  ...,
  match = c("contains", "exact", "regex"),
  not = FALSE,
  timeout = NULL
)

Arguments

Value

ctx, invisibly.

Examples

page <- pz_open(pz_example("tasks"))
page |> pz_expect_text("Tasks", target = "h1", match = "exact")
page |> pz_expect_text("passport", target = pz_loc(".task", which = "first"))

# A vector compares pairwise with the matches, in order
page |> pz_expect_text(c("All", "Open", "Done"), target = ".filters a")

# Regular expressions use R's syntax
page |> pz_expect_text("^[A-Z]", target = ".task-title", match = "regex")

# On failure, the error shows the target and the last text seen
try(pz_expect_text(page, "otters", target = "h1", timeout = 0.5))
pz_close(page)

Description

pz_expect_title() passes when the page's ⁠<title>⁠ satisfies title. It works from any context, scoped or root: the title belongs to the page, not to an element.

Outside of testthat, a failure aborts with a classed error of class "paparazzi_expectation_failure"; inside testthat, the failure is reported as a test failure instead. See pz_expect_exists() for the retry, timeout, and bridge behavior shared by all expectations.

Usage

pz_expect_title(
  ctx,
  title,
  ...,
  match = c("contains", "exact", "regex"),
  not = FALSE,
  timeout = NULL
)

Arguments

Value

ctx, invisibly.

Examples

page <- pz_open(pz_example("tasks"))
page |> pz_expect_title("Tasks", match = "exact")
pz_close(page)

Description

pz_expect_url() passes when the page's URL satisfies url. It works from any context, scoped or root: the URL belongs to the page, not to an element.

Outside of testthat, a failure aborts with a classed error of class "paparazzi_expectation_failure"; inside testthat, the failure is reported as a test failure instead. See pz_expect_exists() for the retry, timeout, and bridge behavior shared by all expectations.

Usage

pz_expect_url(
  ctx,
  url,
  ...,
  match = c("contains", "exact", "regex"),
  not = FALSE,
  timeout = NULL
)

Arguments

Value

ctx, invisibly.

Examples

page <- pz_open(pz_example("tasks"))
page |> pz_expect_url("tasks.html")

page |>
  pz_act_click(pz_loc(".filters a", has_text = "Done")) |>
  pz_expect_url("#done$", match = "regex")
pz_close(page)

Description

pz_expect_value() passes when at least one element matches and the value property of every match satisfies value. Elements without a value property (paragraphs, divs) read as missing and satisfy no value. Checkbox and radio values come from their value attribute (the default is "on"), whatever their checked state.

A length-1 value applies to every match. A length-n value requires exactly n matches and compares pairwise, in order. With not = TRUE, the expectation passes when no match satisfies value, including when nothing matches.

Outside of testthat, a failure aborts with a classed error of class "paparazzi_expectation_failure"; inside testthat, the failure is reported as a test failure instead. See pz_expect_exists() for the retry, timeout, and bridge behavior shared by all expectations.

Usage

pz_expect_value(
  ctx,
  value,
  target = NULL,
  ...,
  match = c("contains", "exact", "regex"),
  not = FALSE,
  timeout = NULL
)

Arguments

Value

ctx, invisibly.

Examples

page <- pz_open(pz_example("tasks"))
page |> pz_expect_value("normal", target = "#task-priority", match = "exact")

page |>
  pz_act_type("Buy milk", target = "#task-title") |>
  pz_expect_value("milk", target = "#task-title")
pz_close(page)

Description

pz_expect_visible() passes when at least one element matches and every match is visible. pz_expect_hidden() is exactly pz_expect_visible(not = TRUE): it passes when no match is visible, including when nothing matches.

Visibility follows the browser's own checkVisibility() (https://developer.mozilla.org/en-US/docs/Web/API/Element/checkVisibility) with CSS checks, so display: none and visibility: hidden anywhere up the ancestor chain count as hidden. Opacity and viewport position are not considered; use pz_expect_in_viewport() for position.

Outside of testthat, a failure aborts with a classed error of class "paparazzi_expectation_failure"; inside testthat, the failure is reported as a test failure instead. See pz_expect_exists() for the retry, timeout, and bridge behavior shared by all expectations.

Usage

pz_expect_visible(ctx, target = NULL, ..., not = FALSE, timeout = NULL)

pz_expect_hidden(ctx, target = NULL, ..., not = FALSE, timeout = NULL)

Arguments

Value

ctx, invisibly.

Examples

page <- pz_open(pz_example("tasks"))
page |> pz_expect_hidden(target = "#help")

page |>
  pz_act_click("#toggle-help") |>
  pz_expect_visible(target = "#help")

# Every match must pass, so check one task or narrow the target
page |> pz_expect_visible(target = pz_loc(".task", has_text = "passport"))
pz_close(page)

Description

pz_find() resolves target (auto-waiting for at least one match), pins the matched set as the current scope, and returns a new context: later calls on it operate inside that scope. Explicit targets resolve lazily among the scope's descendants at use time – re-renders within the scope are fine – and target = NULL means the scope itself for the calls that accept one.

The pinned set is eager: it is fixed at find time, and a later re-render that detaches any of its elements aborts with a classed error on the next use – the scope is never silently re-queried (a lazy, reusable target is what pz_loc() is for). Multi-match targets pin the whole set.

The stack is immutable: ⁠pz_find*()⁠ never mutate the context they are called on, and contexts derived from the same parent share its pinned sets.

Usage

pz_find(ctx, target, ..., from_root = FALSE)

Arguments

Value

A new context.

See Also

pz_find_first(), pz_find_pop(), pz_find_reset()

Examples

page <- pz_open(pz_example("tasks"))

# Inside a scope, targets resolve among the scope's descendants
page |>
  pz_find(pz_loc(".task", has_text = "dentist")) |>
  pz_act_click(".task-done")
pz_get_attr(page, "class", target = pz_loc(".task", has_text = "dentist"))

# Assign a scoped context to start more than one chain from it
task_list <- pz_find(page, ".task-list")
task_list
pz_get_count(task_list, target = ".task.done")

# from_root looks outside the current scope, but still pushes a new scope
task_list |>
  pz_find("#new-task", from_root = TRUE) |>
  pz_act_type("Buy milk", target = "#task-title")
pz_get_value(page, target = "#task-title")
pz_close(page)

Description

pz_find_first() is pz_find() with which = "first". With a target, it pins the spec's first match. Without a target, it narrows the current scope to its first element: one eager slice of the pinned set, with no re-query and no waiting.

Usage

pz_find_first(ctx, target = NULL, ..., from_root = FALSE)

Arguments

Value

A new context.

See Also

pz_find(), pz_find_last(), pz_find_nth()

Examples

page <- pz_open(pz_example("tasks"))
page |>
  pz_find_first(".task") |>
  pz_get_text(target = ".task-title")

# Without a target, narrow the current scope to its first element
page |>
  pz_find(".task[data-priority='normal']") |>
  pz_find_first() |>
  pz_get_text(target = ".task-title")
pz_close(page)

Description

pz_find_last() is pz_find() with which = "last". With a target, it pins the spec's last match. Without a target, it narrows the current scope to its last element: one eager slice of the pinned set, with no re-query and no waiting.

Usage

pz_find_last(ctx, target = NULL, ..., from_root = FALSE)

Arguments

Value

A new context.

See Also

pz_find(), pz_find_first(), pz_find_nth()

Examples

page <- pz_open(pz_example("tasks"))
page |>
  pz_find_last(".task") |>
  pz_get_text(target = ".task-title")
pz_close(page)

Description

pz_find_nth() is pz_find() with which = n. With a target, it pins the spec's nth match; an out-of-range n means no match, so the call keeps auto-waiting like any pz_loc() resolution. Without a target, it narrows the current scope to its nth element: one eager slice of the pinned set, and an out-of-range n errors immediately – the set was fixed at pin time, so there is nothing to wait for.

Usage

pz_find_nth(ctx, n, target = NULL, ..., from_root = FALSE)

Arguments

Value

A new context.

See Also

pz_find(), pz_find_first(), pz_find_last()

Examples

page <- pz_open(pz_example("tasks"))

# Mark the second task as done
page |>
  pz_find_nth(2, target = ".task") |>
  pz_act_click(".task-done")
pz_get_text(page, target = pz_loc(".task.done .task-title"))
pz_close(page)

Description

pz_find_pop() returns a context one scope level up the stack. The popped pinned set is NOT released – a context derived before the pop may still hold it – and popping never mutates the context it was called on. At the root it is a no-op returning ctx unchanged.

Usage

pz_find_pop(ctx)

Arguments

Value

A new context one level up, or ctx itself at the root.

See Also

pz_find(), pz_find_reset()

Examples

page <- pz_open(pz_example("tasks"))
page |>
  pz_find(".task-list") |>
  pz_find_last(".task") |>
  pz_act_click(".task-done") |>
  # Back to the whole list, to check the result
  pz_find_pop() |>
  pz_expect_count(2, target = ".task.done") |>
  pz_get_count(target = ".task.done")
pz_close(page)

Description

pz_find_reset() returns a context with an empty scope stack. No pinned set is released – contexts derived before the reset may still hold them – and resetting never mutates the context it was called on. At the root it is a no-op returning ctx unchanged.

Usage

pz_find_reset(ctx)

Arguments

Value

A new root context, or ctx itself at the root.

See Also

pz_find(), pz_find_pop()

Examples

page <- pz_open(pz_example("tasks"))
page |>
  pz_find(".task-list") |>
  pz_find_first(".task") |>
  pz_act_click(".task-done") |>
  # The help toggle is outside the list, so start again from the root
  pz_find_reset() |>
  pz_act_click("#toggle-help") |>
  pz_expect_visible(target = "#help") |>
  pz_get_text(target = "#help")
pz_close(page)

Description

Declares a font face for pz_stage_fonts(), served by Bunny Fonts (https://fonts.bunny.net), a GDPR-friendly foundry that mirrors the Google Fonts collection and stylesheet format.

Usage

pz_font_bunny(family, weight = 400, style = "normal")

Arguments

Value

A font object for pz_stage_fonts().

See Also

pz_stage_fonts(), pz_font_google(), pz_font_file()

Examples

pz_font_bunny("Inter", style = "italic")

Description

Declares a font face for pz_stage_fonts() from a local font file. The bytes are read by R and handed to the page directly, so the file works on http pages (which cannot load ⁠file://⁠ URLs) and is not subject to Content Security Policy font restrictions. You are responsible for the license of fonts you use.

Usage

pz_font_file(family, path, weight = 400, style = "normal")

Arguments

Value

A font object for pz_stage_fonts().

See Also

pz_stage_fonts(), pz_font_google(), pz_font_bunny()

Examples

## Not run: 
pz_font_file("My Brand Sans", "~/fonts/my-brand-sans.woff2")

## End(Not run)

Description

Declares a font face for pz_stage_fonts(). The family is identified by its Google Fonts name, and Chrome fetches the stylesheet and font files at staging time; nothing is downloaded by R.

Usage

pz_font_google(family, weight = 400, style = "normal")

Arguments

Value

A font object for pz_stage_fonts().

See Also

pz_stage_fonts(), pz_font_bunny(), pz_font_file()

Examples

pz_font_google("Inter", weight = 700)

Description

pz_frame() builds a lazy framing spec for a capture: the region is computed at capture time, then padded, nudged, grown to an aspect ratio, and clamped. Every capture takes one: screenshots through pz_screenshot(frame =), recordings through pz_record_start(frame =), and camera shots through pz_camera(frame =). Wherever a frame is accepted, a bare locator (a CSS selector string, a pz_loc() spec, or a list of either) is promoted to ⁠pz_frame(<locator>)⁠.

Every field defaults to NULL, meaning "inherit": at capture time an unset field takes the pz_stage_frame() value if one is staged, else the built-in default. The built-in defaults are pad = 0, offset = c(0, 0), anchor = "center", when = "stop", and target_box = "element", with ratio, bounds, zoom, and target unset. Camera shots never inherit the staged frame; their built-in defaults are pad = 24 and target_box = "element".

The framed region is computed in this order:

1. Union the bounding boxes of the target's matched elements. With target_box = "annotated", include their attached annotations.

2. Expand by pad.

3. With zoom = NULL, shift by offset, then grow the shorter side to reach ratio (never shrink), placing the content by anchor. With a numeric zoom, the region is the view divided by zoom (the viewport for stills and recordings, the recording's home frame for camera shots), with ratio setting its aspect if given; the padded target is placed inside it by anchor, then shifted by offset.

4. Clamp to bounds and to the page's rendered area.

5. Round to whole pixels.

Usage

pz_frame(
  target = NULL,
  ...,
  ratio = NULL,
  pad = NULL,
  offset = NULL,
  anchor = NULL,
  bounds = NULL,
  when = NULL,
  target_box = NULL,
  zoom = NULL
)

Arguments

Value

An S3 object of class paparazzi_frame.

Examples

# Frames are specs: nothing is measured until a capture uses them
pz_frame(pad = 32)
pz_frame(ratio = 16/9, pad = 24, anchor = "top")
pz_frame(".task-list", ratio = 4/3, bounds = "main")


page <- pz_open(pz_example("tasks"))
path <- file.path(tempdir(), "tasks.png")

# A locator target frames the union of its boxes
page |> pz_screenshot(path, frame = pz_frame(list("h1", ".filters"), pad = 16))

# Unset fields inherit the staged framing
page |>
  pz_stage_frame(pad = 16) |>
  pz_screenshot(path, frame = pz_frame("#new-task", ratio = 16/9))
pz_screenshot(page, frame = pz_frame("#new-task", ratio = 16/9))
pz_close(page)

Description

pz_get_attr() returns the named attribute of every element matching target, one entry per match. Missing attributes give NA.

Usage

pz_get_attr(ctx, name, target = NULL, ...)

Arguments

Value

A character vector, one entry per match.

Examples

page <- pz_open(pz_example("tasks"))
pz_get_attr(page, "data-priority", target = ".task")

# Missing attributes are NA
pz_get_attr(page, "aria-label", target = "select, input[type='text']")
pz_close(page)

Description

pz_get_count() returns the number of elements matching target, counted inside the current scope. Unlike the other getters it doesn't wait for a match: 0 is a valid answer, so it resolves once and returns immediately. One exception: on a scope whose pinned elements have left the page it raises paparazzi_error_detached instead of returning 0, because the pinned set promises a live set and is never silently re-queried.

Usage

pz_get_count(ctx, target = NULL, ...)

Arguments

Value

An integer.

Examples

page <- pz_open(pz_example("tasks"))
pz_get_count(page, target = ".task")

# Zero is an answer, so pz_get_count() never waits
pz_get_count(page, target = ".error-message")

# Counts are relative to the current scope
page |>
  pz_find(".task-list") |>
  pz_get_count(target = ".task.done")
pz_close(page)

Description

pz_get_elements() returns a summary of every element matching target, one row per match in match order: the lowercased tag name, the id and class attributes, and the whitespace-collapsed text. id and class are NA when the attribute is absent.

Usage

pz_get_elements(ctx, target = NULL, ...)

Arguments

Value

A tibble with columns tag, id, class, text, one row per match, plus an element list-column of contexts scoped to each match, pinned at get time (see pz_get_rect()).

Examples

page <- pz_open(pz_example("tasks"))
pz_get_elements(page, target = "#new-task > *")
pz_close(page)

Description

pz_get_html() returns the outer HTML of every element matching target, one entry per match.

Usage

pz_get_html(ctx, target = NULL, ...)

Arguments

Value

A character vector, one entry per match.

Examples

page <- pz_open(pz_example("tasks"))
pz_get_html(page, target = pz_loc(".task", which = "first"))
pz_close(page)

Description

pz_get_rect() returns the bounding box of every element matching target, one row per match in match order.

Usage

pz_get_rect(ctx, target = NULL, ...)

Arguments

Value

A tibble with columns x, y, width, height (doubles, CSS pixels, viewport-relative), one row per match, plus an element list-column. Each element entry is a context scoped to that one match, pinned at get time, so a chain can continue from it: rects$element[[2]] |> pz_act_hover().

Examples

page <- pz_open(pz_example("tasks"))
rects <- pz_get_rect(page, target = ".filters a")
rects

# Each row's element column is a context scoped to that match
rects$element[[3]] |>
  pz_act_click() |>
  pz_expect_url("#done")
pz_close(page)

Description

pz_get_style() returns the computed styles of every element matching target – what the browser actually applied, the same values Playwright's toHaveCSS() and jQuery's .css() read – one row per match in match order. Like all getters it auto-waits for at least one match.

Usage

pz_get_style(ctx, props = NULL, target = NULL, ...)

Arguments

Details

Property names accept snake_case, converted to the CSS kebab-case spelling (font_size becomes font-size, also the column name, so select it with df$`font-size` ); custom properties ("--bs-primary") pass through unchanged. props = NULL returns every computed property the browser reports (longhands only).

Value

A tibble with one row per match, one character column per property, plus an element list-column: each entry is a context scoped to that one match, pinned at get time, so a chain can continue from it (see pz_get_rect()).

See Also

pz_expect_style()

Examples

page <- pz_open(pz_example("tasks"))
pz_get_style(page, c("font-size", "font_weight"), target = "h1")

# One row per match
pz_get_style(page, "text-decoration-line", target = ".task-title")
pz_close(page)

Description

pz_get_text() returns the textContent of every element matching target, one entry per match. By default runs of whitespace are collapsed to single spaces and trimmed, matching pz_expect_text(); raw = TRUE returns the text exactly as the browser holds it.

Usage

pz_get_text(ctx, target = NULL, ..., raw = FALSE)

Arguments

Value

A character vector, one entry per match.

Examples

page <- pz_open(pz_example("tasks"))
pz_get_text(page, target = "h1")

# One string per match
pz_get_text(page, target = ".task[data-priority='high'] .task-title")

# Whitespace is collapsed unless raw = TRUE
pz_get_text(page, target = "#help")
pz_get_text(page, target = "#help", raw = TRUE)
pz_close(page)

Description

pz_get_title() returns the page's current title.

Usage

pz_get_title(ctx)

Arguments

Value

A character vector of length one.

Examples

page <- pz_open(pz_example("tasks"))
pz_get_title(page)
pz_close(page)

Description

pz_get_url() returns the page's current URL.

Usage

pz_get_url(ctx)

Arguments

Value

A character vector of length one.

Examples

page <- pz_open(pz_example("tasks"))
page |> pz_act_click(pz_loc(".filters a", has_text = "Open"))
basename(pz_get_url(page))
pz_close(page)

Description

pz_get_value() returns the value property of every element matching target, one entry per match. Elements without a value property (non-form elements) give NA.

Usage

pz_get_value(ctx, target = NULL, ...)

Arguments

Value

A character vector, one entry per match.

Examples

page <- pz_open(pz_example("tasks"))
page |> pz_act_type("Buy milk", target = "#task-title")
pz_get_value(page, target = list("#task-title", "#task-priority"))
pz_close(page)

Description

Prints a console summary of the page: URL, device, recording and cursor state, and – when target is given – the target's matches resolved relative to the current scope without auto-waiting: a single resolution pass, each match shown as a short opening tag with its visibility, enabled state, and box (long lists are truncated).

The header names the context. At the root it reads ⁠paparazzi page⁠. In a scoped context from pz_find() it reads ⁠paparazzi scope⁠, with the scope stack right under it: live match counts for each level, plus a warning when pinned elements have gone stale.

show = "screenshot" additionally captures an annotated screenshot: dashed outlines over the scope's elements, solid numbered outlines over the target's matches, drawn under paparazzi's shadow-root overlay, so they never appear in pz_screenshot() output. show = "browser" draws the same outlines in the live page, leaves them, and opens the browser via the page's ⁠$view()⁠. show = "auto" picks "screenshot" in interactive sessions and "none" otherwise.

Usage

pz_inspect(
  ctx,
  target = NULL,
  ...,
  path = NULL,
  show = c("auto", "screenshot", "browser", "none")
)

Arguments

Value

ctx, invisibly (visibly in an active recording chain). With show = "screenshot" and path = NULL while knitting, returns ctx visibly so knitr prints the summary and includes the annotated screenshot once. A subsequent action or scope change discards the pending image; a terminal getter leaves it for the next knitr print. If the context belongs to an active recording chain, knitr stops and includes the recording instead of the inspect image.

Examples

page <- pz_open(pz_example("tasks"))
page |> pz_inspect()

# With a target: its matches, resolved inside the current scope
page |>
  pz_find(".task-list") |>
  pz_inspect(".task.done", show = "none")

# An annotated screenshot outlines the scope and the numbered matches
page |>
  pz_find(".task-list") |>
  pz_inspect(".task-done", show = "screenshot", path = file.path(tempdir(), "inspect.png"))
pz_close(page)

Description

pz_loc() builds a page-independent element spec: a CSS selector, optionally narrowed by required text content (has_text), a match position (which), and an ancestor scope (within). Specs are lazy – they resolve at use time, so they follow DOM changes between uses – and can be defined once and reused across sessions.

Wherever a spec is accepted, a bare string is promoted to pz_loc(string), and a list of specs and strings is a union that matches the elements of any member.

Usage

pz_loc(css, ..., has_text = NULL, which = NULL, within = NULL)

Arguments

Value

An S3 object of class paparazzi_loc.

Examples

# A spec describes elements; nothing is looked up until you use it
pz_loc(".task")
pz_loc(".task", has_text = "passport")
pz_loc(".task", which = "last")
pz_loc(".task-done", within = pz_loc(".task", has_text = "dentist"))


page <- pz_open(pz_example("tasks"))

# Specs resolve each time they're used, so define them once and reuse them
high <- pz_loc(".task-title", within = ".task[data-priority='high']")
pz_get_text(page, target = high)

# A list of specs and strings matches the elements of any member
pz_get_count(page, target = list(".task.done", high))
pz_close(page)

Description

pz_nav_goto() navigates to url; pz_nav_reload() reloads the page; pz_nav_back()/pz_nav_forward() step through the history.

Every navigation resets the scope to the root: the returned context has an empty scope stack, and the pinned scope objects are released, so a context scoped before the navigation raises a detach error if used afterwards – re-scope with pz_find() on the returned root context. Session-level state (timeout and recording) is untouched, and staged settings carry over to the returned context.

Usage

pz_nav_goto(ctx, url, ..., wait = c("auto", "load", "shiny", "none"))

pz_nav_reload(ctx, ..., wait = c("auto", "load", "shiny", "none"))

pz_nav_back(ctx, ...)

pz_nav_forward(ctx, ...)

Arguments

Value

The root context, invisibly.

See Also

pz_find_reset() for scope-only resets (no navigation).

Examples

page <- pz_open(pz_example("tasks"))
url <- pz_get_url(page)

# The filter links change the URL fragment, so each filter is a history entry
page |> pz_nav_goto(paste0(url, "#done"))
pz_get_count(page, target = ".task:not(.hidden)")

page |> pz_nav_back()
pz_get_count(page, target = ".task:not(.hidden)")

page |> pz_nav_forward()
pz_get_url(page)

# Reloading keeps the URL, fragment included
page |> pz_nav_reload()
pz_get_url(page)
pz_close(page)

Description

Opens a URL, local file, local server, or existing chromote::ChromoteSession as a paparazzi page: the root context that starts every ⁠|>⁠ chain.

Usage

pz_open(
  x,
  ...,
  wait = c("auto", "load", "shiny", "none"),
  timeout = 10,
  shiny_options = list(),
  envvars = NULL
)

Arguments

Value

A PaparazziPage (the root context).

Browser

pz_open() opens pages in chromote's default browser (chromote::default_chromote_object()) and starts it if none is running. A browser paparazzi starts keeps its profile in tempdir(), so the profile is removed when R exits, unless a --user-data-dir is already set with chromote::set_chrome_args(). A default set with chromote::set_default_chromote_object() is used as-is.

Examples

# An HTML file is served over HTTP so the page gets bfcache and other
# HTTP-only behavior
page <- pz_open(pz_example("tasks"))
pz_get_url(page)
pz_close(page)

# Named arguments in `...` set up the device before the page loads
phone <- pz_open(pz_example("tasks"), width = 390, height = 844, mobile = TRUE)
pz_evaluate(phone, "window.innerWidth")
pz_screenshot(phone, frame = pz_frame("#new-task", pad = 16))
pz_close(phone)


# An app directory runs in a background R process that the page owns.
# pz_open() returns once Shiny has connected and gone idle.
page <- pz_open(pz_example("tasks-app"))
pz_get_text(page, target = "#summary")
pz_close(page) # also stops the app

Description

The block form of pz_record_start(): starts recording, evaluates the embraced expression code, and stops and encodes on exit – including on error, so a failed run still produces the video up to the failure. Returns what pz_record_stop() returns, never the block's value: ctx invisibly when a path was given outside knitting, media while knitting, or a viewer preview when the path is NULL in an interactive session. Write pz_record(code = { ... }) to omit the path.

Usage

pz_record(ctx, path = NULL, code, ...)

Arguments

Value

ctx, invisibly, or printable media; see pz_record_stop().

Examples

page <- pz_open(pz_example("tasks"))
path <- file.path(tempdir(), "add-task.mp4")

# The recording stops and is written when the block exits, even on error
page |>
  pz_record(path, {
    page |>
      pz_act_type("Buy milk", target = "#task-title") |>
      pz_act_click("#add-task") |>
      pz_expect_count(8, target = ".task")
  }) |>
  pz_screenshot(file.path(tempdir(), "after.png"))
file.exists(path)
pz_close(page)

Description

Lingers on the current frame for seconds in the output video. Unlike pz_wait(), the hold advances only the video clock. Captions, annotations, and keystroke callouts added afterward appear after the held segment. When the page is not recording this is a no-op, so debugging a chain with the recording commented out doesn't pay for video-only pauses. A camera move still in progress (see pz_camera()) finishes before the hold begins.

Usage

pz_record_hold(ctx, seconds)

Arguments

Value

ctx, invisibly.

Examples

page <- pz_open(pz_example("tasks"))

# Without a recording, pz_record_hold() returns straight away
system.time(pz_record_hold(page, 2))

path <- file.path(tempdir(), "help.mp4")
page |>
  pz_record_start(path) |>
  pz_act_click("#toggle-help") |>
  # Give viewers a second to read the help text
  pz_record_hold(1) |>
  pz_record_stop()
pz_close(page)

Description

pz_record_pause() cuts the stretch up to the next pz_record_resume() out of the recording: no frames are captured and the video clock stops, so the pause leaves no trace in the output.

Usage

pz_record_pause(ctx)

pz_record_resume(ctx)

Arguments

Value

ctx, invisibly.

Examples

page <- pz_open(pz_example("tasks"))
path <- file.path(tempdir(), "add-task.mp4")
page |>
  pz_record_start(path) |>
  pz_act_click("#task-title") |>
  pz_record_pause() |>
  # Filling in the form is cut from the video
  pz_set_value("Buy milk", target = "#task-title") |>
  pz_set_value("high", target = "#task-priority") |>
  pz_record_resume() |>
  pz_act_click("#add-task") |>
  pz_expect_count(8, target = ".task") |>
  pz_record_stop()
pz_close(page)

Description

pz_record_start() begins recording the page to a video or GIF; pz_record_stop() ends the recording, encodes it, and writes the file. pz_record_pause()/pz_record_resume() cut stretches out of the recording, and pz_record_hold() lingers on the current frame. pz_record() is the block form: it records for the duration of an expression and stops on exit, including on error.

The output format comes from the path extension: .mp4 (h264), .webm, or .gif. Both methods produce a video at the requested fps; when a new frame is not available, the previous frame is repeated.

Usage

pz_record_start(
  ctx,
  path = NULL,
  ...,
  method = c("poll", "screencast"),
  frame = NULL,
  fps = 15,
  scale = NULL,
  hold = c(0.5, 1),
  keep_frames = FALSE,
  captions = c("burn", "vtt", "both"),
  format = c("auto", "mp4", "webm", "gif")
)