# `Fluffy`
[🔗](https://github.com/ftes/fluffy/blob/v0.8.0/lib/fluffy.ex#L1)

Pipeable feature testing for Phoenix applications.

Start a session with the Phoenix (`:phoenix`) or Playwright (`:playwright`)
backend, then compose locators, actions, expectations, and event waits.
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` (`t:non_neg_integer/0`) - Maximum time in milliseconds to wait for the operation. Playwright browser bookkeeping and navigation synchronization use the session timeout separately.

# `close_session`

Closes a session and its resources. Returns `:ok` or `{:error, reason}`.

# `reload`

```elixir
@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`

```elixir
@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` (`t:atom/0`)

* `:base_url` (`t:String.t/0`)

* `:headers` (list of tuple of , `t:String.t/0` values)

* `:conn` (struct of type `Plug.Conn`)

* `:timeout` (`t:pos_integer/0`)

* `:browser_context` (`t:keyword/0`)

  * `:accept_downloads` (`t:boolean/0`)

  * `:bypass_csp` (`t:boolean/0`)

  * `:color_scheme`

  * `:contrast`

  * `:device_scale_factor`

  * `:extra_http_headers` (map of `t:String.t/0` keys and `t:String.t/0` values)

  * `:forced_colors`

  * `:geolocation` (`t:map/0`)

  * `:has_touch` (`t:boolean/0`)

  * `:http_credentials` (`t:map/0`)

  * `:ignore_https_errors` (`t:boolean/0`)

  * `:is_mobile` (`t:boolean/0`)

  * `:java_script_enabled` (`t:boolean/0`)

  * `:locale` (`t:String.t/0`)

  * `:offline` (`t:boolean/0`)

  * `:permissions` (list of `t:String.t/0`)

  * `:proxy` (`t:map/0`)

  * `:reduced_motion`

  * `:screen` (`t:map/0`)

    * `:width` (`t:pos_integer/0`) - Required.

    * `:height` (`t:pos_integer/0`) - Required.

  * `:service_workers`

  * `:storage_state`

  * `:strict_selectors` (`t:boolean/0`)

  * `:timezone_id` (`t:String.t/0`)

  * `:user_agent` (`t:String.t/0`)

  * `:viewport`

# `visit`

# `check`

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

# `click`

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

# `fill`

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

Fills a control with the literal string representation of `value`.

Accepts any value implementing `String.Chars`, including numbers, dates,
and custom structs. Conversion uses `to_string/1`, without HTML escaping.

Filling contenteditable elements requires Playwright. Static and LiveView
support input and textarea controls.

# `press`

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

Presses a key on one strict target. Behavior depends on the current driver.

Playwright performs a native key press, including browser default actions,
and accepts Playwright key names, characters, and modifier combinations.

LiveView forwards `%{"key" => key}` unchanged to LiveViewTest's
`render_keydown/2` and `render_keyup/2` for bindings on the selected element.
Either or both phases may be bound, including `phx-window-keydown` and
`phx-window-keyup` on that element. An element with no keyboard binding raises.
LiveViewTest handles event values and targeting. Fluffy does not filter
`phx-key`, translate key names, parse modifier combinations, synthesize input
values, change focus, edit text, activate controls, or submit forms.
The caller is responsible for supplying the intended key value.

Static pages do not support `press` and raise `Fluffy.CapabilityError`.
Use `submit/2` to submit a form explicitly on any driver.

# `select_option`

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

Selects options by value or label, or explicitly with `%{value: value}`,
`%{label: label}`, or `%{index: index}`.

Values and labels accept `String.Chars` and are converted without HTML
escaping. Indexes remain zero-based integers. A list requests multiple
options; wrap a charlist in `%{value: charlist}` or `%{label: charlist}`
to use it as one option.

# `set_input_files`

```elixir
@spec set_input_files(
  Fluffy.Session.t(),
  Fluffy.Locator.t() | Fluffy.FileChooser.t(),
  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.

Pass a chooser returned by `Fluffy.Event.file_chooser/1` directly. It targets
its original page and preserves the session's current-page selection. Choosers
require Playwright. The returned session keeps this action pipeable:

    pending = wait_for(session, Fluffy.Event.file_chooser())

    session
    |> click(by_role(:button, name: "Upload"))
    |> set_input_files(await(pending), "test/fixtures/report.pdf")
    |> click(by_role(:button, name: "Save"))

Register the wait before clicking the button. `await/1` returns the chooser;
`set_input_files/4` fills its input and returns the session.

## Options

* `:timeout` (`t: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` (`t:non_neg_integer/0`) - Maximum aggregate size of the selected files in bytes.

# `submit`

```elixir
@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`

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

# `await`

```elixir
@spec await(Fluffy.Event.Pending.t()) :: term()
```

Consumes a pending event and returns its value. Its deadline starts at registration.

# `off`

Removes the most recently registered listener matching this source, event type, and handler.

# `on`

Registers a persistent handler. Handlers run independently, linked to the registering caller.

# `once`

Registers a handler for the first matching event, removing it before invocation.

# `wait_for`

```elixir
@spec wait_for(Fluffy.Session.t(), Fluffy.Event.t(), [Fluffy.Event.option()]) ::
  Fluffy.Event.Pending.t()
```

Registers an event wait immediately. Await the pending handle once with `await/1`.

# `open_browser`

```elixir
@spec open_browser(Fluffy.Session.t()) :: Fluffy.Session.t()
```

Opens a temporary HTML snapshot of the active page in your default browser.

Returns the unchanged session so it can be used in a pipeline. Static and
LiveView pages resolve local assets through the session endpoint; LiveView
snapshots show the full page, including the root layout and portal content.
Playwright pages resolve assets against the page URL. Scripts are removed. This is an HTML snapshot, not an offline archive:
browser resources must remain accessible, and DOM properties such as unsaved
input values, canvas contents, and shadow roots are not serialized.

The temporary file remains available after the session closes.

    session
    |> visit("/chamber")
    |> open_browser()

# `step`
*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`

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.

# `action_option`

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

# `backend`

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

# `file_input_option`

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

# `session_option`

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*
