|
| 1 | +# Configuration Options |
| 2 | + |
| 3 | +## Introduction |
| 4 | + |
| 5 | +## Options |
| 6 | + |
| 7 | +### `default_hidden` |
| 8 | + |
| 9 | +The default value for the [`hidden` option](../queries/by-role.md#hidden) used by `get_by_role`. Defaults to `false`. |
| 10 | + |
| 11 | +### `default_ignore` |
| 12 | + |
| 13 | +The default value for the [`ignore` option](../queries/by-text.md#ignore) used by `get_by_text`. Also determines the nodes that are being ignored when errors are printed. |
| 14 | + |
| 15 | +Defaults to `script, style`. |
| 16 | + |
| 17 | +### `throw_suggestions` (experimental) |
| 18 | + |
| 19 | +When enabled, if [better queries](../queries/about-queries.md#priority) are available, the test will fail and provide a suggested query to use instead. Defaults to `false`. |
| 20 | + |
| 21 | +To disable a suggestion for a single query just add `.suggest(false)` as an option. |
| 22 | + |
| 23 | +```rust,ignore |
| 24 | +// Will not throw a suggestion. |
| 25 | +screen.get_by_test_id("foo", MatcherOptions::default().suggest(false)) |
| 26 | +``` |
| 27 | + |
| 28 | +> **Note** |
| 29 | +> |
| 30 | +> When this option is enabled, it may provide suggestions that lack an intuitive implementation. Typically this happens for [roles which cannot be named](https://w3c.github.io/aria/#namefromprohibited), most notably paragraphs. For instance, if you attempt to use `get_by_text`, you may encounter the following error: |
| 31 | +> |
| 32 | +> ```text |
| 33 | +> A better query is available, try this: |
| 34 | +> get_by_role(AriaRole::Paragraph) |
| 35 | +> ``` |
| 36 | +> |
| 37 | +> However, there is no direct way to query paragraphs using the config parameter, such as in `get_by_role(AriaRole::Paragraph, ByRoleOptions::default().name("Hello World"))`. |
| 38 | +> |
| 39 | +> To address this issue, you can leverage a custom function to validate the element's structure, as shown in the example below. More information can be found in the [GitHub issue](https://github.com/testing-library/dom-testing-library/issues/1306). |
| 40 | +> |
| 41 | +> ```rust,ignore |
| 42 | +> get_by_role( |
| 43 | +> AriaRole::Paragraph, |
| 44 | +> ByRoleOptions::default().name(Rc::new(|_, element| { |
| 45 | +> element.map(|element| element.text_content()).is_some_and(|content| content == "Hello World") |
| 46 | +> })) |
| 47 | +> ) |
| 48 | +> ``` |
| 49 | +
|
| 50 | +### `test_id_attribute` |
| 51 | +
|
| 52 | +The attribute used by `get_by_test_id` and related queries. Defaults to `data-testid`. |
| 53 | +
|
| 54 | +### `get_element_error` |
| 55 | +
|
| 56 | +A function that returns the error used when [get or find queries](../queries/about-queries.md#types-of-queries) fail. Takes the error message and container as arguments. |
| 57 | +
|
| 58 | +### `async_util_timeout` |
| 59 | +
|
| 60 | +The global timeout value in milliseconds used by `wait_for` utilities. Defaults to 1000ms. |
0 commit comments