Fluffy (Fluffy v0.2.0)

Pipeable feature testing for Phoenix applications.

Start a session with the Phoenix (:phoenix) or Playwright (:playwright) backend, then compose locators, actions, expectations, and event capture. The Phoenix backend selects its Static (Phoenix.ConnTest) or LiveView (Phoenix.LiveViewTest) driver for each page; the Playwright backend uses the Playwright driver.

Unless a function documents additional entries, action, assertion, reload, and event-wait option lists accept:

:timeout (non_neg_integer/0) - Maximum time in milliseconds to wait for the operation.

Summary

Lifecycle and navigation

close_page(session, name \\ nil)

Closes a named Playwright page, or the active page when no name is supplied.

page_names(session)

Returns all current session-local page names.

reload(session, options \\ [])

Reloads the active page's current document and returns the updated session.

start_session(backend, options \\ [])

Starts an isolated :phoenix or :playwright session.

switch_page(session, name)

Makes a named Playwright page the target of subsequent actions and assertions.

visit(session, path)

Actions

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

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

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

fill(session, locator, value, options \\ [])

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

press(session, locator, key, options \\ [])

Presses Enter, Space, or Tab on one strict target.

select_option(session, locator, requested, options \\ [])

set_input_files(session, locator_or_chooser, selection, options \\ [])

Selects local paths or in-memory Fluffy.FilePayload values for a file input, or clears its FileList with [].

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

Submits one form through its native submission path.

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

Assertions

expect(session, expectation, options \\ [])

Executes a typed assertion value and returns the unchanged or reconciled session.

not_(expectation)

Event capture and results

dialog(session, key)

Returns a previously captured dialog without consuming it.

download(session, key)

Returns a previously captured download without consuming it.

file_chooser(session, key)

Returns a previously captured file chooser without consuming it.

navigation(session, key)

Returns a previously captured navigation without consuming it.

page(session, name)

Returns a previously captured Fluffy.Page without consuming it.

request(session, key)

Returns a previously captured request without consuming it.

response(session, key)

Returns a previously captured response without consuming it.

wait_for(session, event, action, options \\ [])

Captures an event caused by action and stores the normalized result under the event's key.

Diagnostics and native access

step(session, name, fun)

Groups the operations in fun under a named diagnostic step.

unwrap(session, fun)

Runs a driver-specific native operation and returns the reconciled session.

Types

action_option()

backend()

file_input_option()

session_option()

Lifecycle and navigation

close_page(session, name \\ nil)

Closes a named Playwright page, or the active page when no name is supplied.

page_names(session)

Returns all current session-local page names.

reload(session, options \\ [])

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

Reloads the active page's current document and returns the updated session.

The Phoenix backend re-dispatches the current URL and selects the Static or LiveView driver for the returned page. The Playwright backend asks the active browser page to reload.

start_session(backend, options \\ [])

@spec start_session(backend(), [session_option()]) :: Fluffy.Session.t()

Starts an isolated :phoenix or :playwright session.

Configure the application endpoint once with config :fluffy, endpoint: MyAppWeb.Endpoint. The session base URL uses the endpoint's active HTTP or HTTPS listener when available and otherwise falls back to MyAppWeb.Endpoint.url(). An explicit :endpoint or :base_url option overrides the application configuration for this session.

Options

:endpoint (atom/0)
:base_url (String.t/0)
:headers (list of tuple of , String.t/0 values)
:conn (struct of type Plug.Conn)
:timeout (pos_integer/0)
:browser_context (keyword/0)
- :accept_downloads (boolean/0)
- :bypass_csp (boolean/0)
- :color_scheme
- :contrast
- :device_scale_factor
- :extra_http_headers (map of String.t/0 keys and String.t/0 values)
- :forced_colors
- :geolocation (map/0)
- :has_touch (boolean/0)
- :http_credentials (map/0)
- :ignore_https_errors (boolean/0)
- :is_mobile (boolean/0)
- :java_script_enabled (boolean/0)
- :locale (String.t/0)
- :offline (boolean/0)
- :permissions (list of String.t/0)
- :proxy (map/0)
- :reduced_motion
- :screen (map/0)
  - :width (pos_integer/0) - Required.
  - :height (pos_integer/0) - Required.
- :service_workers
- :storage_state
- :strict_selectors (boolean/0)
- :timezone_id (String.t/0)
- :user_agent (String.t/0)
- :viewport

switch_page(session, name)

Makes a named Playwright page the target of subsequent actions and assertions.

visit(session, path)

Actions

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

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

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

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

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

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

fill(session, locator, value, options \\ [])

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

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

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

press(session, locator, key, options \\ [])

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

Presses Enter, Space, or Tab on one strict target.

On a LiveView page, direct or window phx-keydown/phx-keyup bindings and phx-key filters are dispatched with their browser-shaped key and current value payload before and around the supported structural default action. Plain event names and push-only Phoenix.LiveView.JS bindings are portable; client-side JS commands, custom LiveSocket metadata, modifiers, key repeat, and timing assertions require Playwright.

press(locator, "Enter") means the browser's implicit Enter behavior. Use submit/2 when the intent is simply to submit a form.

select_option(session, locator, requested, options \\ [])

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

set_input_files(session, locator_or_chooser, selection, options \\ [])

@spec set_input_files(
  Fluffy.Session.t(),
  Fluffy.Locator.t() | atom(),
  String.t() | Fluffy.FilePayload.t() | [String.t()] | [Fluffy.FilePayload.t()],
  [file_input_option()]
) :: Fluffy.Session.t()

Selects local paths or in-memory Fluffy.FilePayload values for a file input, or clears its FileList with [].

One path or payload selects one file. A non-empty homogeneous list selects files in list order on an input with the multiple attribute. [] clears the current selection. The complete value is validated and snapshotted before the page changes. Static and LiveView drivers carry those snapshots into form submission or the supported managed-upload lifecycle; Playwright uses its native path or payload transport.

The default aggregate selection limit is configured with config :fluffy, file_input_max_bytes: 10_000_000. Override it for one action with :max_bytes. File contents are never included in size or validation errors.

When locator_or_chooser is an atom, it names a chooser previously captured with Fluffy.Event.file_chooser/2. Chooser-key selection is available only in Playwright sessions.

Options

:timeout (non_neg_integer/0) - Maximum time in milliseconds to wait for the operation.
:max_bytes (non_neg_integer/0) - Maximum aggregate size of the selected files in bytes.

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

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

Submits one form through its native submission path.

This is a semantic form action, not a synthetic keyboard event. Clicking a particular submit button remains the way to select a submitter and its name/value or override attributes.

Playwright follows browser-native constraint validation. Static and LiveView deliberately bypass it and submit the current structural form state; use Playwright when the test concerns invalid events, validity UI, focus, or browser-blocked submission.

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

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

Assertions

expect(session, expectation, options \\ [])

@spec expect(Fluffy.Session.t(), Fluffy.Expect.t(), [Fluffy.Expect.option()]) ::
  Fluffy.Session.t()

Executes a typed assertion value and returns the unchanged or reconciled session.

not_(expectation)

Event capture and results

dialog(session, key)

Returns a previously captured dialog without consuming it.

download(session, key)

Returns a previously captured download without consuming it.

file_chooser(session, key)

Returns a previously captured file chooser without consuming it.

page(session, name)

@spec page(Fluffy.Session.t(), term()) :: Fluffy.Page.t()

Returns a previously captured Fluffy.Page without consuming it.

request(session, key)

Returns a previously captured request without consuming it.

response(session, key)

Returns a previously captured response without consuming it.

wait_for(session, event, action, options \\ [])

@spec wait_for(
  Fluffy.Session.t(),
  Fluffy.Event.t(),
  (Fluffy.Session.t() -> Fluffy.Session.t()),
  [
    Fluffy.Event.option()
  ]
) :: Fluffy.Session.t()

Captures an event caused by action and stores the normalized result under the event's key.

The listener is installed before the action runs. The returned session keeps the captured result so the call remains pipeable.

Diagnostics and native access

step(session, name, fun)

(macro)

Groups the operations in fun under a named diagnostic step.

Playwright sessions with tracing enabled record a nested trace group at the call site's source location. Phoenix sessions and untraced Playwright sessions simply run the callback. The callback must return the updated session, which is also returned by step/3.

unwrap(session, fun)

Runs a driver-specific native operation and returns the reconciled session.

Static callbacks receive the current Plug.Conn and must return an updated Plug.Conn. LiveView callbacks receive the current Phoenix.LiveViewTest.View, and Playwright callbacks receive a Fluffy.Playwright.Handle. Successful LiveView and Playwright callback return values are ignored.

Native operations are not cross-driver compatible. Prefer the shared Fluffy API whenever it covers the behavior under test.

Types

action_option()

@type action_option() :: {:timeout, non_neg_integer()}

backend()

@type backend() :: :phoenix | :playwright

file_input_option()

@type file_input_option() ::
  {:timeout, non_neg_integer()} | {:max_bytes, non_neg_integer()}

session_option()

@type session_option() ::
  {:endpoint, atom()}
  | {:base_url, binary()}
  | {:headers, [{atom() | binary(), binary()}]}
  | {:conn, struct()}
  | {:timeout, pos_integer()}
  | {:browser_context, keyword()}