All Selectors below support the listed selector specific filters in addition to the following system-wide filters
- :id (String, Regexp, XPath::Expression) - Matches the id attribute
- :class (String, Array, Regexp, XPath::Expression) - Matches the class(es) provided
- :style (String, Regexp, Hash) - Match on elements style
- :above (Element) - Match elements above the passed element on the page
- :below (Element) - Match elements below the passed element on the page
- :left_of (Element) - Match elements left of the passed element on the page
- :right_of (Element) - Match elements right of the passed element on the page
- :near (Element) - Match elements near (within 50px) the passed element on the page
- :focused (Boolean) - Match elements with focus (requires driver support)
Built-in Selectors
- :xpath - Select elements by XPath expression
- Locator: An XPath expression
page.html
page.find :xpath, './/input'
- :css - Select elements by CSS selector
page.html
page.find :css, 'input'
- :id - Select element by id
- Locator: (String, Regexp, XPath::Expression) The id of the element to match
page.html
page.find :id, 'content'
- :field - Select field elements (input [not of type submit, image, or hidden], textarea, select)
- Locator: Matches against the id, test_id attribute, name, placeholder, or
associated label text
- Filters:
- :name (String, Regexp) - Matches the name attribute
- :placeholder (String, Regexp) - Matches the placeholder attribute
- :type (String) - Matches the type attribute of the field or element type for 'textarea' and 'select'
- :readonly (Boolean) - Match on the element being readonly
- :with (String, Regexp) - Matches the current value of the field
- :checked (Boolean) - Match checked fields?
- :unchecked (Boolean) - Match unchecked fields?
- :disabled (Boolean, :all) - Match disabled field? (Default: false)
- :multiple (Boolean) - Match fields that accept multiple values
- :valid (Boolean) - Match fields that are valid/invalid according to HTML5 form validation
- :validation_message (String, Regexp) - Matches the elements current validationMessage
page.html # => '<label for="article_title">Title</label>
<input id="article_title" name="article[title]" value="Hello world">'
page.find :field, 'article_title'
page.find :field, 'article[title]'
page.find :field, 'Title'
page.find :field, 'Title', type: 'text', with: 'Hello world'
- :fieldset - Select fieldset elements
- Locator: Matches id, test_id, or contents of wrapped legend
- Filters:
- :legend (String) - Matches contents of wrapped legend
- :disabled (Boolean) - Match disabled fieldset?
page.html # => '<fieldset disabled>
<legend>Fields (disabled)</legend>
</fieldset>'
page.find :fieldset, 'Fields (disabled)', disabled: true
- :link - Find links (
<a> elements with an href attribute)
- Locator: Matches the id, test_id, or title attributes, or the string content of the link,
or the alt attribute of a contained img element. By default this selector requires a link to have an href attribute.
- Filters:
- :title (String) - Matches the title attribute
- :alt (String) - Matches the alt attribute of a contained img element
- :href (String, Regexp, nil, false) - Matches the normalized href of the link, if nil will find
<a> elements with no href attribute, if false ignores href presence
page.html
page.find :link, 'Home', href: '/'
page.html
page.find :link, 'The logo', href: '/'
page.find :link, alt: 'The logo', href: '/'
- :button - Find buttons ( input [of type submit, reset, image, button] or button elements )
- Locator: Matches the id, test_id attribute, name, value, or title attributes, string content of a button, or the alt attribute of an image type button or of a descendant image of a button
- Filters:
- :name (String, Regexp) - Matches the name attribute
- :title (String) - Matches the title attribute
- :value (String) - Matches the value of an input button
- :type (String) - Matches the type attribute
- :disabled (Boolean, :all) - Match disabled buttons (Default: false)
page.html
page.find :button, 'Submit'
page.html
page.find :button, 'Save as draft', name: 'article[state]', value: 'draft'
- :link_or_button - Find links or buttons
- Locator: See :link and :button selectors
- Filters:
- :disabled (Boolean, :all) - Match disabled buttons? (Default: false)
page.html
page.find :link_or_button, 'Home'
page.html
page.find :link_or_button, 'Submit'
- :fillable_field - Find text fillable fields ( textarea, input [not of type submit, image, radio, checkbox, hidden, file] )
- Locator: Matches against the id, test_id attribute, name, placeholder, or associated label text
- Filters:
- :name (String, Regexp) - Matches the name attribute
- :placeholder (String, Regexp) - Matches the placeholder attribute
- :with (String, Regexp) - Matches the current value of the field
- :type (String) - Matches the type attribute of the field or element type for 'textarea'
- :disabled (Boolean, :all) - Match disabled field? (Default: false)
- :multiple (Boolean) - Match fields that accept multiple values
- :valid (Boolean) - Match fields that are valid/invalid according to HTML5 form validation
- :validation_message (String, Regexp) - Matches the elements current validationMessage
page.html # => '<label for="article_body">Body</label>
<textarea id="article_body" name="article[body]"></textarea>'
page.find :fillable_field, 'article_body'
page.find :fillable_field, 'article[body]'
page.find :fillable_field, 'Body'
page.find :field, 'Body', type: 'textarea'
- :radio_button - Find radio buttons
- Locator: Match id, test_id attribute, name, or associated label text
- Filters:
- :name (String, Regexp) - Matches the name attribute
- :checked (Boolean) - Match checked fields?
- :unchecked (Boolean) - Match unchecked fields?
- :disabled (Boolean, :all) - Match disabled field? (Default: false)
- :option (String, Regexp) - Match the current value
- :with - Alias of :option
page.html # => '<input type="radio" id="article_state_published" name="article[state]" value="published" checked>
<label for="article_state_published">Published</label>
<input type="radio" id="article_state_draft" name="article[state]" value="draft">
<label for="article_state_draft">Draft</label>'
page.find :radio_button, 'article_state_published'
page.find :radio_button, 'article[state]', option: 'published'
page.find :radio_button, 'Published', checked: true
page.find :radio_button, 'Draft', unchecked: true
- :checkbox - Find checkboxes
- Locator: Match id, test_id attribute, name, or associated label text
- Filters:
- :name (String, Regexp) - Matches the name attribute
- :checked (Boolean) - Match checked fields?
- :unchecked (Boolean) - Match unchecked fields?
- :disabled (Boolean, :all) - Match disabled field? (Default: false)
- :with (String, Regexp) - Match the current value
- :option - Alias of :with
page.html # => '<input type="checkbox" id="registration_terms" name="registration[terms]" value="true">
<label for="registration_terms">I agree to terms and conditions</label>'
page.find :checkbox, 'registration_terms'
page.find :checkbox, 'registration[terms]'
page.find :checkbox, 'I agree to terms and conditions', unchecked: true
- :select - Find select elements
- Locator: Match id, test_id attribute, name, placeholder, or associated label text
- Filters:
- :name (String, Regexp) - Matches the name attribute
- :placeholder (String, Placeholder) - Matches the placeholder attribute
- :disabled (Boolean, :all) - Match disabled field? (Default: false)
- :multiple (Boolean) - Match fields that accept multiple values
- :options (Array) - Exact match options
- :enabled_options (Array) - Exact match enabled options
- :disabled_options (Array) - Exact match disabled options
- :with_options (Array) - Partial match options
- :selected (String, Array) - Match the selection(s)
- :with_selected (String, Array) - Partial match the selection(s)
page.html # => '<label for="article_category">Category</label>
<select id="article_category" name="article[category]">
<option value="General" checked></option>
<option value="Other"></option>
</select>'
page.find :select, 'article_category'
page.find :select, 'article[category]'
page.find :select, 'Category'
page.find :select, 'Category', selected: 'General'
page.find :select, with_options: ['General']
page.find :select, with_options: ['Other']
page.find :select, options: ['General', 'Other']
page.find :select, options: ['General'] # => raises Capybara::ElementNotFound
- :option - Find option elements
- Locator: Match text of option
- Filters:
- :disabled (Boolean) - Match disabled option
- :selected (Boolean) - Match selected option
page.html # => '<option value="General" checked></option>
<option value="Disabled" disabled></option>
<option value="Other"></option>'
page.find :option, 'General'
page.find :option, 'General', selected: true
page.find :option, 'Disabled', disabled: true
page.find :option, 'Other', selected: false
- :datalist_input - Find input field with datalist completion
- Locator: Matches against the id, test_id attribute, name,
placeholder, or associated label text
- Filters:
- :name (String, Regexp) - Matches the name attribute
- :placeholder (String, Regexp) - Matches the placeholder attribute
- :disabled (Boolean, :all) - Match disabled field? (Default: false)
- :options (Array) - Exact match options
- :with_options (Array) - Partial match options
page.html # => '<label for="ice_cream_flavor">Flavor</label>
<input list="ice_cream_flavors" id="ice_cream_flavor" name="ice_cream[flavor]">
<datalist id="ice_cream_flavors">
<option value="Chocolate"></option>
<option value="Strawberry"></option>
<option value="Vanilla"></option>
</datalist>'
page.find :datalist_input, 'ice_cream_flavor'
page.find :datalist_input, 'ice_cream[flavor]'
page.find :datalist_input, 'Flavor'
page.find :datalist_input, with_options: ['Chocolate', 'Strawberry']
page.find :datalist_input, options: ['Chocolate', 'Strawberry', 'Vanilla']
page.find :datalist_input, options: ['Chocolate'] # => raises Capybara::ElementNotFound
- :datalist_option - Find datalist option
- Locator: Match text or value of option
- Filters:
- :disabled (Boolean) - Match disabled option
page.html # => '<datalist>
<option value="Chocolate"></option>
<option value="Strawberry"></option>
<option value="Vanilla"></option>
<option value="Forbidden" disabled></option>
</datalist>'
page.find :datalist_option, 'Chocolate'
page.find :datalist_option, 'Strawberry'
page.find :datalist_option, 'Vanilla'
page.find :datalist_option, 'Forbidden', disabled: true
- :file_field - Find file input elements
- Locator: Match id, test_id attribute, name, or associated label text
- Filters:
- :name (String, Regexp) - Matches the name attribute
- :disabled (Boolean, :all) - Match disabled field? (Default: false)
- :multiple (Boolean) - Match field that accepts multiple values
page.html # => '<label for="article_banner_image">Banner Image</label>
<input type="file" id="article_banner_image" name="article[banner_image]">'
page.find :file_field, 'article_banner_image'
page.find :file_field, 'article[banner_image]'
page.find :file_field, 'Banner Image'
page.find :file_field, 'Banner Image', name: 'article[banner_image]'
page.find :field, 'Banner Image', type: 'file'
- :label - Find label elements
- Locator: Match id, test_id, or text contents
- Filters:
- :for (Element, String, Regexp) - The element or id of the element associated with the label
page.html # => '<label for="article_title">Title</label>
<input id="article_title" name="article[title]">'
page.find :label, 'Title'
page.find :label, 'Title', for: 'article_title'
page.find :label, 'Title', for: page.find('article[title]')
- :table - Find table elements
- Locator: id, test_id, or caption text of table
- Filters:
- :caption (String) - Match text of associated caption
- :with_rows (Array>, Array>) - Partial match
<td> data - visibility of <td> elements is not considered
- :rows (Array>) - Match all
<td>s - visibility of <td> elements is not considered
- :with_cols (Array>, Array>) - Partial match
<td> data - visibility of <td> elements is not considered
- :cols (Array>) - Match all
<td>s - visibility of <td> elements is not considered
page.html # => '<table>
<caption>A table</caption>
<tr>
<th>A</th>
<th>B</th>
</tr>
<tr>
<td>1</td>
<td>2</td>
</tr>
<tr>
<td>3</td>
<td>4</td>
</tr>
</table>'
page.find :table, 'A table'
page.find :table, with_rows: [
{ 'A' => '1', 'B' => '2' },
{ 'A' => '3', 'B' => '4' },
]
page.find :table, with_rows: [
['1', '2'],
['3', '4'],
]
page.find :table, rows: [
{ 'A' => '1', 'B' => '2' },
{ 'A' => '3', 'B' => '4' },
]
page.find :table, rows: [
['1', '2'],
['3', '4'],
]
page.find :table, rows: [ ['1', '2'] ] # => raises Capybara::ElementNotFound
- :table_row - Find table row
- Locator: Array, Hash table row
<td> contents - visibility of <td> elements is not considered
page.html # => '<table>
<tr>
<th>A</th>
<th>B</th>
</tr>
<tr>
<td>1</td>
<td>2</td>
</tr>
<tr>
<td>3</td>
<td>4</td>
</tr>
</table>'
page.find :table_row, 'A' => '1', 'B' => '2'
page.find :table_row, 'A' => '3', 'B' => '4'
- :frame - Find frame/iframe elements
- Locator: Match id, test_id attribute, or name
- Filters:
- :name (String) - Match name attribute
page.html
page.find :frame, 'embed_frame'
page.find :frame, 'embed'
page.find :frame, name: 'embed'
- :element
- Locator: Type of element ('div', 'a', etc) - if not specified defaults to '*'
- Filters:
- :<any> (String, Regexp) - Match on any specified element attribute
page.html
page.find :element, 'button'
page.find :element, type: 'button', text: 'Check me'
page.find :element, role: 'menuitemcheckbox'
page.find :element, role: /checkbox/, 'aria-checked': 'true'