Posted 11 months ago. Visible to the public. Repeats.

Capybara can find links and fields by their [aria-label]

Sometimes a link or input field has no visible label. E.g. a text field with a magnifying glass icon 🔎 and a "Search" button does not really need a visible label "Query".

For accessibility Archive reasons it is good practice to give such a field an [aria-label] attribute:

<input type="search" aria-label="Search contacts">

This way, when a visually impaired user focuses the field, the screen reader will speak the label text ("Search contacts").


Without an [aria-label] attribute screen readers will announce the field by its element type. In the example above (if no [aria-label] would be provided) it would speak something like "Search input".

Configuring Capybara to use [aria-label]

Capybara will not by default find an input field by its [aria-label] attribute. However, you can configure it to do so:

fill_in 'Search contacts', with: 'foo' # => raises "Unable to find field 'Query'" Capybara.enable_aria_label = true # enable [aria-label] support for field finders fill_in 'Search contacts', with: 'foo' # => fills in the query "foo"

Also see An auto-mapper for ARIA labels and BEM classes in Cucumber selectors

By refactoring problematic code and creating automated tests, makandra can vastly improve the maintainability of your Rails application.

Owner of this card:

Henning Koch
Last edit:
3 months ago
by Henning Koch
About this deck:
We are makandra and do test-driven, agile Ruby on Rails software development.
License for source code
Posted by Henning Koch to makandra dev
This website uses short-lived cookies to improve usability.
Accept or learn more