View Source Pages (Pages v2.2.1)

Entry point for interacting with pages.

Pages are built around Pages.Driver.t/0 structs. Drivers hold state about the current connection, implement @behavior Pages.Driver and must implement the String.Chars protocol to transform themselves into HTML.

Available drivers

Pages.Driver.Conn.t/0 - Given a Plug.Conn.t/0, this driver will be used.
Pages.Driver.LiveView.t/0 - Given a Plug.Conn.t/0 with inner data that appears as if a Phoenix.LiveView is configured, this driver will be used.

Summary

Types

attrs_t()

context_t()

http_method()

live_view_upload()

page_type_t()

result()

In most cases, when interacting with pages, a new page will be returned (either a %Pages.Driver.LiveView{} or a %Pages.Driver.Conn{}). When actions redirect to an external URL, Pages functions will return a tuple with {:error, :external, url}

text_filter()

Functions

clear_connect_params(page)

Clears out any params set via Phoenix.LiveViewTest.put_connect_params/2

click(page, selector)

click(page, title, selector)

click(page, method, title, selector)

Simulates clicking on an element at selector with title title. Set the method param to :post to click on a link that has data-method=post.

handle_redirect(page)

Handles cases where the server issues a redirect to the client without a synchronous interaction from the user. This may be used to handle redirects issued from Phoenix.LiveView.handle_info/2 callbacks, for instance.

new(conn, context \\ %{})

Instantiates a new page.

open_browser(page)

Attempt to open the current page in a web browser.

render_change(page, selector, value)

Render a change to the element at selector with the value value. See Phoenix.LiveViewTest.render_change/2 for a description of the value field.

render_hook(page, event, value_attrs, opts \\ [])

Sends a hook event to the live view.

render_upload(page, upload, entry_name, percent \\ 100)

Performs an upload of a file input and renders the result. See Phoenix.LiveViewTest.file_input/4 for a description of the upload field.

rerender(page)

Re-renders the page.

submit_form(page, selector)

Submits a form without specifying any attributes. This function will submit any values currently set in the form HTML.

submit_form(page, selector, attrs)

Fills in a form with attributes and submits it. Hidden parameters can by send by including a fifth enumerable.

submit_form(page, selector, attrs, hidden_attrs)

submit_form(page, selector, schema, form_attrs, hidden_attrs)

update_form(page, selector, attrs)

update_form(page, selector, schema, attrs)

update_form(page, selector, schema, attrs, opts)

Updates fields in a form with attributes, without submitting the form.

visit(conn, path)

visit(conn, path, context)

Visits path.

with_child_component(page, child_id, fun)

Finds a phoenix component with an id matching child_id, and passes it to the given function. This is helpful when a site implements stateful LiveView components, and messages should be directed to a process other than the parent LiveView pid.

Types

attrs_t()

@type attrs_t() :: Keyword.t() | map()

context_t()

@type context_t() :: %{required(atom()) => any()} | keyword()

http_method()

@type http_method() :: :get | :post

live_view_upload()

@type live_view_upload() :: %Phoenix.LiveViewTest.Upload{
  cid: term(),
  config: term(),
  element: term(),
  entries: term(),
  pid: term(),
  ref: term(),
  selector: term(),
  view: term()
}

page_type_t()

@type page_type_t() :: :live_view

result()

@type result() :: Pages.Driver.t() | {:error, :external, Path.t()}

text_filter()

@type text_filter() :: binary() | Regex.t()

Functions

clear_connect_params(page)

@spec clear_connect_params(Pages.Driver.t()) :: result()

Clears out any params set via Phoenix.LiveViewTest.put_connect_params/2

click(page, selector)

@spec click(Pages.Driver.t(), HtmlQuery.Css.selector()) :: result()

click(page, title, selector)

@spec click(Pages.Driver.t(), http_method(), HtmlQuery.Css.selector()) :: result()

@spec click(Pages.Driver.t(), text_filter(), HtmlQuery.Css.selector()) :: result()

click(page, method, title, selector)

@spec click(Pages.Driver.t(), http_method(), text_filter(), HtmlQuery.Css.selector()) ::
  result()

Simulates clicking on an element at selector with title title. Set the method param to :post to click on a link that has data-method=post.

handle_redirect(page)

@spec handle_redirect(Pages.Driver.t()) :: result()

new(conn, context \\ %{})

@spec new(Plug.Conn.t(), context_t()) :: result()

Instantiates a new page.

open_browser(page)

@spec open_browser(Pages.Driver.t()) :: Pages.Driver.t()

Attempt to open the current page in a web browser.

render_change(page, selector, value)

@spec render_change(Pages.Driver.t(), HtmlQuery.Css.selector(), Enum.t()) :: result()

Render a change to the element at selector with the value value. See Phoenix.LiveViewTest.render_change/2 for a description of the value field.

render_hook(page, event, value_attrs, opts \\ [])

@spec render_hook(Pages.Driver.t(), binary(), attrs_t(), keyword()) :: result()

Sends a hook event to the live view.

Arguments

name	decription
page	The current page struct.
event	The event name to send to `handle_event`.
value_attrs	A map of params to send to `handle_event`.
opts	An optional keyword list of options.

Options

name	description
target	The selector of an embedded live componont to receive the event. Example: `#sub-module`

See Phoenix.LiveViewTest.render_hook/3 for more information.

render_upload(page, upload, entry_name, percent \\ 100)

@spec render_upload(Pages.Driver.t(), live_view_upload(), binary(), integer()) ::
  result()

Performs an upload of a file input and renders the result. See Phoenix.LiveViewTest.file_input/4 for a description of the upload field.

rerender(page)

@spec rerender(Pages.Driver.t()) :: result()

Re-renders the page.

submit_form(page, selector)

@spec submit_form(Pages.Driver.t(), HtmlQuery.Css.selector()) :: result()

Submits a form without specifying any attributes. This function will submit any values currently set in the form HTML.

submit_form(page, selector, attrs)

@spec submit_form(Pages.Driver.t(), HtmlQuery.Css.selector(), attrs :: attrs_t()) ::
  result()

Fills in a form with attributes and submits it. Hidden parameters can by send by including a fifth enumerable.

Arguments

name	decription
page	The current page struct.
selector	A CSS selector matching the form.
schema	An optional atom representing the schema of the form. Attributes will be nested under this key when submitted. See Schema.
attrs	A map of attributes to send.
hidden_attrs	An optional map or keyword of hidden values to include.

Schema

This atom determines the key under which attrs will be nested when sent to the server, and corresponds to the atom which an t:Ecto.Changeset.t/0 serializes to, or the value of :as passed to Phoenix.HTML.FormData.to_form/4.

When a schema is passed, the form attrs will be received as nested params under the schema key.

If one wishes to construct the full nested map of attrs, then the schema may be omitted.

Examples

iex> conn = Phoenix.ConnTest.build_conn()
iex> page = Pages.visit(conn, "/live/form")
iex> Pages.submit_form(page, "#form", :foo, value: "rerender")

iex> conn = Phoenix.ConnTest.build_conn()
iex> page = Pages.visit(conn, "/live/form")
iex> Pages.submit_form(page, "#form", foo: [value: "rerender"])

Notes

When used with LiveView, this will trigger phx-submit with the specified attributes, and handles phx-trigger-action if present.

submit_form(page, selector, attrs, hidden_attrs)

@spec submit_form(
  Pages.Driver.t(),
  HtmlQuery.Css.selector(),
  attrs :: attrs_t(),
  hidden_attrs :: attrs_t()
) :: result()

@spec submit_form(
  Pages.Driver.t(),
  HtmlQuery.Css.selector(),
  schema :: atom(),
  attrs :: attrs_t()
) ::
  result()

submit_form(page, selector, schema, form_attrs, hidden_attrs)

@spec submit_form(
  Pages.Driver.t(),
  HtmlQuery.Css.selector(),
  schema :: atom(),
  attrs :: attrs_t(),
  hidden_attrs :: attrs_t()
) :: result()

update_form(page, selector, attrs)

@spec update_form(Pages.Driver.t(), HtmlQuery.Css.selector(), attrs :: attrs_t()) ::
  result()

update_form(page, selector, schema, attrs)

@spec update_form(
  Pages.Driver.t(),
  HtmlQuery.Css.selector(),
  schema :: atom(),
  attrs :: attrs_t()
) ::
  result()

@spec update_form(
  Pages.Driver.t(),
  HtmlQuery.Css.selector(),
  attrs :: attrs_t(),
  opts :: keyword()
) ::
  result()

update_form(page, selector, schema, attrs, opts)

@spec update_form(
  Pages.Driver.t(),
  HtmlQuery.Css.selector(),
  schema :: atom(),
  attrs :: attrs_t(),
  opts :: keyword()
) :: result()

Updates fields in a form with attributes, without submitting the form.

Arguments

name	decription
page	The current page struct.
selector	A CSS selector matching the form.
schema	An optional atom representing the schema of the form. Attributes will be nested under this key when submitted. See Schema.
attrs	A map of attributes to send.
opts	A keyword list of options.

Options

name	type	description
target	`list(binary())`	A list to be sent in the `_target` of the form params, indicating which field has been changes.

Schema

When a schema is passed, the form attrs will be received as nested params under the schema key.

If one wishes to construct the full nested map of attrs, then the schema may be omitted.

Examples

iex> conn = Phoenix.ConnTest.build_conn()
iex> page = Pages.visit(conn, "/live/form")
iex> Pages.update_form(page, "#form", :my_form, value: "baz")

iex> conn = Phoenix.ConnTest.build_conn()
iex> page = Pages.visit(conn, "/live/form")
iex> Pages.update_form(page, "#form", my_form: [value: "baz"])

Notes

When used with LiveView, this will trigger phx-change with the specified attributes, and handles phx-trigger-action if present.

visit(conn, path)

@spec visit(Pages.Driver.t(), Path.t()) :: result()

@spec visit(Plug.Conn.t(), Path.t()) :: result()

visit(conn, path, context)

@spec visit(Pages.Driver.t(), Path.t(), context_t()) :: result()

@spec visit(Plug.Conn.t(), Path.t(), context_t()) :: result()

Visits path.

with_child_component(page, child_id, fun)

@spec with_child_component(
  Pages.Driver.t(),
  child_id :: binary(),
  (Pages.Driver.t() -> term())
) ::
  Pages.Driver.t()

Examples

Pages.with_child_component(page, "chat-component", fn child ->
  Pages.submit_form(child,
    [test_role: "new-chat-message"],
    :chat_message,
    contents: "Hi there!")
end)