Assert helper to ensure an element with given CSS selector 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.

If you want to specify the content of the element, use assert_has/3.

Examples

# assert there's an h1
assert_has(session, "h1")

# assert there's an element with ID "user"
assert_has(session, "#user")

Assert helper to ensure an element with given CSS selector and options.

It'll raise an error if no elements are found, but it will not raise if more than one matching element is found.

Options

• text: the text filter to look for.

• exact: by default assert_has/3 will perform a substring match (e.g. a =~ b). That makes it easier to assert text within HTML elements that also contain other HTML elements. But sometimes we want to assert the exact text is present. For that, use exact: true. (defaults to false)

• count: the number of items you expect to match CSS selector (and text if provided)

• at: the element to be asserted against

Examples

# assert there's an element with ID "user" and text "Aragorn"
assert_has(session, "#user", text: "Aragorn")
  # ^ succeeds if text found is "Aragorn" or "Aragorn, Son of Arathorn"

# assert there's an element with ID "user" and text "Aragorn"
assert_has(session, "#user", text: "Aragorn", exact: true)
  # ^ succeeds only if text found is "Aragorn". Fails if finds "Aragorn, Son of Arathorn"

# assert there are two elements with class "posts"
assert_has(session, ".posts", count: 2)

# assert there are two elements with class "posts" and text "Hello"
assert_has(session, ".posts", text: "Hello", count: 2)

# assert the second element in the list of ".posts" has text "Hello"
assert_has(session, ".posts", at: 2, text: "Hello")

Assert helper to verify current request path. Takes an optional query_params map.

Note on Live Patch Implementation

Capturing the current path in live patches relies on message passing and could, therefore, be subject to intermittent failures. Please open an issue if you see intermittent failures when using assert_path with live patches so we can improve the implementation.

Examples

# assert we're at /users
conn
|> visit("/users")
|> assert_path("/users")

# assert we're at /users?name=frodo
conn
|> visit("/users")
|> assert_path("/users", query_params: %{name: "frodo"})

Same as assert_path/2 but takes an optional query_params map.

Check a checkbox.

If the form is a LiveView form, and if the form has a phx-change attribute defined, check/2 will trigger the phx-change event.

This can be followed by a click_button/3 or submit/1 to submit the form.

Example

Given we have a form that contains this:

<input type="hidden" name="admin" value="off" />
<label for="admin">Admin</label>
<input id="admin" type="checkbox" name="admin" value="on" />

We can check the "Admin" option:

session
|> check("Admin")

Choose a radio button option.

If the form is a LiveView form, and if the form has a phx-change attribute defined, choose/3 will trigger the phx-change event.

This can be followed by a click_button/3 or submit/1 to submit the form.

Example

Given we have a form that contains this:

<input type="radio" id="email" name="contact" value="email" />
<label for="email">Email</label>
<input type="radio" id="phone" name="contact" value="phone" />
<label for="phone">Phone</label>
<input type="radio" id="mail" name="contact" value="mail" checked />
<label for="mail">Mail</label>

We can choose to be contacted by email:

session
|> choose("Email")

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_in/3, select/3, etc.

This function can be preceded by filling out a form.

Example

session
|> fill_in("Name", name: "Aragorn")
|> check("Human")
|> click_button("Create")

Submitting default data

By default, using click_button/2 will submit the form it's part of (so long as it has a phx-click, data-* attrs, or an action).

It will also include any hidden inputs and default data (e.g. inputs with a value set and the button's name and value if present).

Example

<form method="post" action="/users/2">
  <input type="hidden" name="admin" value="true"/>
  <button name="complete" value="true">Complete</button>
</form>

session
|> click_button("Complete")
# ^ includes `%{"admin" => "true", "complete" => "true"}` in payload

Single-button forms

click_button/2 is smart enough to use a hidden input's value with name=_method as the method to send (e.g. when we want to send delete, put, or patch)

That means, it is helpful to submit single-button forms.

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

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 text inputs and textareas, targetting the elements by their labels.

If the form is a LiveView form, and if the form has a phx-change attribute defined, fill_in/3 will trigger the phx-change event.

This can be followed by a click_button/3 or submit/1 to submit the form.

Examples

Given we have a form that contains this:

<label for="name">Name</label>
<input id="name" name="name"/>

or this:

<label>
  Name
  <input name="name"/>
</label>

We can fill in the name field:

session
|> fill_in("Name", with: "Aragorn")

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/2 helper. Verifies that element with given CSS selector is not present.

It'll raise an error if any elements that match selector are found.

If you want to specify the content of the element, use refute_has/3.

Example

# refute there's an h1
refute_has(session, "h1")

# refute there's an element with ID "user"
refute_has(session, "#user")

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

Options

• text: the text filter to look for.

• exact: by default refute_has/3 will perform a substring match (e.g. a =~ b). That makes it easier to refute text within HTML elements that also contain other HTML elements. But sometimes we want to refute the exact text is absent. For that, use exact: true.

• count: the number of items you're expecting should not match the CSS selector (and text if provided)

• at: the element to be refuted against

Examples

# refute there's an element with ID "user" and text "Aragorn"
refute_has(session, "#user", text: "Aragorn")

# refute there's an element with ID "user" and exact text "Aragorn"
refute_has(session, "#user", text: "Aragorn", exact: true)

# refute there are two elements with class "posts" (less or more will not raise)
refute_has(session, ".posts", count: 2)

# refute there are two elements with class "posts" and text "Hello"
refute_has(session, ".posts", text: "Hello", count: 2)

# refute the second element with class "posts" has text "Hello"
refute_has(session, ".posts", at: 2, text: "Hello")

Verifies current request path is NOT the one provided. Takes an optional query_params map for more specificity.

Note on Live Patch Implementation

Capturing the current path in live patches relies on message passing and could, therefore, be subject to intermittent failures. Please open an issue if you see intermittent failures when using refute_path with live patches so we can improve the implementation.

Examples

# refute we're at /posts
conn
|> visit("/users")
|> refute_path("/posts")

# refute we're at /users?name=frodo
conn
|> visit("/users?name=aragorn")
|> refute_path("/users", query_params: %{name: "frodo"})

Same as refute_path/2 but takes an optional query_params for more specific refutation.

Selects an option from a select dropdown.

If the form is a LiveView form, and if the form has a phx-change attribute defined, select/3 will trigger the phx-change event.

This can be followed by a click_button/3 or submit/1 to submit the form.

Examples

Given we have a form that contains this:

<label for="race">Race</label>
<select id="race" name="race">
  <option value="human">Human</option>
  <option value="elf">Elf</option>
  <option value="dwarf">Dwarf</option>
  <option value="orc">Orc</option>
</select>

We can select an option:

session
|> select("Human", from: "Race")

Helper to submit a pre-filled form without clicking a button (see fill_in/3, select/3, choose/2, etc. for how to fill a form.)

Forms are typically submitted by clicking buttons. But sometimes we want to emulate what happens when we submit a form hitting <Enter>. That's what this helper does.

If the form is a LiveView form, and if the form has a phx-submit attribute defined, submit/1 will trigger the phx-submit event. Otherwise, it'll submit the form regularly.

If the form has a submit button with a name and value, submit/1 will also include that data in the payload.

Example

session
|> fill_in("Name", with: "Aragorn")
|> select("Human", from: "Race")
|> choose("Email")
|> submit()

Uncheck a checkbox.

If the form is a LiveView form, and if the form has a phx-change attribute defined, uncheck/2 will trigger the phx-change event.

This can be followed by a click_button/3 or submit/1 to submit the form.

Example

Given we have a form that contains this:

<input type="hidden" name="admin" value="off" />
<label for="admin">Admin</label>
<input id="admin" type="checkbox" name="admin" value="on" />

We can uncheck the "Admin" option:

session
|> uncheck("Admin")

Note that unchecking a checkbox in HTML doesn't actually send any data to the server. That's why we have to have a hidden input with the default value (in the example above: admin="off").

Escape hatch to give users access to underlying "native" data structure.

Once the unwrapped actions are performed, PhoenixTest will handle redirects (if any).

• In LiveView tests, unwrap/2 will pass the view that comes from Phoenix.LiveViewTest live/2. Your action must return the result of a render_* LiveViewTest action.

• In non-LiveView tests, unwrap/2 will pass the conn struct. And your action must return a conn struct.

Examples

# in a LiveView
session
|> unwrap(fn view ->
  view
  |> LiveViewTest.element("#hook")
  |> LiveViewTest.render_hook(:hook_event, %{name: "Legolas"})
end)

# in a non-LiveView
session
|> unwrap(fn conn ->
  conn
  |> Phoenix.ConnTest.recycle()
end)

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.

Helpers to scope filling out form within a given selector. Use this if you have more than one form on a page with similar labels.

Examples

Given we have some HTML like this:

<form id="user-form" action="/users" method="post">
  <label for="name">Name</label>
  <input id="name" name="name"/>

  <input type="hidden" name="admin" value="off" />
  <label for="admin">Admin</label>
  <input id="admin" type="checkbox" name="admin" value="on" />
</form>

# and assume another form with "Name" and "Admin" labels

We can fill the form like this:

session
|> within("#user-form", fn session ->
  session
  |> fill_in("Name", with: "Aragorn")
  |> check("Admin")
end)