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

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

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

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