Filament.Test
(filament v0.4.1)
Copy Markdown
Rung 2 test API for Filament components.
Mount a component in isolation, drive it with simulated events, assert on rendered HTML. No WebSocket required.
Example:
import Filament.Test
{:ok, stub} = Filament.Test.Stub.start(fn _ -> %{count: 0} end)
{:ok, view} = mount(Counter, %{server: stub})
assert render_text(view) =~ "Count: 0"
{:ok, view} = click(view, "button")
assert render_text(view) =~ "Count: 1"Summary
Functions
Simulate a blur event on the element matching selector.
Finds the phx-blur attribute, dispatches the handler, flushes state updates,
re-renders. Returns {:ok, updated_view} or {:error, reason}.
Like blur/2 but returns the view directly, raising on error.
Simulate a change event on the element matching selector with params.
Finds the phx-change attribute, dispatches the handler with params,
flushes state updates, re-renders. Returns {:ok, updated_view} or {:error, reason}.
Like change/3 but returns the view directly, raising on error.
Simulate a click on the element matching selector.
Finds the phx-click attribute, dispatches the event handler, flushes resulting
state updates, and re-renders. Returns {:ok, updated_view} or {:error, reason}.
Like click/2 but returns the view directly, raising on error.
Assert that assertion_fn.() returns a truthy value within timeout milliseconds.
Retries every interval ms. Raises ExUnit.AssertionError on timeout.
Return true if the element matching selector has CSS class class_name.
Raises if selector matches no elements.
Simulate a keydown event.
Like key_down/2,3 but returns the view directly, raising on error.
Mount component with props. Returns {:ok, view} or {:error, reason}.
Like mount/3 but returns the view directly.
Return the rendered HTML as a plain string (with HTML tags stripped).
Simulate a form submission on the element matching selector with params.
Finds the phx-submit attribute on the form, dispatches the handler with params,
flushes state updates, re-renders. Returns {:ok, updated_view} or {:error, reason}.
Like submit/3 but returns the view directly, raising on error.
Drain pending filament messages and re-render the view. Useful after pushing to an observable stub from outside the component.
Types
Functions
Simulate a blur event on the element matching selector.
Finds the phx-blur attribute, dispatches the handler, flushes state updates,
re-renders. Returns {:ok, updated_view} or {:error, reason}.
Like blur/2 but returns the view directly, raising on error.
Simulate a change event on the element matching selector with params.
Finds the phx-change attribute, dispatches the handler with params,
flushes state updates, re-renders. Returns {:ok, updated_view} or {:error, reason}.
Like change/3 but returns the view directly, raising on error.
Simulate a click on the element matching selector.
Finds the phx-click attribute, dispatches the event handler, flushes resulting
state updates, and re-renders. Returns {:ok, updated_view} or {:error, reason}.
Like click/2 but returns the view directly, raising on error.
Assert that assertion_fn.() returns a truthy value within timeout milliseconds.
Retries every interval ms. Raises ExUnit.AssertionError on timeout.
The assertion function must be a zero-arity function. For assertions that need
to first call update/1, include that call inside the fn and use the returned
view for the assertion:
Filament.Test.eventually(fn ->
view = Filament.Test.update(view)
render_text(view) =~ "Count: 5"
end, timeout: 500)Return true if the element matching selector has CSS class class_name.
Raises if selector matches no elements.
@spec key_down(t(), String.t(), keyword()) :: {:ok, t()} | {:error, term()}
@spec key_down(t(), String.t(), String.t()) :: {:ok, t()} | {:error, term()}
Simulate a keydown event.
Two forms:
key_down(view, key, opts \\ [])— window-level (on_key). Finds the firstphx-hook="FilamentKey"element and dispatches with modifier opts:ctrl: true,shift: true,alt: true,meta: true.key_down(view, selector, key)— element-scoped (on_keydown). Finds the element matchingselector, dispatches with%{"key" => key}.
Both flush state updates and re-render. Return {:ok, updated_view} or
{:error, reason}.
@spec key_down!(t(), String.t(), keyword()) :: t()
@spec key_down!(t(), String.t(), String.t()) :: t()
Like key_down/2,3 but returns the view directly, raising on error.
@spec mount(component :: module(), props :: map(), opts :: keyword()) :: {:ok, t()} | {:error, term()}
Mount component with props. Returns {:ok, view} or {:error, reason}.
Options:
:stub— list of{server_identity, stub_fn}pairs (seeFilament.Test.Stub). Example:stub: [{CartServer, fn _req -> %{items: []} end}]
Like mount/3 but returns the view directly.
Return the rendered HTML as a plain string (with HTML tags stripped).
Simulate a form submission on the element matching selector with params.
Finds the phx-submit attribute on the form, dispatches the handler with params,
flushes state updates, re-renders. Returns {:ok, updated_view} or {:error, reason}.
Like submit/3 but returns the view directly, raising on error.
Drain pending filament messages and re-render the view. Useful after pushing to an observable stub from outside the component.