Fluffy.Playwright (Fluffy v0.1.1)

Copy Markdown View Source

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

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.

trace(session, options \\ [])

Starts a Playwright trace for this session's BrowserContext.

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

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

@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:

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

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

Fluffy.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 \\ [])

@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.

trace(session, options \\ [])

@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.