View Source PhoenixTest (PhoenixTest v0.2.8)
PhoenixTest provides a unified way of writing feature tests -- regardless of whether you're testing LiveView pages or static pages.
It also handles navigation between LiveView and static pages seamlessly. So, you don't have to worry about what type of page you're visiting. Just write the tests from the user's perspective.
Thus, you can test a flow going from static to LiveView pages and back without having to worry about the underlying implementation.
This is a sample flow:
test "admin can create a user", %{conn: conn} do
conn
|> visit("/")
|> click_link("Users")
|> fill_form("#user-form", name: "Aragorn", email: "aragorn@dunedan.com")
|> click_button("Create")
|> assert_has(".user", "Aragorn")
end
Note that PhoenixTest does not handle JavaScript. If you're looking for something that supports JavaScript, take a look at Wallaby.
Summary
Functions
Assert helper to ensure an element with given CSS selector and text
is
present.
Perfoms action defined by button (and based on attributes present).
Performs action defined by button with CSS selector.
Clicks a link with given text and performs the action.
Clicks a link with given CSS selector and text and performs the action. selector to target the link.
Fills form data, validating that input fields are present.
Open the default browser to display current HTML of session
.
Opposite of assert_has/3
helper. Verifies that element with
given CSS selector and text
is not present.
Submits form in the same way one would do by pressing <Enter>
.
Entrypoint to create a session.
Functions
Assert helper to ensure an element with given CSS selector and text
is
present.
It'll raise an error if no elements are found, but it will not raise if more than one matching element is found.
Perfoms action defined by button (and based on attributes present).
This can be used in a number of ways.
Button with phx-click
If the button has a phx-click
on it, it'll send the event to the LiveView.
Example
<button phx-click="save">Save</button>
session
|> click_button("Save") # <- will send "save" event to LiveView
Button relying on Phoenix.HTML.js
If the button acts as a form via Phoenix.HTML's data-method
, data-to
, and
data-csrf
, this will emulate Phoenix.HTML.js and submit the form via data
attributes.
But note that this doesn't guarantee the JavaScript that handles form
submissions via data
attributes is loaded. The test emulates the behavior
but you must make sure the JavaScript is loaded.
For more on that, see https://hexdocs.pm/phoenix_html/Phoenix.HTML.html#module-javascript-library
Example
<button data-method="delete" data-to="/users/2" data-csrf="token">Delete</button>
session
|> click_button("Delete") # <- will submit form like Phoenix.HTML.js does
Combined with fill_form/3
This function can be preceded by fill_form
to fill out a form and
subsequently submit the form.
Note that fill_form/3
+ click_button/2
works for both static and live
pages.
Example
session
|> fill_form("#user-form", name: "Aragorn")
|> click_button("Create")
Single-button form
If click_button/2
is used alone (without phx-click
, data-*
attrs, or
fill_form/3
), it is assumed it is a form with a single button (e.g.
"Delete").
Example
<form method="post" action="/users/2">
<input type="hidden" name="_method" value="delete" />
<button>Delete</button>
</form>
session
|> click_button("Delete") # <- Triggers full form delete
Performs action defined by button with CSS selector.
See click_button/2
for more details.
Clicks a link with given text and performs the action.
Here's how it handles different types of a
tags:
- With
href
: follows it to the next page - With
phx-click
: it'll send the event to the appropriate LiveView - With live redirect: it'll follow the live navigation to the next LiveView
- With live patch: it'll patch the current LiveView
Examples
<.link href="/page/2">Page 2</.link>
<.link phx-click="next-page">Next Page</.link>
<.link navigate="next-liveview">Next LiveView</.link>
<.link patch="page/details">Page Details</.link>
session
|> click_link("Page 2") # <- follows to next page
session
|> click_link("Next Page") # <- sends "next-page" event to LiveView
session
|> click_link("Next LiveView") # <- follows to next LiveView
session
|> click_link("Page Details") # <- applies live patch
Submitting forms
Phoenix allows for submitting forms on links via Phoenix.HTML's data-method
,
data-to
, and data-csrf
.
We can use click_link
to emulate Phoenix.HTML.js and submit the
form via data attributes.
But note that this doesn't guarantee the JavaScript that handles form
submissions via data
attributes is loaded. The test emulates the behavior
but you must make sure the JavaScript is loaded.
For more on that, see https://hexdocs.pm/phoenix_html/Phoenix.HTML.html#module-javascript-library
Example
<a href="/users/2" data-method="delete" data-to="/users/2" data-csrf="token">
Delete
</a>
session
|> click_link("Delete") # <- will submit form like Phoenix.HTML.js does
Clicks a link with given CSS selector and text and performs the action. selector to target the link.
See click_link/2
for more details.
Fills form data, validating that input fields are present.
This can be used by both static and live pages.
If the form is a LiveView form, and if the form has a phx-change
attribute
defined, fill_form/3
will trigger the phx-change
event.
This can be followed by a click_button/3
to submit the form.
Examples
session
|> fill_form("#user-form", name: "Aragorn")
|> click_button("Create")
If your form has nested data -- for example, with an input such as <input name="user[email]">
-- you can pass a nested map as the last argument:
session
|> fill_form("#user-form", user: %{email: "aragorn@dunedain.com"})
|> click_button("Create")
Open the default browser to display current HTML of session
.
Examples
session
|> visit("/")
|> open_browser()
|> submit_form("#user-form", name: "Aragorn")
Opposite of assert_has/3
helper. Verifies that element with
given CSS selector and text
is not present.
It'll raise an error if any elements that match selector and text are found.
Submits form in the same way one would do by pressing <Enter>
.
Note that this does not validate presence of the submit button.
In the case of LiveView forms, it'll submit the form with LiveView's
phx-submit
event.
If it's a static form, this is equivalent to filling the form and submitting
it with the form's method
and to the form's action
.
Note: if your form has a submit button, it's recommended you test with
fill_form/3
+ click_button/2
instead.
Examples
session
|> submit_form("#user-form", name: "Aragorn")
If your form has nested data -- for example, with an input such as <input name="user[email]">
-- you can pass a nested map as the last argument:
session
|> submit_form("#user-form", user: %{email: "aragorn@dunedain.com"})
Entrypoint to create a session.
visit/2
takes a Plug.Conn
struct and the path to visit.
It returns a session
which the rest of the PhoenixTest
functions can use.
Note that visit/2
is smart enough to know if the page you're visiting is a
LiveView or a static view. You don't need to worry about which type of page
you're visiting.