0
# Vue Test Utils
1
2
Vue Test Utils is the official testing library for Vue.js 3 applications, providing essential utilities for mounting components, interacting with them, and making assertions in tests. It offers a comprehensive API for shallow and deep component rendering, DOM manipulation, event triggering, and component state inspection.
3
4
## Package Information
5
6
- **Package Name**: @vue/test-utils
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @vue/test-utils`
10
11
## Core Imports
12
13
```typescript
14
import { mount, shallowMount, VueWrapper, DOMWrapper } from "@vue/test-utils";
15
```
16
17
For CommonJS:
18
19
```javascript
20
const { mount, shallowMount, VueWrapper, DOMWrapper } = require("@vue/test-utils");
21
```
22
23
## Basic Usage
24
25
```typescript
26
import { mount } from "@vue/test-utils";
27
import MyComponent from "./MyComponent.vue";
28
29
// Mount a component
30
const wrapper = mount(MyComponent, {
31
props: { message: "Hello World" },
32
slots: {
33
default: "Slot content"
34
}
35
});
36
37
// Make assertions
38
expect(wrapper.text()).toContain("Hello World");
39
expect(wrapper.find('[data-test="button"]').exists()).toBe(true);
40
41
// Trigger events
42
await wrapper.find('button').trigger('click');
43
44
// Check emitted events
45
expect(wrapper.emitted('click')).toHaveLength(1);
46
47
// Update props
48
await wrapper.setProps({ message: "Updated message" });
49
```
50
51
## Architecture
52
53
Vue Test Utils is built around several key architectural patterns:
54
55
- **Mounting Functions**: `mount()` and `shallowMount()` create component instances with different rendering strategies
56
- **Wrapper Classes**: `VueWrapper` and `DOMWrapper` provide unified APIs for component and DOM interactions
57
- **Global Configuration**: Centralized `config` object for setting up global test environment
58
- **Type Safety**: Full TypeScript support with generic type preservation and element-specific typing
59
- **Plugin System**: Extensible architecture allowing custom wrapper functionality
60
61
## Capabilities
62
63
### Component Mounting
64
65
Core mounting functionality for creating testable Vue component instances with full control over props, slots, and environment.
66
67
```typescript { .api }
68
function mount<T>(
69
component: T,
70
options?: ComponentMountingOptions<T>
71
): VueWrapper<ComponentPublicInstance<T>>
72
73
function shallowMount<T>(
74
component: T,
75
options?: ComponentMountingOptions<T>
76
): VueWrapper<ComponentPublicInstance<T>>
77
```
78
79
[Component Mounting](./mounting.md)
80
81
### Vue Component Wrapper
82
83
The VueWrapper class provides methods for interacting with mounted Vue components, including prop manipulation, event testing, and component state inspection.
84
85
```typescript { .api }
86
class VueWrapper<T extends ComponentPublicInstance> extends BaseWrapper<Node> {
87
readonly vm: T;
88
props(): Record<string, any>;
89
props(key: string): any;
90
emitted(): Record<string, unknown[][]>;
91
emitted<T = unknown[]>(eventName: string): T[];
92
setData(data: Record<string, any>): Promise<void>;
93
setProps(props: Record<string, any>): Promise<void>;
94
setValue(value: any): Promise<void>;
95
unmount(): void;
96
}
97
```
98
99
[Vue Component Wrapper](./vue-wrapper.md)
100
101
### DOM Element Wrapper
102
103
The DOMWrapper class provides methods for interacting with DOM elements, including form manipulation, attribute testing, and CSS class verification.
104
105
```typescript { .api }
106
class DOMWrapper<T extends Node> extends BaseWrapper<T> {
107
setValue(value: any): Promise<void>;
108
}
109
```
110
111
[DOM Element Wrapper](./dom-wrapper.md)
112
113
### Global Configuration
114
115
Global configuration system for setting up consistent test environments, including component stubs, global properties, and wrapper plugins.
116
117
```typescript { .api }
118
interface Config {
119
global: {
120
stubs: Record<string, Component | boolean | string>;
121
provide: Record<string | symbol, any>;
122
components: Record<string, Component>;
123
config: Partial<AppConfig>;
124
directives: Record<string, Directive>;
125
mixins: ComponentOptions[];
126
mocks: Record<string, any>;
127
plugins: (app: App, ...options: any[]) => any;
128
renderStubDefaultSlot: boolean;
129
};
130
plugins: {
131
VueWrapper: Array<(wrapper: VueWrapper<any>) => void>;
132
DOMWrapper: Array<(wrapper: DOMWrapper<any>) => void>;
133
createStubs?: (
134
stubs: Record<string, any>,
135
shallow: boolean
136
) => Record<string, Component>;
137
};
138
}
139
140
const config: Config;
141
```
142
143
[Global Configuration](./configuration.md)
144
145
### Testing Utilities
146
147
Helper functions and utilities for common testing scenarios, including promise resolution, auto-cleanup, and server-side rendering.
148
149
```typescript { .api }
150
function flushPromises(): Promise<void>;
151
function enableAutoUnmount(hook: (callback: () => void) => void): void;
152
function disableAutoUnmount(): void;
153
function renderToString<T>(
154
component: T,
155
options?: ComponentMountingOptions<T>
156
): Promise<string>;
157
```
158
159
[Testing Utilities](./utilities.md)
160
161
## Type Definitions
162
163
Core interfaces and types for component mounting and wrapper functionality.
164
165
```typescript { .api }
166
interface ComponentMountingOptions<T> {
167
props?: ComponentProps<T>;
168
slots?: {
169
[K in keyof ComponentSlots<T>]:
170
| string
171
| VNode
172
| Component
173
| { template: string };
174
};
175
global?: GlobalMountOptions;
176
shallow?: boolean;
177
attachTo?: Element | string;
178
attrs?: Record<string, unknown>;
179
data?(): Record<string, unknown>;
180
}
181
182
interface GlobalMountOptions {
183
components?: Record<string, Component>;
184
config?: Partial<AppConfig>;
185
directives?: Record<string, Directive>;
186
mixins?: ComponentOptions[];
187
mocks?: Record<string, any>;
188
plugins?: Array<Plugin | [Plugin, ...any[]]>;
189
provide?: Record<string | symbol, any>;
190
stubs?: Stubs;
191
renderStubDefaultSlot?: boolean;
192
}
193
194
type Stubs = Record<string, Component | boolean | string> | string[];
195
196
interface FindComponentSelector {
197
ref?: string;
198
name?: string;
199
}
200
```