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

A PhoenixTest-style facade over Fluffy's actions and assertions.

Import this module on its own to keep familiar PhoenixTest helper names with
either backend. See [Coming from PhoenixTest](migration-from-phoenix-test.md)
for migration setup, examples, and compatibility differences.

Actions and assertions return a `Fluffy.PhoenixTest.Session`. Native Fluffy
APIs accept its contained `session` field. The function documentation below
defines the supported overloads and options; unsupported options raise
`ArgumentError`.

# `session`

```elixir
@type session() :: Fluffy.PhoenixTest.Session.t() | Fluffy.Session.t()
```

A facade session, or a native session accepted when entering the facade.

# `assert_has`

```elixir
@spec assert_has(session(), String.t()) :: session()
```

Checks whether any CSS match is visible, or negates that check.
Multiple matches are allowed; refutation requires every match to be hidden or absent.
Static and Live use structural visibility; Playwright uses rendered visibility.
Without a count or field predicate, hidden and absent elements satisfy refutation.
Counts and field predicates do not add a visibility requirement, matching native assertions.

Supports `text:`, `count:`, one-based `at:`, `value:`, `checked:`, `selected:`,
`label:`, `exact:`, and `timeout:`. Text and label matching default to substring
matching. `exact: true` matches the complete normalized text or label and is
case-sensitive. Value comparisons are exact; `selected:` matches a selected
option's complete normalized text. With field predicates, `exact:` applies
only to the optional label.

Only one of `text:`, `value:`, `checked:`, or `selected:` is accepted. Counts
cannot be combined with field predicates or `at:`. Label filtering precedes
`at:`, which precedes text filtering. Value and checked predicates require
one control. `exact:` requires `text:` or `label:`.

The special selector `"title"` accepts `text:`, `exact:`, and `timeout:`.
Text defaults to substring matching; without text it requires a nonempty title.

# `assert_has`

```elixir
@spec assert_has(session(), String.t(), String.t() | keyword()) :: session()
```

# `assert_has`

```elixir
@spec assert_has(session(), String.t(), String.t(), keyword()) :: session()
```

# `assert_path`

```elixir
@spec assert_path(session(), String.t(), keyword()) :: session()
```

Checks a path, optionally with an exact flat `query_params:` map and `timeout:`.
A whole `*` path segment matches one segment, including an empty segment.
Other segments match literally. Query strings are ignored unless
`query_params:` is supplied; fragments are always ignored.

# `check`

```elixir
@spec check(session(), String.t()) :: session()
```

Changes a labeled control's checked state, with optional CSS and label `exact:`.

# `check`

```elixir
@spec check(session(), String.t(), keyword() | String.t()) :: session()
```

# `check`

```elixir
@spec check(session(), String.t() | nil, String.t(), keyword()) :: session()
```

# `choose`

```elixir
@spec choose(session(), String.t()) :: session()
```

Changes a labeled control's checked state, with optional CSS and label `exact:`.

# `choose`

```elixir
@spec choose(session(), String.t(), keyword() | String.t()) :: session()
```

# `choose`

```elixir
@spec choose(session(), String.t() | nil, String.t(), keyword()) :: session()
```

# `click_button`

```elixir
@spec click_button(session(), String.t()) :: session()
```

Clicks a button by accessible name, or by CSS and text or label (optional `exact:`).

# `click_button`

```elixir
@spec click_button(session(), String.t(), String.t()) :: session()
```

# `click_button`

```elixir
@spec click_button(session(), String.t(), String.t(), keyword()) :: session()
```

# `click_link`

```elixir
@spec click_link(session(), String.t()) :: session()
```

Clicks a link by accessible name, or by CSS and text (optional `exact:`).
CSS links fall back to label matching only when no text match exists at the
time of the call. Ambiguous or non-actionable text matches do not trigger fallback.

# `click_link`

```elixir
@spec click_link(session(), String.t(), String.t()) :: session()
```

# `click_link`

```elixir
@spec click_link(session(), String.t(), String.t(), keyword()) :: session()
```

# `fill_in`

```elixir
@spec fill_in(session(), String.t(), keyword()) :: session()
```

Fills a labeled field using a `String.Chars` value in `with:` and optional label `exact:`.

# `fill_in`

```elixir
@spec fill_in(session(), String.t() | nil, String.t(), keyword()) :: session()
```

# `open_browser`

```elixir
@spec open_browser(session()) :: session()
```

Opens the current page using Fluffy's driver-specific browser preview.

# `put_endpoint`

```elixir
@spec put_endpoint(Plug.Conn.t(), module()) :: Plug.Conn.t()
```

Stores the Phoenix endpoint on a prepared connection.

# `refute_has`

```elixir
@spec refute_has(session(), String.t()) :: session()
```

Checks whether any CSS match is visible, or negates that check.
Multiple matches are allowed; refutation requires every match to be hidden or absent.
Static and Live use structural visibility; Playwright uses rendered visibility.
Without a count or field predicate, hidden and absent elements satisfy refutation.
Counts and field predicates do not add a visibility requirement, matching native assertions.

Supports `text:`, `count:`, one-based `at:`, `value:`, `checked:`, `selected:`,
`label:`, `exact:`, and `timeout:`. Text and label matching default to substring
matching. `exact: true` matches the complete normalized text or label and is
case-sensitive. Value comparisons are exact; `selected:` matches a selected
option's complete normalized text. With field predicates, `exact:` applies
only to the optional label.

Only one of `text:`, `value:`, `checked:`, or `selected:` is accepted. Counts
cannot be combined with field predicates or `at:`. Label filtering precedes
`at:`, which precedes text filtering. Value and checked predicates require
one control. `exact:` requires `text:` or `label:`.

The special selector `"title"` accepts `text:`, `exact:`, and `timeout:`.
Text defaults to substring matching; without text it requires a nonempty title.

# `refute_has`

```elixir
@spec refute_has(session(), String.t(), String.t() | keyword()) :: session()
```

# `refute_has`

```elixir
@spec refute_has(session(), String.t(), String.t(), keyword()) :: session()
```

# `refute_path`

```elixir
@spec refute_path(session(), String.t(), keyword()) :: session()
```

Negates the combined path and optional query expectation.

# `reload_page`

```elixir
@spec reload_page(session()) :: session()
```

Reloads the active page using the current driver.

# `select`

```elixir
@spec select(session(), String.Chars.t() | [String.Chars.t()], keyword()) :: session()
```

Selects exact option labels with `option: value_or_list` (or legacy `from: label`).
Each option accepts `String.Chars`. Lists replace the selected set; use `[charlist]`
for a single charlist label. Supports label `exact:`; rejects `exact_option: false`.

# `select`

```elixir
@spec select(
  session(),
  String.t() | nil,
  String.Chars.t() | [String.Chars.t()],
  keyword()
) :: session()
```

# `start_session`

Starts an explicit Fluffy session with the selected backend.

# `start_session`

Starts an explicit Fluffy session with backend options.

# `submit`

```elixir
@spec submit(session()) :: Fluffy.PhoenixTest.Session.t()
```

Submits the form owning the most recently edited field. URL patches retain the
active form; navigation to another document or LiveView clears it.

# `submit`

```elixir
@spec submit(session(), String.t() | Fluffy.Locator.t()) ::
  Fluffy.PhoenixTest.Session.t()
```

Submits an explicit CSS form selector or native form locator.

# `uncheck`

```elixir
@spec uncheck(session(), String.t()) :: session()
```

Changes a labeled control's checked state, with optional CSS and label `exact:`.

# `uncheck`

```elixir
@spec uncheck(session(), String.t(), keyword() | String.t()) :: session()
```

# `uncheck`

```elixir
@spec uncheck(session(), String.t() | nil, String.t(), keyword()) :: session()
```

# `unwrap`

```elixir
@spec unwrap(session(), (term() -&gt; term())) :: session()
```

Runs a native callback with Fluffy's driver-specific unwrap semantics.

# `upload`

```elixir
@spec upload(session(), String.t(), String.t() | [String.t()]) :: session()
```

Selects one or more local files on a labeled input, with optional CSS and label `exact:`.
Accepts a path string or a list of path strings, preserving selection order.
Pass `[]` to clear the selection.

In the four-argument form, a final keyword list (including `[]`) is interpreted
as options. To clear using both CSS and label, use `upload(session, css, label, [], [])`.

# `upload`

```elixir
@spec upload(
  session(),
  String.t(),
  String.t() | [String.t()],
  keyword() | String.t() | [String.t()]
) ::
  session()
```

# `upload`

```elixir
@spec upload(
  session(),
  String.t() | nil,
  String.t(),
  String.t() | [String.t()],
  keyword()
) :: session()
```

# `visit`

```elixir
@spec visit(Plug.Conn.t() | session(), String.t()) :: session()
```

Visits a path. A connection always starts a Phoenix session.
Used connections are recycled automatically; fresh prepared connections are preserved.

# `within`

```elixir
@spec within(session(), String.t(), (Fluffy.PhoenixTest.Session.t() -&gt;
                                 Fluffy.PhoenixTest.Session.t())) ::
  session()
```

Runs a callback with a CSS scope. Return the updated scoped session from the callback.
Nested callbacks restore the outer scope. All operations retain the facade wrapper,
including the last interacted field's form when leaving a scope.

---

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