Fluffy.Playwright (Fluffy v0.7.0)

Browser-only helpers for the active Playwright page.

These functions intentionally live under Fluffy.Playwright because they depend on a real browser. Use them when behavior requires one; they are not implemented by the Static or LiveView drivers.

Summary

Types

evaluate_option()

screenshot_option()

trace_option()

Functions

add_cookies(session, cookies)

Adds cookie maps to the browser context and returns the session.

clear_cookies(session, options \\ [])

Clears cookies and returns the session. Filters :name, :domain, and :path accept strings or regexes. Accepts :timeout.

cookies(session, options \\ [])

Returns browser cookies, optionally filtered by a list of :urls. Accepts :timeout.

evaluate(session, expression, options \\ [])

Evaluates JavaScript in the active Playwright page and returns the value.

screenshot(session, path, options \\ [])

Saves a PNG screenshot of the active page and returns the session.

storage_state(session, options \\ [])

Returns storage state for reuse as browser_context: [storage_state: state]. Accepts :indexed_db, :timeout, and optional JSON output :path.

trace(session, options \\ [])

Starts a Playwright trace for this session's BrowserContext.

Actions

blur(session, locator, options \\ [])

Blurs the target in the active browser page.

drag_to(session, source, target, options \\ [])

Drags the source locator onto the target locator in the same frame. Requires Playwright.

focus(session, locator, options \\ [])

Focuses the target in the active browser page.

hover(session, locator, options \\ [])

Hovers over a locator. Requires Playwright.

press_sequentially(session, locator, text, options \\ [])

Types text character by character, emitting keyboard events. Accepts :delay in milliseconds. Requires Playwright.

Lifecycle and navigation

close_page(session)

Closes a page. Handles selecting it must explicitly switch to another page before continuing.

close_page(session, page)

Closes the given page handle, preserving the session's current-page selection.

current_page(session)

Returns a live handle to the selected page.

go_back(session, options \\ [])

Navigates backward in browser history. Does nothing if there is no entry.

go_forward(session, options \\ [])

Navigates forward in browser history. Does nothing if there is no entry.

new_page(session)

Creates a blank page in the session's browser context and returns its handle.

pages(session)

Returns live handles for all open pages, including browser pages discovered without an event wait.

switch_page(session, page)

Selects a page handle for this pipeline, without changing other session handles.

Types

evaluate_option()

@type evaluate_option() ::
  {:arg, term()}
  | {:is_function, boolean()}
  | {:timeout, nil | non_neg_integer()}

screenshot_option()

@type screenshot_option() ::
  {:full_page, boolean()}
  | {:omit_background, boolean()}
  | {:timeout, pos_integer()}

trace_option()

@type trace_option() ::
  {:directory, binary()}
  | {:name, binary()}
  | {:open, boolean()}
  | {:screenshots, boolean()}
  | {:snapshots, boolean()}
  | {:sources, boolean()}

Functions

add_cookies(session, cookies)

(Playwright only)

Adds cookie maps to the browser context and returns the session.

clear_cookies(session, options \\ [])

(Playwright only)

Clears cookies and returns the session. Filters :name, :domain, and :path accept strings or regexes. Accepts :timeout.

cookies(session, options \\ [])

(Playwright only)

Returns browser cookies, optionally filtered by a list of :urls. Accepts :timeout.

evaluate(session, expression, options \\ [])

(Playwright only)

@spec evaluate(Fluffy.Session.t(), String.t(), [evaluate_option()]) :: term()

Evaluates JavaScript in the active Playwright page and returns the value.

This mirrors Playwright's page/frame evaluation semantics: promises are awaited by Playwright, serializable JavaScript values are returned to Elixir, and JavaScript or protocol failures raise.

evaluate/3 is a browser-only value query, so it returns the evaluated value rather than the Fluffy session. Use Elixir's then/2 when a pipeline needs the value and then should continue with the session:

import Fluffy
import Fluffy.Playwright
import Fluffy.Locator
alias Fluffy.Playwright

session
|> then(fn session ->
  title = Playwright.evaluate(session, "document.title")
  assert title == "Potions classroom"
  session
end)
|> click(by_role(:button, name: "Continue"))

For function-style expressions, pass is_function: true and arg::

Playwright.evaluate(session, "selector => document.querySelector(selector).textContent",
  is_function: true,
  arg: "#status"
)

Do not use this for JavaScript that owns a navigation, opens a page, starts a download, or installs a durable listener. Use the corresponding listener-before-action Fluffy.wait_for/3 event API so lifecycle and cleanup remain owned by Fluffy. Reserve Fluffy.unwrap/2 for uncommon page-local operations that have no first-class API.

Options

:arg (term/0) - Serializable argument passed to a function-style expression. The default value is nil.
:is_function (boolean/0) - Treat the expression as a JavaScript function. The default value is false.
:timeout (non_neg_integer/0 or nil) - Maximum evaluation time in milliseconds; defaults to the session timeout. The default value is nil.

screenshot(session, path, options \\ [])

(Playwright only)

@spec screenshot(Fluffy.Session.t(), Path.t(), [screenshot_option()]) ::
  Fluffy.Session.t()

Saves a PNG screenshot of the active page and returns the session.

Options

:full_page (boolean/0) - Capture the full scrollable page instead of only the viewport. The default value is false.
:omit_background (boolean/0) - Hide the default white background to allow transparency. The default value is false.
:timeout (pos_integer/0) - Maximum screenshot time in milliseconds.

storage_state(session, options \\ [])

(Playwright only)

Returns storage state for reuse as browser_context: [storage_state: state]. Accepts :indexed_db, :timeout, and optional JSON output :path.

trace(session, options \\ [])

(Playwright only)

@spec trace(Fluffy.Session.t(), [trace_option()]) :: Fluffy.Session.t()

Starts a Playwright trace for this session's BrowserContext.

The trace includes every page in the session and is saved when the test's lifecycle scope shuts down. Because an explicit trace is primarily a local debugging request, its viewer opens by default; pass open: false in CI. A session may start one trace.

Options

:directory (String.t/0) - Directory in which to save the trace archive.
:name (String.t/0) - Human-readable trace name and artifact filename prefix.
:open (boolean/0) - Open Playwright Trace Viewer after saving the trace. The default value is true.
:screenshots (boolean/0) - Capture screenshots during tracing. The default value is true.
:snapshots (boolean/0) - Capture DOM snapshots and network activity. The default value is true.
:sources (boolean/0) - Include source files in the trace. The default value is true.

Actions

blur(session, locator, options \\ [])

(Playwright only)

@spec blur(Fluffy.Session.t(), Fluffy.Locator.t(), [Fluffy.action_option()]) ::
  Fluffy.Session.t()

Blurs the target in the active browser page.

drag_to(session, source, target, options \\ [])

(Playwright only)

Drags the source locator onto the target locator in the same frame. Requires Playwright.

focus(session, locator, options \\ [])

(Playwright only)

@spec focus(Fluffy.Session.t(), Fluffy.Locator.t(), [Fluffy.action_option()]) ::
  Fluffy.Session.t()

Focuses the target in the active browser page.

hover(session, locator, options \\ [])

(Playwright only)

Hovers over a locator. Requires Playwright.

press_sequentially(session, locator, text, options \\ [])

(Playwright only)

Types text character by character, emitting keyboard events. Accepts :delay in milliseconds. Requires Playwright.

Lifecycle and navigation

close_page(session)

(Playwright only)

@spec close_page(Fluffy.Session.t()) :: Fluffy.Session.t()

Closes a page. Handles selecting it must explicitly switch to another page before continuing.

close_page(session, page)

(Playwright only)

@spec close_page(Fluffy.Session.t(), Fluffy.Page.t()) :: Fluffy.Session.t()

Closes the given page handle, preserving the session's current-page selection.

current_page(session)

(Playwright only)

@spec current_page(Fluffy.Session.t()) :: Fluffy.Page.t()

Returns a live handle to the selected page.

go_back(session, options \\ [])

(Playwright only)

Navigates backward in browser history. Does nothing if there is no entry.

go_forward(session, options \\ [])

(Playwright only)

Navigates forward in browser history. Does nothing if there is no entry.

new_page(session)

(Playwright only)

@spec new_page(Fluffy.Session.t()) :: Fluffy.Page.t()

Creates a blank page in the session's browser context and returns its handle.

The session keeps its current page selection. Use switch_page/2 to select the new page. Pages share the context's cookies and storage.

import Fluffy
import Fluffy.Playwright

main = current_page(session)
other = Fluffy.Playwright.new_page(session)

session
|> switch_page(other)
|> visit("/dashboard")
|> switch_page(main)

pages(session)

(Playwright only)

@spec pages(Fluffy.Session.t()) :: [Fluffy.Page.t()]

Returns live handles for all open pages, including browser pages discovered without an event wait.

switch_page(session, page)

(Playwright only)

@spec switch_page(Fluffy.Session.t(), Fluffy.Page.t()) :: Fluffy.Session.t()

Selects a page handle for this pipeline, without changing other session handles.