Merge pull request #518 from testing-library/nickmccurdy-patch-1

Add documentation for queryFallback

Author: nickserv

docs/dom-testing-library/api-queries.md

@@ -605,6 +605,7 @@ getByRole(
     name?: TextMatch,
     normalizer?: NormalizerFn,
     selected?: boolean,
+    queryFallbacks?: boolean,
   }): HTMLElement
 ```
 
@@ -710,6 +711,12 @@ cy.findByRole('dialog').should('exist')
 
 <!--END_DOCUSAURUS_CODE_TABS-->
 
+By default, it's assumed that the first role of each element is supported, so only the first role can be queried. If you need to query an element by any of its fallback roles instead, you can use `queryFallbacks: true`.
+
+For example, `getByRole('switch')` would always match `<div role="switch checkbox" />` because it's the first role, while `getByRole('checkbox')` would not. However, `getByRole('checkbox', { queryFallbacks: true })` would enable all fallback roles and therefore match the same element.
+
+> An element doesn't have multiple roles in a given environment. It has a single one. Multiple roles in the attribute are evaluated from left to right until the environment finds the first role it understands. This is useful when new roles get introduced and you want to start supporting those as well as older environments that don't understand that role (yet).
+
 ### `ByTestId`
 
 > getByTestId, queryByTestId, getAllByTestId, queryAllByTestId, findByTestId,