Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Acceptance Tests: Use accessible names and descriptions #662

Merged
merged 3 commits into from
Jul 13, 2022

Conversation

seanpdoyle
Copy link
Contributor

End-users very rarely interact with our applications based on CSS
selectors or an element's [id] attribute.

Whether they're driving their their browser directly or with the support
of assistive technologies, end-user interact with a page's form
controls, buttons, or links based on their visual presentation or their
text content.

In order for our automated test suites to reliably simulate end-user
experiences with the highest fidelity, we should write our instructions
with accessible names and descriptions in
mind.

End-users very rarely interact with our applications based on CSS
selectors or an element's `[id]` attribute.

Whether they're driving their their browser directly or with the support
of assistive technologies, end-user interact with a page's form
controls, buttons, or links based on their visual presentation or their
text content.

In order for our automated test suites to reliably simulate end-user
experiences with the highest fidelity, we should write our instructions
with [accessible names and descriptions][names_and_descriptions] in
mind.

[names_and_descriptions]: https://www.w3.org/TR/wai-aria-practices/#names_and_descriptions
@seanpdoyle seanpdoyle requested a review from JoelQ May 9, 2022 16:21
Copy link

@thiagoa thiagoa left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you! I love this guideline, and the docs are very helpful.

@@ -45,6 +45,10 @@

[Sample](acceptance_test_spec.rb)

- Don't locate elements with CSS selectors or `[id]` attributes.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Don't

Most acceptance tests I see are testing the happy path, and therefore they should definitely follow this advice.

Sometimes I see acceptance tests that are like:

scenario "the happy path", :js do
  # great practices in here. stellar work
end

scenario "the user's favorite color is incorrect", :js do
  # ... shortcuts that get us to the page most quickly ..., then
  fill_in "Favorite color", with: "Blue"
  click_on "That is definitely my favorite color. It's absolutely not yellow"
  expect(page).to have_content("You may not cross this bridge")
end

Where the happy path follows this advice, but the other test wishes it were a request test but it needs JS.

What do you think of this practice? Do you think it warrants using "avoid" instead of "don't"?

Copy link
Contributor Author

@seanpdoyle seanpdoyle May 13, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think I'm missing context on the question. Where in this example code is an [id], CSS selector, or JavaScript?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Er, sorry about that. The [id] happens in here:

  # ... shortcuts that get us to the page most quickly ..., then

I was unimaginative and couldn't quickly find a real code example where we were sloppy in the lead-up to the error case code path.

(And the JS is whatever is required to get the content on the page. You can imagine a single-page app or some other monstrosity.)

Some meta thoughts:

  • maybe an implication here is that error paths should be tested at a totally different layer.
  • maybe there's no excuse for circumventing the good, accessible way to navigate, even if it is more verbose.

Copy link
Contributor Author

@seanpdoyle seanpdoyle May 13, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maybe an implication here is that error paths should be tested at a totally different layer.

Personally, I'm exploring that space with efforts like thoughtbot/action_dispatch-testing-integration-capybara, but this could be covered with view or component testing, separate from the browser environment.

maybe there's no excuse for circumventing the good, accessible way to navigate, even if it is more verbose.

There are for Capybara to locate, interact with, or assert invalid fields.

For example, the :field selector accepts a valid: Boolean filter and a validation_message: String filter to affect query scope based on an element's validity state (which requires a Real Browser to function, but doesn't require any JS).

Similarly, the citizensadvice/capybara_accessible_selectors gem extends :fillable_field and other form control selectors to accept a described_by: filter based on a form control having text content that references it through the aria-describedby attribute.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please let me know how I can help. I believe I merged.

Copy link
Contributor

@mike-burns mike-burns left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah alright. Let's give this a try!

@seanpdoyle seanpdoyle merged commit d166a5e into main Jul 13, 2022
@seanpdoyle seanpdoyle deleted the acceptance-testing-accessible-name branch July 13, 2022 13:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

7 participants