Acceptance Tests: Use accessible names and descriptions (#662)

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 Co-authored-by: Matheus Richard <[email protected]>
thoughtbot · Jul 13, 2022 · d166a5e · d166a5e
1 parent efa5757
commit d166a5e
Showing 1 changed file with 5 additions and 0 deletions.
diff --git a/testing-rspec/README.md b/testing-rspec/README.md
@@ -46,6 +46,10 @@
 [Sample](acceptance_test_spec.rb)
 
 - Use the most specific [selectors][] available.
+- Don't locate elements with CSS selectors or `[id]` attributes.
+- Use [accessible names and descriptions][names_and_descriptions] to locate
+  elements, to interact with form controls, buttons, and links, or to scope
+  blocks of actions and assertions.
 - Avoid `it` block descriptions that add no information, such as "successfully."
 - Avoid `it` block descriptions that repeat the top-level `describe` block
   description.
@@ -60,6 +64,7 @@
 > system specs were previously called feature specs and lived in `spec/features`
 
 [selectors]: https://rubydoc.info/github/teamcapybara/capybara/master/Capybara/Selector
+[names_and_descriptions]: https://www.w3.org/WAI/ARIA/apg/practices/names-and-descriptions/
 
 ## Factories