-
-
Notifications
You must be signed in to change notification settings - Fork 1.4k
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
Conversation
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
There was a problem hiding this 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. |
There was a problem hiding this comment.
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"?
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this 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!
Co-authored-by: Matheus Richard <[email protected]>
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.