Fluffy.PhoenixTest (Fluffy v0.7.0)

Copy Markdown View Source

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

Summary

Types

session()

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

Functions

assert_has(session, selector)

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.

assert_has(session, selector, options)
assert_has(session, selector, text, options)
assert_path(session, path, options \\ [])

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(session, label)

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

check(session, label, options)
check(session, selector, label, options)
choose(session, label)

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

choose(session, label, options)
choose(session, selector, label, options)
click_button(session, text)

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

click_button(session, selector, text)
click_button(session, selector, text, options)
click_link(session, text)

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(session, selector, text)
click_link(session, selector, text, options)
fill_in(session, label, options)

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

fill_in(session, selector, label, options)
open_browser(session)

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

put_endpoint(conn, endpoint)

Stores the Phoenix endpoint on a prepared connection.

refute_has(session, selector)

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.

refute_has(session, selector, options)
refute_has(session, selector, text, options)
refute_path(session, path, options \\ [])

Negates the combined path and optional query expectation.

reload_page(session)

Reloads the active page using the current driver.

select(session, label, options)

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(session, selector, label_or_option, options)
start_session(backend)

Starts an explicit Fluffy session with the selected backend.

start_session(backend, options)

Starts an explicit Fluffy session with backend options.

submit(session)

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

submit(session, selector)

Submits an explicit CSS form selector or native form locator.

uncheck(session, label)

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

uncheck(session, label, options)
uncheck(session, selector, label, options)
unwrap(session, fun)

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

upload(session, label, paths)

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.

upload(session, label_or_selector, paths_or_label, options_or_paths)
upload(session, selector, label, paths, options)
visit(conn, path)

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

within(session, selector, fun)

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.

Types

session()

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

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

Functions

assert_has(session, selector)

@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(session, selector, options)

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

assert_has(session, selector, text, options)

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

assert_path(session, path, options \\ [])

@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(session, label)

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

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

check(session, label, options)

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

check(session, selector, label, options)

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

choose(session, label)

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

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

choose(session, label, options)

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

choose(session, selector, label, options)

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

click_button(session, text)

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

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

click_button(session, selector, text)

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

click_button(session, selector, text, options)

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

click_link(session, text)

@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(session, selector, text)

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

click_link(session, selector, text, options)

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

fill_in(session, label, options)

@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(session, selector, label, options)

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

open_browser(session)

@spec open_browser(session()) :: session()

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

put_endpoint(conn, endpoint)

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

Stores the Phoenix endpoint on a prepared connection.

refute_has(session, selector)

@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(session, selector, options)

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

refute_has(session, selector, text, options)

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

refute_path(session, path, options \\ [])

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

Negates the combined path and optional query expectation.

reload_page(session)

@spec reload_page(session()) :: session()

Reloads the active page using the current driver.

select(session, label, options)

@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(session, selector, label_or_option, options)

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

start_session(backend)

Starts an explicit Fluffy session with the selected backend.

start_session(backend, options)

Starts an explicit Fluffy session with backend options.

submit(session)

@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(session, selector)

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

Submits an explicit CSS form selector or native form locator.

uncheck(session, label)

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

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

uncheck(session, label, options)

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

uncheck(session, selector, label, options)

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

unwrap(session, fun)

@spec unwrap(session(), (term() -> term())) :: session()

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

upload(session, label, paths)

@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(session, label_or_selector, paths_or_label, options_or_paths)

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

upload(session, selector, label, paths, options)

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

visit(conn, path)

@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(session, selector, fun)

@spec within(session(), String.t(), (Fluffy.PhoenixTest.Session.t() ->
                                 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.