Phoenix.LiveViewTest (Phoenix LiveView v0.15.5) View Source

Conveniences for testing Phoenix LiveViews.

In LiveView tests, we interact with views via process communication in substitution of a browser. Like a browser, our test process receives messages about the rendered updates from the view which can be asserted against to test the life-cycle and behavior of LiveViews and their children.

LiveView Testing

The life-cycle of a LiveView as outlined in the Phoenix.LiveView docs details how a view starts as a stateless HTML render in a disconnected socket state. Once the browser receives the HTML, it connects to the server and a new LiveView process is started, remounted in a connected socket state, and the view continues statefully. The LiveView test functions support testing both disconnected and connected mounts separately, for example:

import Plug.Conn
import Phoenix.ConnTest
import Phoenix.LiveViewTest
@endpoint MyEndpoint

test "disconnected and connected mount", %{conn: conn} do
  conn = get(conn, "/my-path")
  assert html_response(conn, 200) =~ "<h1>My Disconnected View</h1>"

  {:ok, view, html} = live(conn)
end

test "redirected mount", %{conn: conn} do
  assert {:error, {:redirect, %{to: "/somewhere"}}} = live(conn, "my-path")
end

Here, we start by using the familiar Phoenix.ConnTest function, get/2 to test the regular HTTP GET request which invokes mount with a disconnected socket. Next, live/1 is called with our sent connection to mount the view in a connected state, which starts our stateful LiveView process.

In general, it's often more convenient to test the mounting of a view in a single step, provided you don't need the result of the stateless HTTP render. This is done with a single call to live/2, which performs the get step for us:

test "connected mount", %{conn: conn} do
  {:ok, _view, html} = live(conn, "/my-path")
  assert html =~ "<h1>My Connected View</h1>"
end

Testing Events

The browser can send a variety of events to a LiveView via phx- bindings, which are sent to the handle_event/3 callback. To test events sent by the browser and assert on the rendered side effect of the event, use the render_* functions:

  • render_click/1 - sends a phx-click event and value, returning the rendered result of the handle_event/3 callback.

  • render_focus/2 - sends a phx-focus event and value, returning the rendered result of the handle_event/3 callback.

  • render_blur/1 - sends a phx-blur event and value, returning the rendered result of the handle_event/3 callback.

  • render_submit/1 - sends a form phx-submit event and value, returning the rendered result of the handle_event/3 callback.

  • render_change/1 - sends a form phx-change event and value, returning the rendered result of the handle_event/3 callback.

  • render_keydown/1 - sends a form phx-keydown event and value, returning the rendered result of the handle_event/3 callback.

  • render_keyup/1 - sends a form phx-keyup event and value, returning the rendered result of the handle_event/3 callback.

  • render_hook/3 - sends a hook event and value, returning the rendered result of the handle_event/3 callback.

For example:

{:ok, view, _html} = live(conn, "/thermo")

assert view
       |> element("button#inc")
       |> render_click() =~ "The temperature is: 31℉"

In the example above, we are looking for a particular element on the page and triggering its phx-click event. LiveView takes care of making sure the element has a phx-click and automatically sends its values to the server.

You can also bypass the element lookup and directly trigger the LiveView event in most functions:

assert render_click(view, :inc, %{}) =~ "The temperature is: 31℉"

The element style is preferred as much as possible, as it helps LiveView perform validations and ensure the events in the HTML actually matches the event names on the server.

Testing regular messages

LiveViews are GenServer's under the hood, and can send and receive messages just like any other server. To test the side effects of sending or receiving messages, simply message the view and use the render function to test the result:

send(view.pid, {:set_temp, 50})
assert render(view) =~ "The temperature is: 50℉"

Testing components

There are two main mechanisms for testing components. To test stateless components or just a regular rendering of a component, one can use render_component/2:

assert render_component(MyComponent, id: 123, user: %User{}) =~
         "some markup in component"

If you want to test how components are mounted by a LiveView and interact with DOM events, you can use the regular live/2 macro to build the LiveView with the component and then scope events by passing the view and a DOM selector in a list:

{:ok, view, html} = live(conn, "/users")
html = view |> element("#user-13 a", "Delete") |> render_click()
refute html =~ "user-13"
refute view |> element("#user-13") |> has_element?()

In the example above, LiveView will lookup for an element with ID=user-13 and retrieve its phx-target. If phx-target points to a component, that will be the component used, otherwise it will fallback to the view.

Link to this section Summary

Functions

Asserts a live patch will happen within timeout.

Asserts a live patch was performed.

Asserts an event will be pushed within timeout.

Asserts a redirect will happen within timeout.

Asserts a redirect was performed.

Asserts a hook reply was returned from a handle_event callback.

Returns an element to scope a function to.

Builds a file input for testing uploads within a form.

Gets the nested LiveView child by child_id from the parent LiveView.

Follows the redirect from a render_* action.

Returns a form element to scope a function to.

Checks if the given element exists on the page.

Checks if the given selector with text_filter is on view.

Spawns a connected LiveView process.

Returns the current list of LiveView children for the parent LiveView.

Spawns a connected LiveView process mounted in isolation as the sole rendered element.

Open the default browser to display current HTML of view_or_element.

Returns the most recent title that was updated via a page_title assign.

Performs a preflight upload request.

Puts connect info to be used on LiveView connections.

Puts connect params to be used on LiveView connections.

Returns the HTML string of the rendered view or element.

Sends a blur event given by element and returns the rendered result.

Sends a blur event to the view and returns the rendered result.

Sends a form change event given by element and returns the rendered result.

Sends a form change event to the view and returns the rendered result.

Sends a click event given by element and returns the rendered result.

Sends a click event to the view with value and returns the rendered result.

Mounts, updates and renders a component.

Sends a focus event given by element and returns the rendered result.

Sends a focus event to the view and returns the rendered result.

Sends a hook event to the view or an element and returns the rendered result.

Sends a keydown event given by element and returns the rendered result.

Sends a keydown event to the view and returns the rendered result.

Sends a keyup event given by element and returns the rendered result.

Sends a keyup event to the view and returns the rendered result.

Simulates a live_patch to the given path and returns the rendered result.

Sends a form submit event given by element and returns the rendered result.

Sends a form submit event to the view and returns the rendered result.

Performs an upload of a file input and renders the result.

Link to this section Functions

Link to this function

assert_patch(view, to, timeout \\ 100)

View Source

Asserts a live patch will happen within timeout.

It always returns :ok. To assert on the flash message, you can assert on the result of the rendered LiveView.

Examples

render_click(view, :event_that_triggers_patch)
assert_patch view, "/path"
Link to this function

assert_patched(view, to)

View Source

Asserts a live patch was performed.

It always returns :ok. To assert on the flash message, you can assert on the result of the rendered LiveView.

Examples

render_click(view, :event_that_triggers_redirect)
assert_patched view, "/path"
Link to this macro

assert_push_event(view, event, payload, timeout \\ 100)

View Source (macro)

Asserts an event will be pushed within timeout.

Examples

assert_push_event view, "scores", %{points: 100, user: "josé"}
Link to this function

assert_redirect(view, to, timeout \\ 100)

View Source

Asserts a redirect will happen within timeout.

It returns the flash messages from said redirect, if any. Note the flash will contain string keys.

Examples

render_click(view, :event_that_triggers_redirect)
flash = assert_redirect view, "/path"
assert flash["info"] == "Welcome"
Link to this function

assert_redirected(view, to)

View Source

Asserts a redirect was performed.

It returns the flash messages from said redirect, if any. Note the flash will contain string keys.

Examples

render_click(view, :event_that_triggers_redirect)
flash = assert_redirected view, "/path"
assert flash["info"] == "Welcome"
Link to this macro

assert_reply(view, payload, timeout \\ 100)

View Source (macro)

Asserts a hook reply was returned from a handle_event callback.

Examples

assert_reply view, %{result: "ok", transaction_id: _}
Link to this function

element(view, selector, text_filter \\ nil)

View Source

Returns an element to scope a function to.

It expects the current LiveView, a query selector, and a text filter.

An optional text filter may be given to filter the results by the query selector. If the text filter is a string or a regex, it will match any element that contains the string or matches the regex. After the text filter is applied, only one element must remain, otherwise an error is raised.

If no text filter is given, then the query selector itself must return a single element.

assert view
      |> element("#term a:first-child()", "Increment")
      |> render() =~ "Increment</a>"
Link to this macro

file_input(view, form_selector, name, entries)

View Source (macro)

Builds a file input for testing uploads within a form.

Given the form DOM selector, the upload name, and a list of maps of client metadata for the upload, the returned file input can be passed to render_upload/2.

Client metadata takes the following form:

  • :last_modified - the last modified timestamp
  • :name - the name of the file
  • :content - the binary content of the file
  • :size - the byte size of the content
  • :type - the MIME type of the file

Examples

avatar = file_input(lv, "#my-form-id", :avatar, [%{
  last_modified: 1_594_171_879_000,
  name: "myfile.jpeg",
  content: File.read!("myfile.jpg"),
  size: 1_396_009,
  type: "image/jpeg"
}])

assert render_upload(avatar, "foo.jpeg") =~ "100%"
Link to this function

find_live_child(parent, child_id)

View Source

Gets the nested LiveView child by child_id from the parent LiveView.

Examples

{:ok, view, _html} = live(conn, "/thermo")
assert clock_view = find_live_child(view, "clock")
assert render_click(clock_view, :snooze) =~ "snoozing"
Link to this macro

follow_redirect(reason, conn, to \\ nil)

View Source (macro)

Follows the redirect from a render_* action.

Imagine you have a LiveView that redirects on a render_click event. You can make it sure it immediately redirects after the render_click action by calling follow_redirect/3:

live_view
|> render_click("redirect")
|> follow_redirect(conn)

follow_redirect/3 expects a connection as second argument. This is the connection that will be used to perform the underlying request.

If the LiveView redirects with a live redirect, this macro returns {:ok, live_view, disconnected_html} with the content of the new LiveView, the same as the live/3 macro. If the LiveView redirects with a regular redirect, this macro returns {:ok, conn} with the rendered redirected page. In any other case, this macro raises.

Finally, note that you can optionally assert on the path you are being redirected to by passing a third argument:

live_view
|> render_click("redirect")
|> follow_redirect(conn, "/redirected/page")
Link to this function

form(view, selector, form_data \\ %{})

View Source

Returns a form element to scope a function to.

It expects the current LiveView, a query selector, and the form data. The query selector must return a single element.

The form data will be validated directly against the form markup and make sure the data you are changing/submitting actually exists, failing otherwise.

Examples

assert view
      |> form("#term", user: %{name: "hello"})
      |> render_submit() =~ "Name updated"

This function is meant to mimic what the user can actually do, so you cannot set hidden input values. However, hidden values can be given when calling render_submit/2 or render_change/2, see their docs for examples.

Checks if the given element exists on the page.

Examples

assert view |> element("#some-element") |> has_element?()
Link to this function

has_element?(view, selector, text_filter \\ nil)

View Source

Checks if the given selector with text_filter is on view.

See element/3 for more information.

Examples

assert has_element?(view, "#some-element")
Link to this macro

live(conn, path \\ nil)

View Source (macro)

Spawns a connected LiveView process.

If a path is given, then a regular get(conn, path) is done and the page is upgraded to a LiveView. If no path is given, it assumes a previously rendered %Plug.Conn{} is given, which will be converted to a LiveView immediately.

Examples

{:ok, view, html} = live(conn, "/path")
assert view.module = MyLive
assert html =~ "the count is 3"

assert {:error, {:redirect, %{to: "/somewhere"}}} = live(conn, "/path")

Returns the current list of LiveView children for the parent LiveView.

Children are returned in the order they appear in the rendered HTML.

Examples

{:ok, view, _html} = live(conn, "/thermo")
assert [clock_view] = live_children(view)
assert render_click(clock_view, :snooze) =~ "snoozing"
Link to this macro

live_isolated(conn, live_view, opts \\ [])

View Source (macro)

Spawns a connected LiveView process mounted in isolation as the sole rendered element.

Useful for testing LiveViews that are not directly routable, such as those built as small components to be re-used in multiple parents. Testing routable LiveViews is still recommended whenever possible since features such as live navigation require routable LiveViews.

Options

  • :session - the session to be given to the LiveView

All other options are forwarded to the LiveView for rendering. Refer to Phoenix.LiveView.Helpers.live_render/3 for a list of supported render options.

Examples

{:ok, view, html} =
  live_isolated(conn, AppWeb.ClockLive, session: %{"tz" => "EST"})

Use put_connect_params/2 to put connect params for a call to Phoenix.LiveView.get_connect_params/1 in Phoenix.LiveView.mount/3:

{:ok, view, html} =
  conn
  |> put_connect_params(%{"param" => "value"})
  |> live_isolated(AppWeb.ClockLive, session: %{"tz" => "EST"})
Link to this function

open_browser(view_or_element, open_fun \\ &open_with_system_cmd/1)

View Source

Open the default browser to display current HTML of view_or_element.

Examples

view
|> element("#term a:first-child()", "Increment")
|> open_browser()

assert view
       |> form("#term", user: %{name: "hello"})
       |> open_browser()
       |> render_submit() =~ "Name updated"

Returns the most recent title that was updated via a page_title assign.

Examples

render_click(view, :event_that_triggers_page_title_update)
assert page_title(view) =~ "my title"
Link to this function

preflight_upload(upload)

View Source

Performs a preflight upload request.

Useful for testing external uploaders to retrieve the :external entry metadata.

Examples

avatar = file_input(lv, "#my-form-id", :avatar, [%{name: ..., ...}, ...])
assert {:ok, %{ref: _ref, config: %{chunk_size: _}}} = preflight_upload(avatar)
Link to this function

put_connect_info(conn, params)

View Source

Puts connect info to be used on LiveView connections.

See Phoenix.LiveView.get_connect_info/1.

Link to this function

put_connect_params(conn, params)

View Source

Puts connect params to be used on LiveView connections.

See Phoenix.LiveView.get_connect_params/1.

Returns the HTML string of the rendered view or element.

If a view is provided, the entire LiveView is rendered. If an element is provided, only that element is rendered.

Examples

{:ok, view, _html} = live(conn, "/thermo")
assert render(view) =~ ~s|<button id="alarm">Snooze</div>|

assert view
       |> element("#alarm")
       |> render() == "Snooze"
Link to this function

render_blur(element, value \\ %{})

View Source

Sends a blur event given by element and returns the rendered result.

The element is created with element/3 and must point to a single element on the page with a phx-blur attribute in it. The event name given set on phx-blur is then sent to the appropriate LiveView (or component if phx-target is set accordingly). All phx-value-* entries in the element are sent as values. Extra values can be given with the value argument.

It returns the contents of the whole LiveView or an {:error, redirect} tuple.

Examples

{:ok, view, html} = live(conn, "/thermo")

assert view
       |> element("#inactive")
       |> render_blur() =~ "Tap to wake"
Link to this function

render_blur(view, event, value)

View Source

Sends a blur event to the view and returns the rendered result.

It returns the contents of the whole LiveView or an {:error, redirect} tuple.

Examples

{:ok, view, html} = live(conn, "/thermo")
assert html =~ "The temp is: 30℉"
assert render_blur(view, :inactive) =~ "Tap to wake"
Link to this function

render_change(element, value \\ %{})

View Source

Sends a form change event given by element and returns the rendered result.

The element is created with element/3 and must point to a single element on the page with a phx-change attribute in it. The event name given set on phx-change is then sent to the appropriate LiveView (or component if phx-target is set accordingly). All phx-value-* entries in the element are sent as values.

If you need to pass any extra values or metadata, such as the "_target" parameter, you can do so by giving a map under the value argument.

It returns the contents of the whole LiveView or an {:error, redirect} tuple.

Examples

{:ok, view, html} = live(conn, "/thermo")

assert view
       |> element("form")
       |> render_change(%{deg: 123}) =~ "123 exceeds limits"

# Passing metadata
{:ok, view, html} = live(conn, "/thermo")

assert view
       |> element("form")
       |> render_change(%{_target: ["deg"], deg: 123}) =~ "123 exceeds limits"

As with render_submit/2, hidden input field values can be provided like so:

refute view
      |> form("#term", user: %{name: "hello"})
      |> render_change(%{user: %{"hidden_field" => "example"}}) =~ "can't be blank"
Link to this function

render_change(view, event, value)

View Source

Sends a form change event to the view and returns the rendered result.

It returns the contents of the whole LiveView or an {:error, redirect} tuple.

Examples

{:ok, view, html} = live(conn, "/thermo")
assert html =~ "The temp is: 30℉"
assert render_change(view, :validate, %{deg: 123}) =~ "123 exceeds limits"
Link to this function

render_click(element, value \\ %{})

View Source

Sends a click event given by element and returns the rendered result.

The element is created with element/3 and must point to a single element on the page with a phx-click attribute in it. The event name given set on phx-click is then sent to the appropriate LiveView (or component if phx-target is set accordingly). All phx-value-* entries in the element are sent as values. Extra values can be given with the value argument.

If the element is does not have a phx-click attribute but it is a link (the <a> tag), the link will be followed accordingly:

  • if the link is a live_patch, the current view will be patched
  • if the link is a live_redirect, this function will return {:error, {:live_redirect, %{to: url}}}, which can be followed with follow_redirect/2
  • if the link is a regular link, this function will return {:error, {:redirect, %{to: url}}}, which can be followed with follow_redirect/2

It returns the contents of the whole LiveView or an {:error, redirect} tuple.

Examples

{:ok, view, html} = live(conn, "/thermo")

assert view
       |> element("buttons", "Increment")
       |> render_click() =~ "The temperature is: 30℉"
Link to this function

render_click(view, event, value)

View Source

Sends a click event to the view with value and returns the rendered result.

It returns the contents of the whole LiveView or an {:error, redirect} tuple.

Examples

{:ok, view, html} = live(conn, "/thermo")
assert html =~ "The temperature is: 30℉"
assert render_click(view, :inc) =~ "The temperature is: 31℉"
Link to this macro

render_component(component, assigns, opts \\ [])

View Source (macro)

Mounts, updates and renders a component.

If the component uses the @myself assigns, then an id must be given to it is marked as stateful.

Examples

assert render_component(MyComponent, id: 123, user: %User{}) =~
         "some markup in component"

assert render_component(MyComponent, %{id: 123, user: %User{}}, router: SomeRouter) =~
         "some markup in component"
Link to this function

render_focus(element, value \\ %{})

View Source

Sends a focus event given by element and returns the rendered result.

The element is created with element/3 and must point to a single element on the page with a phx-focus attribute in it. The event name given set on phx-focus is then sent to the appropriate LiveView (or component if phx-target is set accordingly). All phx-value-* entries in the element are sent as values. Extra values can be given with the value argument.

It returns the contents of the whole LiveView or an {:error, redirect} tuple.

Examples

{:ok, view, html} = live(conn, "/thermo")

assert view
       |> element("#inactive")
       |> render_focus() =~ "Tap to wake"
Link to this function

render_focus(view, event, value)

View Source

Sends a focus event to the view and returns the rendered result.

It returns the contents of the whole LiveView or an {:error, redirect} tuple.

Examples

{:ok, view, html} = live(conn, "/thermo")
assert html =~ "The temp is: 30℉"
assert render_focus(view, :inactive) =~ "Tap to wake"
Link to this function

render_hook(view_or_element, event, value \\ %{})

View Source

Sends a hook event to the view or an element and returns the rendered result.

It returns the contents of the whole LiveView or an {:error, redirect} tuple.

Examples

{:ok, view, html} = live(conn, "/thermo")
assert html =~ "The temp is: 30℉"
assert render_hook(view, :refresh, %{deg: 32}) =~ "The temp is: 32℉"

If you are pushing events from a hook to a component, then you must pass an element, created with element/3, as first argument and it must point to a single element on the page with a phx-target attribute in it:

{:ok, view, _html} = live(conn, "/thermo")
assert view
       |> element("#thermo-component")
       |> render_hook(:refresh, %{deg: 32}) =~ "The temp is: 32℉"
Link to this function

render_keydown(element, value \\ %{})

View Source

Sends a keydown event given by element and returns the rendered result.

The element is created with element/3 and must point to a single element on the page with a phx-keydown or phx-window-keydown attribute in it. The event name given set on phx-keydown is then sent to the appropriate LiveView (or component if phx-target is set accordingly). All phx-value-* entries in the element are sent as values. Extra values can be given with the value argument.

It returns the contents of the whole LiveView or an {:error, redirect} tuple.

Examples

{:ok, view, html} = live(conn, "/thermo")
assert html =~ "The temp is: 30℉"
assert view |> element("#inc") |> render_keydown() =~ "The temp is: 31℉"
Link to this function

render_keydown(view, event, value)

View Source

Sends a keydown event to the view and returns the rendered result.

It returns the contents of the whole LiveView or an {:error, redirect} tuple.

Examples

{:ok, view, html} = live(conn, "/thermo")
assert html =~ "The temp is: 30℉"
assert render_keydown(view, :inc) =~ "The temp is: 31℉"
Link to this function

render_keyup(element, value \\ %{})

View Source

Sends a keyup event given by element and returns the rendered result.

The element is created with element/3 and must point to a single element on the page with a phx-keyup or phx-window-keyup attribute in it. The event name given set on phx-keyup is then sent to the appropriate LiveView (or component if phx-target is set accordingly). All phx-value-* entries in the element are sent as values. Extra values can be given with the value argument.

It returns the contents of the whole LiveView or an {:error, redirect} tuple.

Examples

{:ok, view, html} = live(conn, "/thermo")
assert html =~ "The temp is: 30℉"
assert view |> element("#inc") |> render_keyup() =~ "The temp is: 31℉"
Link to this function

render_keyup(view, event, value)

View Source

Sends a keyup event to the view and returns the rendered result.

It returns the contents of the whole LiveView or an {:error, redirect} tuple.

Examples

{:ok, view, html} = live(conn, "/thermo")
assert html =~ "The temp is: 30℉"
assert render_keyup(view, :inc) =~ "The temp is: 31℉"
Link to this function

render_patch(view, path)

View Source

Simulates a live_patch to the given path and returns the rendered result.

Link to this function

render_submit(element, value \\ %{})

View Source

Sends a form submit event given by element and returns the rendered result.

The element is created with element/3 and must point to a single element on the page with a phx-submit attribute in it. The event name given set on phx-submit is then sent to the appropriate LiveView (or component if phx-target is set accordingly). All phx-value-* entries in the element are sent as values. Extra values, including hidden input fields, can be given with the value argument.

It returns the contents of the whole LiveView or an {:error, redirect} tuple.

Examples

{:ok, view, html} = live(conn, "/thermo")

assert view
       |> element("form")
       |> render_submit(%{deg: 123, avatar: upload}) =~ "123 exceeds limits"

To submit a form along with some with hidden input values:

assert view
      |> form("#term", user: %{name: "hello"})
      |> render_submit(%{user: %{"hidden_field" => "example"}}) =~ "Name updated"
Link to this function

render_submit(view, event, value)

View Source

Sends a form submit event to the view and returns the rendered result.

It returns the contents of the whole LiveView or an {:error, redirect} tuple.

Examples

{:ok, view, html} = live(conn, "/thermo")
assert html =~ "The temp is: 30℉"
assert render_submit(view, :refresh, %{deg: 32}) =~ "The temp is: 32℉"
Link to this function

render_upload(upload, entry_name, percent \\ 100)

View Source

Performs an upload of a file input and renders the result.

See file_input/4 for details on building a file input.

Examples

Given the following LiveView template:

<%= for entry <- @uploads.avatar.entries %>
    <%=entry.name %>: <%= entry.progress %>%
<% end %>

Your test case can assert the uploaded content:

avatar = file_input(lv, "#my-form-id", :avatar, [
  %{
    last_modified: 1_594_171_879_000,
    name: "myfile.jpeg",
    content: File.read!("myfile.jpg"),
    size: 1_396_009,
    type: "image/jpeg"
  }
])

assert render_upload(avatar, "foo.jpeg") =~ "100%"

By default, the entire file is chunked to the server, but an optional percentage to chunk can be passed to test chunk-by-chunk uploads:

assert render_upload(avatar, "foo.jpeg", 49) =~ "49%"
assert render_upload(avatar, "foo.jpeg", 51) =~ "100%"