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
```