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.
Import Fluffy.Expect for expectations, or use Fluffy.Assert for
ExUnit-style assertions. 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. Playwright browser bookkeeping and navigation synchronization use the session timeout separately.
Summary
Actions
Drags the source locator onto the target locator in the same frame. Requires Playwright.
Hovers over a locator. Requires Playwright.
Presses Enter, Space, or Tab on one strict target.
Types text character by character, emitting keyboard events. Accepts :delay in milliseconds. Requires Playwright.
Selects local paths or in-memory Fluffy.FilePayload values for a file
input, or clears its FileList with [].
Submits one form through its native submission path.
Event capture and results
Returns a previously captured dialog without consuming it.
Returns a previously captured download without consuming it.
Returns a previously captured file chooser without consuming it.
Returns a previously captured navigation without consuming it.
Returns a previously captured Fluffy.Page without consuming it.
Returns a previously captured request without consuming it.
Returns a previously captured response without consuming it.
Captures an event caused by action and stores the normalized result under
the event's key.
Diagnostics and native access
Groups the operations in fun under a named diagnostic step.
Runs a driver-specific native operation and returns the reconciled session.
Actions
@spec blur(Fluffy.Session.t(), Fluffy.Locator.t(), [action_option()]) :: Fluffy.Session.t()
@spec check(Fluffy.Session.t(), Fluffy.Locator.t(), [action_option()]) :: Fluffy.Session.t()
@spec click(Fluffy.Session.t(), Fluffy.Locator.t(), [action_option()]) :: Fluffy.Session.t()
Drags the source locator onto the target locator in the same frame. Requires Playwright.
@spec fill(Fluffy.Session.t(), Fluffy.Locator.t(), String.t(), [action_option()]) :: Fluffy.Session.t()
@spec focus(Fluffy.Session.t(), Fluffy.Locator.t(), [action_option()]) :: Fluffy.Session.t()
Hovers over a locator. Requires Playwright.
@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.
Types text character by character, emitting keyboard events. Accepts :delay in milliseconds. Requires Playwright.
@spec select_option(Fluffy.Session.t(), Fluffy.Locator.t(), term(), [action_option()]) :: Fluffy.Session.t()
@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. Playwright browser bookkeeping and navigation synchronization use the session timeout separately.:max_bytes(non_neg_integer/0) - Maximum aggregate size of the selected files in bytes.
@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.
@spec uncheck(Fluffy.Session.t(), Fluffy.Locator.t(), [action_option()]) :: Fluffy.Session.t()
Event capture and results
Returns a previously captured dialog without consuming it.
Returns a previously captured download without consuming it.
Returns a previously captured file chooser without consuming it.
@spec page(Fluffy.Session.t(), term()) :: Fluffy.Page.t()
Returns a previously captured Fluffy.Page without consuming it.
Returns a previously captured request without consuming it.
Returns a previously captured response without consuming it.
@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 capture timeout starts when arming; events arriving after it expires are ignored. The returned session keeps the captured result so the call remains pipeable.
Diagnostics and native access
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.
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
@type action_option() :: {:timeout, non_neg_integer()}
@type backend() :: :phoenix | :playwright
@type file_input_option() :: {:timeout, non_neg_integer()} | {:max_bytes, non_neg_integer()}