0
# Element Queries
1

2
Complete set of query functions for finding elements by user-visible characteristics like role, text, and labels. All queries are inherited from DOM Testing Library and work seamlessly with Vue components.
3

4
## Capabilities
5

6
### Query Types
7

8
Vue Testing Library provides three types of queries for each search method:
9

10
- **getBy\***: Returns element, throws error if not found or multiple found
11
- **queryBy\***: Returns element or null if not found, throws if multiple found
12
- **findBy\***: Returns Promise<Element>, waits for element to appear
13

14
### By Role Queries
15

16
Find elements by their accessible role. This is the recommended query method as it most closely matches how users and assistive technologies interact with elements.
17

18
```typescript { .api }
19
/**
20
 * Get element by ARIA role (recommended query method)
21
 * @param role - ARIA role name
22
 * @param options - Additional filtering options
23
 * @returns HTMLElement matching the role
24
 */
25
function getByRole(role: string, options?: ByRoleOptions): HTMLElement;
26
function queryByRole(role: string, options?: ByRoleOptions): HTMLElement | null;
27
function findByRole(role: string, options?: ByRoleOptions): Promise<HTMLElement>;
28
function getAllByRole(role: string, options?: ByRoleOptions): HTMLElement[];
29
function queryAllByRole(role: string, options?: ByRoleOptions): HTMLElement[];
30
function findAllByRole(role: string, options?: ByRoleOptions): Promise<HTMLElement[]>;
31

32
interface ByRoleOptions {
33
  /** Filter by accessible name */
34
  name?: string | RegExp;
35
  /** Include hidden elements */
36
  hidden?: boolean;
37
  /** Filter by description */
38
  description?: string | RegExp;
39
  /** Filter by expanded state */
40
  expanded?: boolean;
41
  /** Filter by checked state */
42
  checked?: boolean;
43
  /** Filter by pressed state */
44
  pressed?: boolean;
45
  /** Filter by selected state */
46
  selected?: boolean;
47
  /** Filter by level (for headings) */
48
  level?: number;
49
  /** Filter by current state */
50
  current?: boolean | string;
51
  /** Exact match for name */
52
  exact?: boolean;
53
}
54
```
55

56
**Usage Examples:**
57

58
```typescript
59
import { render, screen } from "@testing-library/vue";
60

61
// Find button by role
62
const button = screen.getByRole("button");
63
const submitButton = screen.getByRole("button", { name: "Submit" });
64

65
// Find heading by level
66
const mainHeading = screen.getByRole("heading", { level: 1 });
67

68
// Find checkbox by checked state
69
const checkedBox = screen.getByRole("checkbox", { checked: true });
70
```
71

72
### By Text Queries
73

74
Find elements by their text content.
75

76
```typescript { .api }
77
/**
78
 * Get element by text content
79
 * @param text - Text to search for (string or regex)
80
 * @param options - Additional options
81
 * @returns HTMLElement containing the text
82
 */
83
function getByText(text: string | RegExp, options?: ByTextOptions): HTMLElement;
84
function queryByText(text: string | RegExp, options?: ByTextOptions): HTMLElement | null;
85
function findByText(text: string | RegExp, options?: ByTextOptions): Promise<HTMLElement>;
86
function getAllByText(text: string | RegExp, options?: ByTextOptions): HTMLElement[];
87
function queryAllByText(text: string | RegExp, options?: ByTextOptions): HTMLElement[];
88
function findAllByText(text: string | RegExp, options?: ByTextOptions): Promise<HTMLElement[]>;
89

90
interface ByTextOptions {
91
  /** Exact text match */
92
  exact?: boolean;
93
  /** Ignore case when matching */
94
  normalizer?: (text: string) => string;
95
  /** Custom selector for container */
96
  selector?: string;
97
}
98
```
99

100
### By Label Text Queries
101

102
Find form elements by their associated label text.
103

104
```typescript { .api }
105
/**
106
 * Get form element by label text
107
 * @param text - Label text to search for
108
 * @param options - Additional options
109
 * @returns HTMLElement associated with the label
110
 */
111
function getByLabelText(text: string | RegExp, options?: ByLabelTextOptions): HTMLElement;
112
function queryByLabelText(text: string | RegExp, options?: ByLabelTextOptions): HTMLElement | null;
113
function findByLabelText(text: string | RegExp, options?: ByLabelTextOptions): Promise<HTMLElement>;
114
function getAllByLabelText(text: string | RegExp, options?: ByLabelTextOptions): HTMLElement[];
115
function queryAllByLabelText(text: string | RegExp, options?: ByLabelTextOptions): HTMLElement[];
116
function findAllByLabelText(text: string | RegExp, options?: ByLabelTextOptions): Promise<HTMLElement[]>;
117

118
interface ByLabelTextOptions {
119
  /** Custom selector for form elements */
120
  selector?: string;
121
  /** Exact text match */
122
  exact?: boolean;
123
  /** Text normalizer function */
124
  normalizer?: (text: string) => string;
125
}
126
```
127

128
### By Placeholder Text Queries
129

130
Find form elements by their placeholder text.
131

132
```typescript { .api }
133
/**
134
 * Get element by placeholder text
135
 * @param text - Placeholder text to search for
136
 * @param options - Additional options
137
 * @returns HTMLElement with matching placeholder
138
 */
139
function getByPlaceholderText(text: string | RegExp, options?: ByPlaceholderTextOptions): HTMLElement;
140
function queryByPlaceholderText(text: string | RegExp, options?: ByPlaceholderTextOptions): HTMLElement | null;
141
function findByPlaceholderText(text: string | RegExp, options?: ByPlaceholderTextOptions): Promise<HTMLElement>;
142
function getAllByPlaceholderText(text: string | RegExp, options?: ByPlaceholderTextOptions): HTMLElement[];
143
function queryAllByPlaceholderText(text: string | RegExp, options?: ByPlaceholderTextOptions): HTMLElement[];
144
function findAllByPlaceholderText(text: string | RegExp, options?: ByPlaceholderTextOptions): Promise<HTMLElement[]>;
145

146
interface ByPlaceholderTextOptions {
147
  /** Exact text match */
148
  exact?: boolean;
149
  /** Text normalizer function */
150
  normalizer?: (text: string) => string;
151
}
152
```
153

154
### By Alt Text Queries
155

156
Find elements (typically images) by their alt attribute.
157

158
```typescript { .api }
159
/**
160
 * Get element by alt text
161
 * @param text - Alt text to search for
162
 * @param options - Additional options
163
 * @returns HTMLElement with matching alt text
164
 */
165
function getByAltText(text: string | RegExp, options?: ByAltTextOptions): HTMLElement;
166
function queryByAltText(text: string | RegExp, options?: ByAltTextOptions): HTMLElement | null;
167
function findByAltText(text: string | RegExp, options?: ByAltTextOptions): Promise<HTMLElement>;
168
function getAllByAltText(text: string | RegExp, options?: ByAltTextOptions): HTMLElement[];
169
function queryAllByAltText(text: string | RegExp, options?: ByAltTextOptions): HTMLElement[];
170
function findAllByAltText(text: string | RegExp, options?: ByAltTextOptions): Promise<HTMLElement[]>;
171

172
interface ByAltTextOptions {
173
  /** Exact text match */
174
  exact?: boolean;
175
  /** Text normalizer function */
176
  normalizer?: (text: string) => string;
177
}
178
```
179

180
### By Title Queries
181

182
Find elements by their title attribute.
183

184
```typescript { .api }
185
/**
186
 * Get element by title attribute
187
 * @param text - Title text to search for
188
 * @param options - Additional options
189
 * @returns HTMLElement with matching title
190
 */
191
function getByTitle(text: string | RegExp, options?: ByTitleOptions): HTMLElement;
192
function queryByTitle(text: string | RegExp, options?: ByTitleOptions): HTMLElement | null;
193
function findByTitle(text: string | RegExp, options?: ByTitleOptions): Promise<HTMLElement>;
194
function getAllByTitle(text: string | RegExp, options?: ByTitleOptions): HTMLElement[];
195
function queryAllByTitle(text: string | RegExp, options?: ByTitleOptions): HTMLElement[];
196
function findAllByTitle(text: string | RegExp, options?: ByTitleOptions): Promise<HTMLElement[]>;
197

198
interface ByTitleOptions {
199
  /** Exact text match */
200
  exact?: boolean;
201
  /** Text normalizer function */
202
  normalizer?: (text: string) => string;
203
}
204
```
205

206
### By Display Value Queries
207

208
Find form elements by their current value.
209

210
```typescript { .api }
211
/**
212
 * Get form element by display value
213
 * @param text - Value to search for
214
 * @param options - Additional options
215
 * @returns HTMLElement with matching value
216
 */
217
function getByDisplayValue(text: string | RegExp, options?: ByDisplayValueOptions): HTMLElement;
218
function queryByDisplayValue(text: string | RegExp, options?: ByDisplayValueOptions): HTMLElement | null;
219
function findByDisplayValue(text: string | RegExp, options?: ByDisplayValueOptions): Promise<HTMLElement>;
220
function getAllByDisplayValue(text: string | RegExp, options?: ByDisplayValueOptions): HTMLElement[];
221
function queryAllByDisplayValue(text: string | RegExp, options?: ByDisplayValueOptions): HTMLElement[];
222
function findAllByDisplayValue(text: string | RegExp, options?: ByDisplayValueOptions): Promise<HTMLElement[]>;
223

224
interface ByDisplayValueOptions {
225
  /** Exact text match */
226
  exact?: boolean;
227
  /** Text normalizer function */
228
  normalizer?: (text: string) => string;
229
}
230
```
231

232
### By Test ID Queries
233

234
Find elements by their test ID attribute (use as last resort).
235

236
```typescript { .api }
237
/**
238
 * Get element by test ID (last resort)
239
 * @param testId - Test ID to search for
240
 * @param options - Additional options
241
 * @returns HTMLElement with matching test ID
242
 */
243
function getByTestId(testId: string, options?: ByTestIdOptions): HTMLElement;
244
function queryByTestId(testId: string, options?: ByTestIdOptions): HTMLElement | null;
245
function findByTestId(testId: string, options?: ByTestIdOptions): Promise<HTMLElement>;
246
function getAllByTestId(testId: string, options?: ByTestIdOptions): HTMLElement[];
247
function queryAllByTestId(testId: string, options?: ByTestIdOptions): HTMLElement[];
248
function findAllByTestId(testId: string, options?: ByTestIdOptions): Promise<HTMLElement[]>;
249

250
interface ByTestIdOptions {
251
  /** Exact match */
252
  exact?: boolean;
253
  /** Text normalizer function */
254
  normalizer?: (text: string) => string;
255
}
256
```
257

258
## Utility Objects
259

260
### Screen Object
261

262
Pre-bound queries for the entire document, eliminating the need to destructure from render results.
263

264
```typescript { .api }
265
/**
266
 * Screen object with all query functions bound to document.body
267
 */
268
declare const screen: {
269
  // All query functions
270
  getByRole(role: string, options?: ByRoleOptions): HTMLElement;
271
  queryByRole(role: string, options?: ByRoleOptions): HTMLElement | null;
272
  findByRole(role: string, options?: ByRoleOptions): Promise<HTMLElement>;
273
  getAllByRole(role: string, options?: ByRoleOptions): HTMLElement[];
274
  queryAllByRole(role: string, options?: ByRoleOptions): HTMLElement[];
275
  findAllByRole(role: string, options?: ByRoleOptions): Promise<HTMLElement[]>;
276
  // ... all other query functions
277
  
278
  // Debugging utilities
279
  debug(element?: Element | Element[], maxLength?: number): void;
280
  logTestingPlaygroundURL(element?: Element): void;
281
};
282
```
283

284
**Usage Example:**
285

286
```typescript
287
import { render, screen } from "@testing-library/vue";
288
import MyComponent from "./MyComponent.vue";
289

290
render(MyComponent);
291

292
// Use screen instead of destructuring from render result
293
const button = screen.getByRole("button");
294
const input = screen.getByLabelText("Email");
295
```
296

297
### Within Function
298

299
Create scoped queries bound to a specific element.
300

301
```typescript { .api }
302
/**
303
 * Get queries bound to a specific element
304
 * @param element - Element to bind queries to
305
 * @returns Object with all query functions scoped to the element
306
 */
307
function within(element: Element): {
308
  getByRole(role: string, options?: ByRoleOptions): HTMLElement;
309
  queryByRole(role: string, options?: ByRoleOptions): HTMLElement | null;
310
  // ... all other query functions
311
};
312
```
313

314
**Usage Example:**
315

316
```typescript
317
import { render, screen, within } from "@testing-library/vue";
318

319
const form = screen.getByRole("form");
320
const withinForm = within(form);
321

322
// Queries are now scoped to the form element
323
const submitButton = withinForm.getByRole("button", { name: "Submit" });
324
```