0
# DOM Queries
1

2
Complete reference for all query methods. Every query type supports three variants (get/query/find) with plural forms (getAll/queryAll/findAll).
3

4
## Query Variants
5

6
```typescript
7
// Single element queries
8
function getBy*<T extends HTMLElement = HTMLElement>(
9
  container: HTMLElement,
10
  text: Matcher,
11
  options?: Options
12
): T;  // Throws if 0 or 2+ matches
13

14
function queryBy*<T extends HTMLElement = HTMLElement>(
15
  container: HTMLElement,
16
  text: Matcher,
17
  options?: Options
18
): T | null;  // Returns null if not found
19

20
function findBy*<T extends HTMLElement = HTMLElement>(
21
  container: HTMLElement,
22
  text: Matcher,
23
  options?: Options,
24
  waitOptions?: waitForOptions
25
): Promise<T>;  // Waits up to 1000ms
26

27
// Plural element queries
28
function getAllBy*<T extends HTMLElement = HTMLElement>(
29
  container: HTMLElement,
30
  text: Matcher,
31
  options?: Options
32
): T[];  // Throws if 0 matches found
33

34
function queryAllBy*<T extends HTMLElement = HTMLElement>(
35
  container: HTMLElement,
36
  text: Matcher,
37
  options?: Options
38
): T[];  // Returns empty array if none found
39

40
function findAllBy*<T extends HTMLElement = HTMLElement>(
41
  container: HTMLElement,
42
  text: Matcher,
43
  options?: Options,
44
  waitOptions?: waitForOptions
45
): Promise<T[]>;  // Waits up to 1000ms
46
```
47

48
## Query by Role (Recommended)
49

50
Query by ARIA role - most accessible method.
51

52
```typescript
53
function getByRole<T extends HTMLElement = HTMLElement>(
54
  container: HTMLElement,
55
  role: ByRoleMatcher,
56
  options?: ByRoleOptions
57
): T;
58

59
interface ByRoleOptions {
60
  // Filter by accessible name (label, aria-label, aria-labelledby)
61
  name?: Matcher;
62
  
63
  // Filter by accessible description (aria-describedby)
64
  description?: Matcher;
65
  
66
  // Hidden elements
67
  hidden?: boolean;  // Default: false
68
  
69
  // ARIA states
70
  selected?: boolean;
71
  checked?: boolean;
72
  pressed?: boolean;
73
  expanded?: boolean;
74
  busy?: boolean;
75
  current?: boolean | string;
76
  
77
  // ARIA properties
78
  level?: number;  // For headings
79
  value?: {now?: number; min?: number; max?: number; text?: Matcher};
80
  
81
  // Other
82
  queryFallbacks?: boolean;  // Include elements without explicit role
83
  suggest?: boolean;  // Include query suggestions in errors
84
}
85

86
type ByRoleMatcher = ARIARole | string;
87
```
88

89
Examples:
90
```javascript
91
// Basic
92
getByRole(container, 'button');
93
getByRole(container, 'button', {name: /submit/i});
94

95
// States
96
getByRole(container, 'checkbox', {checked: true});
97
getByRole(container, 'tab', {selected: true});
98

99
// Properties
100
getByRole(container, 'heading', {level: 1});
101
getByRole(container, 'progressbar', {value: {now: 50, min: 0, max: 100}});
102

103
// Hidden elements
104
getByRole(container, 'alert', {hidden: true});
105
```
106

107
## Query by Label Text
108

109
Query form elements by associated label - recommended for forms.
110

111
```typescript
112
function getByLabelText<T extends HTMLElement = HTMLElement>(
113
  container: HTMLElement,
114
  text: Matcher,
115
  options?: SelectorMatcherOptions
116
): T;
117

118
interface SelectorMatcherOptions extends MatcherOptions {
119
  selector?: string;  // Narrow by selector (e.g., 'input[type="email"]')
120
  ignore?: boolean | string;  // CSS selectors to ignore
121
}
122
```
123

124
Examples:
125
```javascript
126
getByLabelText(container, 'Email');
127
getByLabelText(container, 'Email', {selector: 'input[type="email"]'});
128

129
// Matches <label>Email</label><input id="email" />
130
// And <input aria-label="Email" />
131
```
132

133
## Query by Placeholder Text
134

135
Query form elements by placeholder attribute.
136

137
```typescript
138
function getByPlaceholderText<T extends HTMLElement = HTMLElement>(
139
  container: HTMLElement,
140
  text: Matcher,
141
  options?: MatcherOptions
142
): T;
143
```
144

145
Examples:
146
```javascript
147
getByPlaceholderText(container, 'Search...');
148
getByPlaceholderText(container, /enter.*email/i);
149
```
150

151
## Query by Text
152

153
Query by visible text content - good for non-interactive elements.
154

155
```typescript
156
function getByText<T extends HTMLElement = HTMLElement>(
157
  container: HTMLElement,
158
  text: Matcher,
159
  options?: SelectorMatcherOptions
160
): T;
161
```
162

163
Examples:
164
```javascript
165
getByText(container, 'Welcome');
166
getByText(container, /error/i);
167
getByText(container, (content, el) => content.startsWith('Total:'));
168

169
// With selector
170
getByText(container, 'Submit', {selector: 'button'});
171

172
// Ignore elements
173
getByText(container, 'Content', {ignore: 'script, style'});
174
```
175

176
## Query by Display Value
177

178
Query form elements by current value.
179

180
```typescript
181
function getByDisplayValue<T extends HTMLElement = HTMLElement>(
182
  container: HTMLElement,
183
  value: Matcher,
184
  options?: MatcherOptions
185
): T;
186
```
187

188
Examples:
189
```javascript
190
getByDisplayValue(container, 'Hello World');  // Finds input/textarea with this value
191
getByDisplayValue(container, 'Option 1');  // Finds select with this option selected
192
```
193

194
## Query by Alt Text
195

196
Query images and other elements by alt attribute.
197

198
```typescript
199
function getByAltText<T extends HTMLElement = HTMLElement>(
200
  container: HTMLElement,
201
  text: Matcher,
202
  options?: MatcherOptions
203
): T;
204
```
205

206
Examples:
207
```javascript
208
getByAltText(container, 'Company logo');
209
getByAltText(container, /user avatar/i);
210
```
211

212
## Query by Title
213

214
Query by title attribute.
215

216
```typescript
217
function getByTitle<T extends HTMLElement = HTMLElement>(
218
  container: HTMLElement,
219
  text: Matcher,
220
  options?: MatcherOptions
221
): T;
222
```
223

224
Examples:
225
```javascript
226
getByTitle(container, 'More information');
227
getByTitle(container, /delete item/i);
228
```
229

230
## Query by Test ID (Last Resort)
231

232
Query by test ID attribute - only use when no better query is available.
233

234
```typescript
235
function getByTestId<T extends HTMLElement = HTMLElement>(
236
  container: HTMLElement,
237
  id: Matcher,
238
  options?: MatcherOptions
239
): T;
240

241
// Configure custom test ID attribute
242
configure({testIdAttribute: 'data-test-id'});
243
```
244

245
Examples:
246
```javascript
247
getByTestId(container, 'submit-button');
248

249
// With custom attribute
250
configure({testIdAttribute: 'data-cy'});
251
getByTestId(container, 'submit-button');  // Now looks for data-cy
252
```
253

254
## Matcher Options
255

256
Common options for matcher-based queries:
257

258
```typescript
259
interface MatcherOptions {
260
  exact?: boolean;  // Match exactly (default: false)
261
  trim?: boolean;  // Trim whitespace (default: true)
262
  collapseWhitespace?: boolean;  // Collapse whitespace (default: true)
263
  normalizer?: (text: string) => string;  // Custom text normalizer
264
  suggest?: boolean;  // Include query suggestions in errors
265
}
266
```
267

268
Examples:
269
```javascript
270
// Exact match
271
getByText(container, 'Submit', {exact: true});
272

273
// Custom normalizer
274
getByText(container, 'submit', {normalizer: str => str.toLowerCase()});
275

276
// Disable whitespace normalization
277
getByText(container, 'Text with  multiple  spaces', {
278
  collapseWhitespace: false
279
});
280
```
281

282
## Matcher Types
283

284
```typescript
285
type Matcher = string | RegExp | number | MatcherFunction;
286

287
type MatcherFunction = (content: string, element: Element | null) => boolean;
288
```
289

290
Usage:
291
```javascript
292
// String
293
getByText(container, 'Text');
294

295
// Regex
296
getByText(container, /text/i);
297

298
// Number (converted to string)
299
getByText(container, 42);
300

301
// Function
302
getByText(container, (content, el) => {
303
  return content.includes('Total:') && el.tagName === 'SPAN';
304
});
305
```
306

307
## Common Patterns
308

309
### Asserting non-existence
310
```javascript
311
// Bad - throws error
312
getByText(container, 'Should not exist');
313

314
// Good - returns null if not found
315
expect(queryByText(container, 'Should not exist')).not.toBeInTheDocument();
316
```
317

318
### Waiting for multiple elements
319
```javascript
320
await waitFor(() => {
321
  expect(screen.getAllByRole('listitem')).toHaveLength(5);
322
});
323
```
324

325
### Narrow by container
326
```javascript
327
const form = screen.getByRole('form');
328
const email = within(form).getByLabelText('Email');
329
```
330

331