View Source Wallaby.Query (wallaby v0.30.9)

Provides the query DSL.

Queries are used to locate and retrieve DOM elements from a browser (see Wallaby.Browser). You create queries like so:

Query.css(".some-css")
Query.xpath(".//input")

Form elements

There are several custom finders for locating form elements. Each of these allows finding by their name, id text, or label text. This allows for more robust querying and decouples the query from presentation selectors like CSS classes.

Query.text_field("My Name")
Query.checkbox("Checkbox")
Query.select("A Fancy Select Box")

Query Options

All of the query operations accept the following options:

:count - The number of elements that should be found or :any (default: 1).
- If a :minimum or :maximum is specified, it defaults to nil.
:minimum - The minimum number of elements that should be found, or nil (default: nil).
:maximum - The maximum number of elements that should be found, or nil (default: nil).
:visible - Determines if the query should return only visible elements (default: true).
:selected - Determines if the query should return only selected elements (default: :any).
:text - Text that should be found inside the element (default: nil).
:at - The position (a number or :all) of the element to return if multiple elements satisfy the query. (default: :all)

Query options can also be set via functions by the same names:

Query.css(".names")
|> Query.visible(true)
|> Query.count(3)

Re-using queries

It is often convenient to re-use queries. The easiest way is to use module attributes:

@name_field Query.text_field("User Name")
@submit_button Query.button("Save")

If the queries need to be dynamic then you should create a module that encapsulates the queries as functions:

defmodule TodoListPage do
  def todo_list do
    Query.css(".todo-list")
  end

  def todos(count) do
    Query.css(".todo", count: count)
  end
end

What does my query do?

Wanna check out what exactly your query will do? Look no further than Wallaby.Query.compile/1 - it takes a query and returns the CSS or xpath query that will be sent to the driver:

iex> Wallaby.Query.compile Wallaby.Query.text("my text")
{:xpath, ".//*[contains(normalize-space(text()), \"my text\")]"}

So, whenever you're not sure whatever a specific query will do just compile it to get all the details!

Summary

Types

attribute_key_value_pair()

compiled()

conditions()

html_validation()

method()

opts()

result()

selector()

t()

Functions

at(query, value)

Updates a query's at option.

at_number(query)

attribute(name, value, opts \\ [])

Checks if the provided attribute, value pair is contained anywhere.

button(selector, opts \\ [])

Looks for a button (literal button or input type button, submit, image or reset) where the provided selector is the id, name, value, alt or title of the button.

checkbox(selector, opts \\ [])

Looks for a checkbox where the provided selector is the id, name or placeholder of the checkbox itself or alternatively the id or the text of the label.

compile(map)

Compiles a query into CSS or xpath so its ready to be sent to the driver

count(query)

count(query, value)

Updates a query's count.

css(selector, opts \\ [])

Literally queries for the CSS selector you provide.

data(name, selector, opts \\ [])

Checks if the data attribute is contained anywhere.

file_field(selector, opts \\ [])

Looks for a file input where the selector is the id or name of the file input itself or the id or text of the label.

fillable_field(selector, opts \\ [])

Looks for a text input field where the provided selector is the id, name or placeholder of the text field itself or alternatively the id or the text of the label.

inner_text(query)

link(selector, opts \\ [])

Looks for a link where the selector is the id, link text, title of the link itself or the alt of an image child node.

matches_count?(query, count)

option(selector, opts \\ [])

Looks for an option that contains the given text.

radio_button(selector, opts \\ [])

Looks for a radio button where the provided selector is the id, name or placeholder of the radio button itself or alternatively the id or the text of the label.

result(query)

select(selector, opts \\ [])

Looks for a select box where the provided selector is the id or name of the select box itself or alternatively the id or the text of the label.

selected(query, value)

Updates a query's selected option.

selected?(query)

specific_element_requested(query)

text(query_or_selector, value_or_opts \\ [])

This function can be used in one of two ways.

text_field(selector, opts \\ [])

See Wallaby.Query.fillable_field/2.

validate(query)

value(selector, opts \\ [])

Checks if the provided value is contained anywhere.

visible(query, value)

Updates a query's visibility (visible if true, hidden if false).

visible?(query)

xpath(selector, opts \\ [])

Literally queries for the xpath selector you provide.

Types

attribute_key_value_pair()

@type attribute_key_value_pair() :: {String.t(), String.t()}

compiled()

@type compiled() :: {:xpath | :css, String.t()}

conditions()

@type conditions() :: [
  count: non_neg_integer() | :any | nil,
  minimum: non_neg_integer() | nil,
  maximum: non_neg_integer() | nil,
  text: String.t() | nil,
  visible: boolean() | :any,
  selected: boolean() | :any,
  at: non_neg_integer() | :all
]

html_validation()

@type html_validation() :: :bad_label | :button_type | nil

method()

@type method() ::
  :css
  | :xpath
  | :link
  | :button
  | :fillable_field
  | :checkbox
  | :radio_button
  | :option
  | :select
  | :file_field
  | :attribute

opts()

@type opts() :: list()

result()

@type result() :: [Wallaby.Element.t()]

selector()

@type selector() :: String.t() | attribute_key_value_pair()

t()

@type t() :: %Wallaby.Query{
  conditions: conditions(),
  html_validation: html_validation(),
  method: method(),
  result: result(),
  selector: selector()
}

Functions

at(query, value)

Updates a query's at option.

Example

  Query.css(".names")
  |> Query.at(3)

at_number(query)

attribute(name, value, opts \\ [])

Checks if the provided attribute, value pair is contained anywhere.

button(selector, opts \\ [])

Looks for a button (literal button or input type button, submit, image or reset) where the provided selector is the id, name, value, alt or title of the button.

checkbox(selector, opts \\ [])

Looks for a checkbox where the provided selector is the id, name or placeholder of the checkbox itself or alternatively the id or the text of the label.

compile(map)

@spec compile(t()) :: compiled()

Compiles a query into CSS or xpath so its ready to be sent to the driver

iex> Wallaby.Query.compile Wallaby.Query.text("my text")
{:xpath, ".//*[contains(normalize-space(text()), \"my text\")]"}
iex> Wallaby.Query.compile Wallaby.Query.css("#some-id")
{:css, "#some-id"}

count(query)

count(query, value)

Updates a query's count.

The count specifies how many elements you expect to be present within the scope of the query and can be any number greater than zero or :any.

Example

# Exactly 2 elements
Query.css(".names > li")
|> Query.count(2)

# Any number of elements
Query.css(".names > li")
|> Query.count(:any)

css(selector, opts \\ [])

Literally queries for the CSS selector you provide.

data(name, selector, opts \\ [])

Checks if the data attribute is contained anywhere.

file_field(selector, opts \\ [])

Looks for a file input where the selector is the id or name of the file input itself or the id or text of the label.

fillable_field(selector, opts \\ [])

Looks for a text input field where the provided selector is the id, name or placeholder of the text field itself or alternatively the id or the text of the label.

inner_text(query)

link(selector, opts \\ [])

Looks for a link where the selector is the id, link text, title of the link itself or the alt of an image child node.

matches_count?(query, count)

option(selector, opts \\ [])

Looks for an option that contains the given text.

radio_button(selector, opts \\ [])

Looks for a radio button where the provided selector is the id, name or placeholder of the radio button itself or alternatively the id or the text of the label.

result(query)

select(selector, opts \\ [])

Looks for a select box where the provided selector is the id or name of the select box itself or alternatively the id or the text of the label.

selected(query, value)

Updates a query's selected option.

Examples

  Query.css("#select-dropdown")
  |> Query.selected(true)

  Query.css("#select-dropdown")
  |> Query.selected(false)

selected?(query)

specific_element_requested(query)

text(query_or_selector, value_or_opts \\ [])

This function can be used in one of two ways.

The first is by providing a selector and possible options. This generates a query that checks if the provided text is contained anywhere.

Example

  Query.text("Submit", count: 1)

The second is by providing an existing query and a value to set as the text option.

Note that the text you're querying for must appear in a single element. To assert on text that appears in multiple (potentially nested) elements, rather than using assert_has/2 in combination with Query.text/2, use assert_text/{2,3} directly.

Examples

Querying the text of a specific element

  submit_button = Query.css("#submit-button")

  update_button = submit_button |> Query.text("Update")
  create_button = submit_button |> Query.text("Create")

Asserting on the text of a single element

```
submit_button = Query.css("#submit-button")
assert_has(session, Query.text(submit_button, "Create"))
```

Asserting on the text of nested elements

HTML:

```
<div id="unread-notifications">
  Unread messages:
  <strong>1 message</strong>
</div>
```

Test:

```
assert_text(session, "Unread messages: 1 message")

notifications_block = Query.css("#unread-notifications")
# It would *not* work to query as: Query.text(notifications_block, "Unread messages: 1 message")
assert_has(session, Query.text(notifications_block, "Unread messages:"))
```

text_field(selector, opts \\ [])

See Wallaby.Query.fillable_field/2.

validate(query)

value(selector, opts \\ [])

Checks if the provided value is contained anywhere.

visible(query, value)

Updates a query's visibility (visible if true, hidden if false).

Examples

  Query.css("#modal")
  |> Query.visible(true)

  Query.css("#modal")
  |> Query.visible(false)

visible?(query)

xpath(selector, opts \\ [])

Literally queries for the xpath selector you provide.