0
# Vue Testing Library
1

2
Vue Testing Library is a lightweight adapter built on top of DOM Testing Library and @vue/test-utils. It provides simple and complete Vue.js testing utilities that encourage good testing practices by focusing on testing components the way users interact with them.
3

4
## Package Information
5

6
- **Package Name**: @testing-library/vue
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install @testing-library/vue --save-dev`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  render, 
16
  screen, 
17
  fireEvent, 
18
  cleanup,
19
  waitFor,
20
  waitForElementToBeRemoved,
21
  within,
22
  configure,
23
  getConfig,
24
  prettyDOM,
25
  logRoles,
26
  getRoles
27
} from "@testing-library/vue";
28
```
29

30
For CommonJS:
31

32
```javascript
33
const { 
34
  render, 
35
  screen, 
36
  fireEvent, 
37
  cleanup,
38
  waitFor,
39
  waitForElementToBeRemoved,
40
  within,
41
  configure,
42
  getConfig,
43
  prettyDOM,
44
  logRoles,
45
  getRoles
46
} = require("@testing-library/vue");
47
```
48

49
All DOM Testing Library queries are also available:
50

51
```typescript
52
import {
53
  // Single element queries
54
  getByRole, getByLabelText, getByPlaceholderText, getByText,
55
  getByDisplayValue, getByAltText, getByTitle, getByTestId,
56
  
57
  // Multiple element queries  
58
  getAllByRole, getAllByLabelText, getAllByPlaceholderText, getAllByText,
59
  getAllByDisplayValue, getAllByAltText, getAllByTitle, getAllByTestId,
60
  
61
  // Null-returning queries
62
  queryByRole, queryByLabelText, queryByPlaceholderText, queryByText,
63
  queryByDisplayValue, queryByAltText, queryByTitle, queryByTestId,
64
  
65
  // Multiple null-returning queries
66
  queryAllByRole, queryAllByLabelText, queryAllByPlaceholderText, queryAllByText,
67
  queryAllByDisplayValue, queryAllByAltText, queryAllByTitle, queryAllByTestId,
68
  
69
  // Async queries
70
  findByRole, findByLabelText, findByPlaceholderText, findByText,
71
  findByDisplayValue, findByAltText, findByTitle, findByTestId,
72
  
73
  // Multiple async queries
74
  findAllByRole, findAllByLabelText, findAllByPlaceholderText, findAllByText,
75
  findAllByDisplayValue, findAllByAltText, findAllByTitle, findAllByTestId
76
} from "@testing-library/vue";
77
```
78

79
Automatic cleanup (no import needed):
80

81
```javascript
82
// Automatic cleanup is enabled by default
83
// Set VTL_SKIP_AUTO_CLEANUP=true to disable
84
```
85

86
## Basic Usage
87

88
```typescript
89
import { render, screen, fireEvent } from "@testing-library/vue";
90
import Button from "./Button.vue";
91

92
// Render a Vue component
93
const { getByRole } = render(Button, {
94
  props: { label: "Click me" }
95
});
96

97
// Query elements using DOM Testing Library queries
98
const button = screen.getByRole("button", { name: "Click me" });
99

100
// Simulate user interactions
101
await fireEvent.click(button);
102

103
// Assert behavior
104
expect(button).toBeInTheDocument();
105
```
106

107
## Architecture
108

109
Vue Testing Library follows the testing philosophy of DOM Testing Library, built around several key components:
110

111
- **Rendering System**: `render` function that mounts Vue components in a testing environment using @vue/test-utils
112
- **Query System**: Complete set of query functions inherited from DOM Testing Library for finding elements
113
- **Event System**: Vue-specific `fireEvent` implementation that handles Vue's async DOM updates
114
- **Screen Object**: Pre-bound queries for convenient element selection
115
- **Cleanup System**: Automatic component unmounting and DOM cleanup between tests
116

117
## Capabilities
118

119
### Component Rendering
120

121
Core functionality for rendering Vue components in tests with full control over props, slots, and mounting options.
122

123
```typescript { .api }
124
function render<C>(
125
  TestComponent: C,
126
  options?: RenderOptions<C>
127
): RenderResult;
128

129
interface RenderOptions<C> {
130
  props?: ComponentProps<C>;
131
  slots?: ExtractSlots<C>;
132
  container?: Element;
133
  baseElement?: Element;
134
  global?: {
135
    plugins?: any[];
136
    mixins?: any[];
137
    mocks?: Record<string, unknown>;
138
    provide?: Record<string | symbol, unknown>;
139
    components?: Record<string, Component>;
140
    directives?: Record<string, Directive>;
141
    stubs?: Record<string, any>;
142
    config?: {
143
      globalProperties?: Record<string, any>;
144
      optionMergeStrategies?: Record<string, any>;
145
    };
146
  };
147
}
148
```
149

150
[Component Rendering](./rendering.md)
151

152
### Element Queries
153

154
Complete set of query functions for finding elements by user-visible characteristics like role, text, and labels.
155

156
```typescript { .api }
157
// Single element queries (throw if no match)
158
function getByRole(role: string, options?: ByRoleOptions): HTMLElement;
159
function getByText(text: string | RegExp, options?: ByTextOptions): HTMLElement;
160
function getByLabelText(text: string | RegExp, options?: ByLabelTextOptions): HTMLElement;
161

162
// Single element queries (return null if no match)  
163
function queryByRole(role: string, options?: ByRoleOptions): HTMLElement | null;
164
function queryByText(text: string | RegExp, options?: ByTextOptions): HTMLElement | null;
165

166
// Async queries (wait for element to appear)
167
function findByRole(role: string, options?: ByRoleOptions): Promise<HTMLElement>;
168
function findByText(text: string | RegExp, options?: ByTextOptions): Promise<HTMLElement>;
169
```
170

171
[Element Queries](./queries.md)
172

173
### Event Simulation
174

175
Vue-specific event firing utilities that properly handle Vue's asynchronous DOM updates and form interactions.
176

177
```typescript { .api }
178
interface VueFireEventObject {
179
  (element: Element, event: Event): Promise<void>;
180
  click(element: Element, options?: MouseEventInit): Promise<void>;
181
  change(element: Element, options?: EventInit): Promise<void>;
182
  input(element: Element, options?: InputEventInit): Promise<void>;
183
  touch(element: Element): Promise<void>;
184
  update(element: Element, value?: string): Promise<void>;
185
}
186

187
declare const fireEvent: VueFireEventObject;
188
```
189

190
[Event Simulation](./events.md)
191

192
### Async Utilities
193

194
Utilities for waiting for asynchronous operations and DOM changes in Vue components.
195

196
```typescript { .api }
197
function waitFor<T>(
198
  callback: () => T | Promise<T>,
199
  options?: {
200
    container?: Element;
201
    timeout?: number;
202
    interval?: number;
203
    onTimeout?: (error: Error) => Error;
204
    mutationObserverOptions?: MutationObserverInit;
205
  }
206
): Promise<T>;
207

208
function waitForElementToBeRemoved<T>(
209
  element: Element | Element[] | (() => Element | Element[] | null),
210
  options?: {
211
    container?: Element;
212
    timeout?: number;
213
    interval?: number;
214
    onTimeout?: (error: Error) => Error;
215
    mutationObserverOptions?: MutationObserverInit;
216
  }
217
): Promise<void>;
218
```
219

220
[Async Utilities](./async.md)
221

222
### Configuration and Debugging
223

224
Configuration utilities and debugging helpers for customizing library behavior and troubleshooting tests.
225

226
```typescript { .api }
227
function configure(options: {
228
  testIdAttribute?: string;
229
  asyncUtilTimeout?: number;
230
  defaultHidden?: boolean;
231
  defaultIgnore?: string;
232
  showOriginalStackTrace?: boolean;
233
  throwSuggestions?: boolean;
234
}): void;
235

236
function getConfig(): {
237
  testIdAttribute: string;
238
  asyncUtilTimeout: number;
239
  defaultHidden: boolean;
240
  defaultIgnore: string;
241
  showOriginalStackTrace: boolean;
242
  throwSuggestions: boolean;
243
};
244

245
function prettyDOM(
246
  dom?: Element | HTMLDocument,
247
  maxLength?: number,
248
  options?: PrettyDOMOptions
249
): string | false;
250

251
function logRoles(container: HTMLElement, options?: { hidden?: boolean }): void;
252

253
function getRoles(container: HTMLElement): { [role: string]: HTMLElement[] };
254
```
255

256
### Auto-cleanup
257

258
Automatic component cleanup functionality that runs after each test to ensure test isolation.
259

260
```typescript { .api }
261
// Automatically imported cleanup - no manual setup required
262
// Controlled by VTL_SKIP_AUTO_CLEANUP environment variable
263
```
264

265
## Types
266

267
```typescript { .api }
268
interface RenderResult {
269
  container: Element;
270
  baseElement: Element;
271
  debug: (element?: Element | Element[], maxLength?: number) => void;
272
  unmount(): void;
273
  html(): string;
274
  emitted<T = unknown>(): Record<string, T[]>;
275
  emitted<T = unknown>(name?: string): T[];
276
  rerender(props: object): Promise<void>;
277
  // All query functions from DOM Testing Library
278
  getByRole: (role: string, options?: ByRoleOptions) => HTMLElement;
279
  queryByRole: (role: string, options?: ByRoleOptions) => HTMLElement | null;
280
  findByRole: (role: string, options?: ByRoleOptions) => Promise<HTMLElement>;
281
  // ... all other query functions
282
}
283

284
interface PrettyDOMOptions {
285
  highlight?: boolean;
286
  maxDepth?: number;
287
  min?: boolean;
288
  plugins?: any[];
289
  printFunctionName?: boolean;
290
  theme?: any;
291
}
292

293
interface ByRoleOptions {
294
  name?: string | RegExp;
295
  hidden?: boolean;
296
  description?: string | RegExp;
297
  expanded?: boolean;
298
  checked?: boolean;
299
  pressed?: boolean;
300
  selected?: boolean;
301
  level?: number;
302
  current?: boolean | string;
303
  exact?: boolean;
304
}
305

306
interface ByTextOptions {
307
  exact?: boolean;
308
  normalizer?: (text: string) => string;
309
  selector?: string;
310
}
311

312
interface ByLabelTextOptions {
313
  selector?: string;
314
  exact?: boolean;
315
  normalizer?: (text: string) => string;
316
}
317

318
interface ByPlaceholderTextOptions {
319
  exact?: boolean;
320
  normalizer?: (text: string) => string;
321
}
322

323
interface ByAltTextOptions {
324
  exact?: boolean;
325
  normalizer?: (text: string) => string;
326
}
327

328
interface ByTitleOptions {
329
  exact?: boolean;
330
  normalizer?: (text: string) => string;
331
}
332

333
interface ByDisplayValueOptions {
334
  exact?: boolean;
335
  normalizer?: (text: string) => string;
336
}
337

338
interface ByTestIdOptions {
339
  exact?: boolean;
340
  normalizer?: (text: string) => string;
341
}
342
```