@spec blur(Mirage.Session.t(), String.t(), String.t() | keyword()) ::
  Mirage.Session.t()

Trigger a blur event on an element.

Accepts the same options as Mirage.click/3.

@spec check(Mirage.Session.t(), String.t(), keyword()) :: Mirage.Session.t()

Checks a checkbox by its associated label text.

Triggers the input's $change as well as its form's $change event (if it has one).

Matches exactly by default; pass exact: false to match substrings. Raises if no matching radio button is found, or if more than one matches.

@spec choose(Mirage.Session.t(), String.t(), keyword()) :: Mirage.Session.t()

Selects a radio button by its associated label.

Triggers the input's $change event as well as its form's $change event (if there is one).

Labels may wrap the input or reference it via a for/id pair.

Matches exactly by default; pass exact: false to match substrings. Raises if no matching radio button is found, or if more than one matches.

Example

Profile
|> visit()
|> choose("robot")
|> assert_has("p", "Your gender is 'robot'")

@spec click(Mirage.Session.t(), String.t(), String.t() | keyword()) ::
  Mirage.Session.t()

Trigger a $click event on the element matching the given CSS selector.

Any actions or commands will be run. If the click triggers a page navigation, the new page will be loaded into the session. When clicking a submit button that belongs to a form, that form's $submit event will be triggered.

Raises if no matching element with a $click handler is found, or if more than one matches.

Examples

SignUpPage
|> visit()
|> fill_in("Name", with: "Bender")
|> fill_in("Password", with: "killallhumans")
|> click("button", "Submit")
|> assert_page(WelcomePage)

HomePage
|> visit()
|> click("button", "Log out")

Options

• :text - Match on the element's inner text.
• :exact - Set to false to match on a substring of an element's text. Default is true meaning you must provide an exact match.

@spec click_button(Mirage.Session.t(), String.t(), keyword(any())) ::
  Mirage.Session.t()

Click on a button by its text.

If it's a submit button belonging to a form, it will trigger that form's $submit event.

This is otherwise shorthand for Mirage.click/3 with "button" as its selector.

@spec click_link(Mirage.Session.t(), String.t(), keyword(any())) :: Mirage.Session.t()

Click on a link by its text.

This is simply a shorthand for Mirage.click/3 with "a" as its selector.

@spec fill_in(Mirage.Session.t(), String.t(), keyword()) :: Mirage.Session.t()

Fill in an input or textarea by its label.

Finds an input by its associated label and triggers the input's $change and as well as its form's $change event (if it has one).

Labels may be associated with their input either by wrapping the input (<label>Name <input/></label>) or via a for attribute matching the input's id.

Matches exactly by default; pass exact: false to match substrings. Raises if no matching label is found, or if more than one matches.

@spec focus(Mirage.Session.t(), String.t(), String.t() | keyword()) ::
  Mirage.Session.t()

Trigger a focus event on an element.

Accepts the same options as Mirage.click/3.

@spec mount(function(), {module(), keyword()} | [{module(), keyword()}]) ::
  Mirage.Session.t()

Mount a component in isolation.

Pass a ~HOLO template containing a single component. Props, cid, and slot content are all declared in the markup itself:

~HOLO"""
<MyApp.Components.PoplarTracker cid="counter" eaten={0} />
"""
|> mount()
|> click("button", "Eat a poplar")
|> assert_has("p", "Number of poplars eaten: 1")

Context can be provided as a {Namespace, key: value} tuple. Props declared with from_context will be populated from matching context values.

~HOLO"""
<MyApp.Components.PoplarTracker cid="counter">
  <p>{@user.name} eats too many poplars</p>
</MyApp.Components.PoplarTracker>
"""
|> mount({MyApp, user: current_user, theme: "dark"})

For multiple namespaces, use a list of tuples:

~HOLO"""
<MyApp.Dashboard cid="dash" />
"""
|> mount([{MyApp, user: current_user}, {Themes, mode: "dark"}])

@spec open_browser(Mirage.Session.t(), keyword() | function()) :: Mirage.Session.t()

Opens the current page HTML in the default browser.

session
|> fill_in("Name", with: "Philip")
|> open_browser()
|> assert_has("Philip")

When using with a component (via Mirage.mount/2), the output will be wrapped in a thin layout bringing in your app's styles.

@spec reload(Mirage.Session.t()) :: Mirage.Session.t()

"Reloads" the current page by revisiting it with the current params.

All client-side state (component state, checked radios, etc.) is reset, just like a real browser reload.

session
|> fill_in("Name", with: "Leela")
|> reload()
|> refute_has("input", value: "Leela")

@spec select(Mirage.Session.t(), String.t(), String.t(), keyword()) ::
  Mirage.Session.t()

Selects an option in a <select> box by its label.

Triggers the select's $change event with the option's value attribute (defaulting to the option's inner text when no value attribute is present).

Labels may wrap the select element or reference it via a for/id pair.

Works with multi-selects.

Matches exactly by default; pass exact: false to match substrings. Raises if no matching label or option is found, or if more than one matches.

Example

EditProfilePage
|> visit()
|> select("Company", "Planet Express")
|> assert_has("p", "You work for 'Planet Express'")

@spec select_text(Mirage.Session.t(), String.t(), String.t() | keyword()) ::
  Mirage.Session.t()

Triggers a $select event on a text input or textarea by its label selecting the text given to option_text.

When text is omitted, all text in the input is selected.

Raises if the label does not point to an input that accepts text (i.e. raises for checkboxes, radios, selects, and non-text input types).

Examples

session
|> fill_in("Bio", with: "I'm a bending unit. I bend girders.")
|> select_text("Bio", "girder")

session
|> fill_in("Bio", with: "My hobbies include smoking cigars, drinking, and killing all humans")
|> select_text("Bio")

@spec uncheck(Mirage.Session.t(), String.t(), keyword()) :: Mirage.Session.t()

Unchecks a checkbox by its associated label.

Trigger's the input's $change event as well as its form's $change event (if it has one).

Matches exactly by default; pass exact: false to match substrings. Raises if no matching radio button is found, or if more than one matches.

@spec visit(
  module(),
  keyword()
) :: Mirage.Session.t()

Entry point to create a session.

Takes a Hologram.Page and, optional, any params. It returns a session which the rest of Mirage can use.

@spec within(Mirage.Session.t(), String.t(), (Mirage.Session.t() ->
                                          Mirage.Session.t())) ::
  Mirage.Session.t()

Scopes all operations within the given block to descendants of the element matching selector.

session
|> within(".sidebar", fn session ->
  session
  |> assert_has("a", "Home")
  |> click_link("Home")
end)

@spec within_article(Mirage.Session.t(), String.t(), (Mirage.Session.t() ->
                                                  Mirage.Session.t())) ::
  Mirage.Session.t()

Scopes to the <article> whose first heading (h1 - h6) matches header.

session
|> within_article("Blog Post", fn session ->
  assert_has(session, "p", "Post content")
end)

@spec within_fieldset(Mirage.Session.t(), String.t(), (Mirage.Session.t() ->
                                                   Mirage.Session.t())) ::
  Mirage.Session.t()

Scopes to the <fieldset> whose <legend> matches legend.

session
|> within_fieldset("Account", fn session ->
  assert_has(session, "input#username")
end)

@spec within_section(
  Mirage.Session.t(),
  String.t(),
  String.t(),
  (Mirage.Session.t() ->
     Mirage.Session.t())
) ::
  Mirage.Session.t()

Scopes to the <section> whose first heading (h1 - h6) matches header.

session
|> within_section("Settings", fn session ->
  assert_has(session, "Send me update", "No")
end)

This can also be used more generally when given a CSS selector as the second argument.

session
|> within_section("div[role=article]", "My header", fn session ->
  assert_has(session, "p", "content")
end)