|
| 1 | +# By Role |
| 2 | + |
| 3 | +> `get_by_role`, `query_by_role`, `get_all_by_role`, `query_all_by_role`, `find_by_role`, `find_all_by_role` |
| 4 | +
|
| 5 | +## API |
| 6 | + |
| 7 | +```rust,ignore |
| 8 | +use aria_query::AriaRole; |
| 9 | +use testing_library_dom::{Matcher, QueryError}; |
| 10 | +use web_sys::HtmlElement; |
| 11 | +
|
| 12 | +fn get_by_role( |
| 13 | + // If you're using `screen`, then skip the container argument: |
| 14 | + container: &HtmlElement, |
| 15 | + role: AriaRole, |
| 16 | + options: ByRoleOptions |
| 17 | +) -> Result<Option<HtmlElement>, QueryError>; |
| 18 | +
|
| 19 | +struct ByRoleOptions { |
| 20 | + hidden: Option<bool>, |
| 21 | + name: Option<Matcher>, |
| 22 | + description: Option<Matcher>, |
| 23 | + selected: Option<bool>, |
| 24 | + busy: Option<bool>, |
| 25 | + checked: Option<bool>, |
| 26 | + pressed: Option<bool>, |
| 27 | + suggest: Option<bool>, |
| 28 | + current: Option<ByRoleOptionsCurrent>, |
| 29 | + expanded: Option<bool>, |
| 30 | + query_fallbacks: Option<bool>, |
| 31 | + level: Option<usize>, |
| 32 | + value: Option<ByRoleOptionsValue>, |
| 33 | +} |
| 34 | +
|
| 35 | +enum ByRoleOptionsCurrent { |
| 36 | + Bool(bool), |
| 37 | + String(String), |
| 38 | +} |
| 39 | +
|
| 40 | +struct ByRoleOptionsValue { |
| 41 | + now: Option<f64>, |
| 42 | + min: Option<f64>, |
| 43 | + max: Option<f64>, |
| 44 | + text: Option<Matcher>, |
| 45 | +} |
| 46 | +``` |
| 47 | + |
| 48 | +Queries for elements with the given role <!-- (and it also accepts a TextMatch) -->. Default roles are taken into consideration e.g. `<button />` has the `button` role without explicitly setting the `role` attribute. Here you can see [a table of HTML elements with their default and desired roles](https://www.w3.org/TR/html-aria/#docconformance). |
| 49 | + |
| 50 | +Please note that setting a `role` and/or `aria-*` attribute that matches the implicit ARIA semantics is unnecessary and is **not recommended** as these properties are already set by the browser, and we must not use the `role` and `aria-*` attributes in a manner that conflicts with the semantics described. For example, a `button` element can't have the `role` attribute of `heading`, because the `button` element has default characteristics that conflict with the `heading` role. |
| 51 | + |
| 52 | +<!-- TODO: Ensure text still applies to `AriaRole`. --> |
| 53 | + |
| 54 | +> Roles are matched literally by string equality, without inheriting from the ARIA role hierarchy. As a result, querying a superclass role like `checkbox` will not include elements with a subclass role like `switch`. |
| 55 | +
|
| 56 | +You can query the returned element(s) by their [accessible name or description](https://www.w3.org/TR/accname-1.1/). The accessible name is for simple cases equal to e.g. the label of a form element, or the text content of a button, or the value of the `aria-label` attribute. It can be used to query a specific element if multiple elements with the same role are present on the rendered content. For an in-depth guide check out ["What is an accessible name?" from TPGi](https://www.tpgi.com/what-is-an-accessible-name/). If you only query for a single element with `get_by_text("The name")` it's oftentimes better to use `get_by_role(expected_role, { name: "The name" })`. The accessible name query does not replace other queries such as `*_by_alt` or `*_by_title`. While the accessible name can be equal to these attributes, it does not replace the functionality of these attributes. For example `<img aria-label="fancy image" src="fancy.jpg" />` will be returned for `get_by_role("img", { name: "fancy image" })`. However, the image will not display its description if `fancy.jpg` could not be loaded. Whether you want to assert this functionality in your test or not is up to you. |
| 57 | + |
| 58 | +<div class="warning"> |
| 59 | + |
| 60 | +**Input type password** |
| 61 | + |
| 62 | +Unfortunately, the spec defines that `<input type="password" />` has no implicit role. This means that in order to query this type of element we must fallback to a less powerful query such as [By Label Text](./by-label-text.md). |
| 63 | + |
| 64 | +</div> |
| 65 | + |
| 66 | +## Options |
| 67 | + |
| 68 | +### `hidden` |
| 69 | + |
| 70 | +TODO |
| 71 | + |
| 72 | +### `selected` |
| 73 | + |
| 74 | +TODO |
| 75 | + |
| 76 | +### `busy` |
| 77 | + |
| 78 | +TODO |
| 79 | + |
| 80 | +### `checked` |
| 81 | + |
| 82 | +TODO |
| 83 | + |
| 84 | +### `current` |
| 85 | + |
| 86 | +TODO |
| 87 | + |
| 88 | +### `pressed` |
| 89 | + |
| 90 | +TODO |
| 91 | + |
| 92 | +### `suggest` |
| 93 | + |
| 94 | +TODO |
| 95 | + |
| 96 | +### `expanded` |
| 97 | + |
| 98 | +TODO |
| 99 | + |
| 100 | +### `query_fallbacks` |
| 101 | + |
| 102 | +TODO |
| 103 | + |
| 104 | +### `level` |
| 105 | + |
| 106 | +TODO |
| 107 | + |
| 108 | +### `value` |
| 109 | + |
| 110 | +TODO |
| 111 | + |
| 112 | +### `description` |
| 113 | + |
| 114 | +TODO |
| 115 | + |
| 116 | +## Performance |
| 117 | + |
| 118 | +`get_by_role` is the most preferred query to use as it most closely resembles the user experience, however the calculations it must perform to provide this confidence can be expensive (particularly with large DOM trees). |
| 119 | + |
| 120 | +Where test performance is a concern it may be desirable to trade some of this confidence for improved performance. |
| 121 | + |
| 122 | +`get_by_role` performance can be improved by setting the option [`hidden`](#hidden) to `true` and thereby avoid expensive visibility checks. Note that in doing so inaccessible elements will now be included in the result. |
| 123 | + |
| 124 | +Another option may be to substitute `get_by_role` for simpler `get_by_label_text` and `get_by_text` queries which can be significantly faster though less robust alternatives. |
0 commit comments