0
# Component Rendering
1

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

4
## Capabilities
5

6
### Render Function
7

8
Renders a Vue component for testing, returning utilities for querying and interacting with the rendered component.
9

10
```typescript { .api }
11
/**
12
 * Render a Vue component for testing
13
 * @param TestComponent - The Vue component to render
14
 * @param options - Rendering options including props, slots, and mounting configuration
15
 * @returns RenderResult with queries and utilities
16
 */
17
function render<C>(
18
  TestComponent: C,
19
  options?: RenderOptions<C>
20
): RenderResult;
21

22
interface RenderOptions<C> {
23
  /** Component props */
24
  props?: ComponentProps<C>;
25
  /** Component slots */
26
  slots?: ExtractSlots<C>;
27
  /** Custom container element to render in */
28
  container?: Element;
29
  /** Custom base element (parent of container) */
30
  baseElement?: Element;
31
  /** Global configuration for Vue Test Utils */
32
  global?: {
33
    /** Vue plugins to install */
34
    plugins?: any[];
35
    /** Global mixins */
36
    mixins?: any[];
37
    /** Global mocks */
38
    mocks?: Record<string, unknown>;
39
    /** Provide/inject values */
40
    provide?: Record<string | symbol, unknown>;
41
    /** Global components */
42
    components?: Record<string, Component>;
43
    /** Global directives */
44
    directives?: Record<string, Directive>;
45
    /** Component stubs */
46
    stubs?: Record<string, any>;
47
    /** Vue config options */
48
    config?: {
49
      globalProperties?: Record<string, any>;
50
      optionMergeStrategies?: Record<string, any>;
51
    };
52
  };
53
}
54
```
55

56
**Usage Examples:**
57

58
```typescript
59
import { render } from "@testing-library/vue";
60
import UserProfile from "./UserProfile.vue";
61

62
// Basic rendering with props
63
const { getByText } = render(UserProfile, {
64
  props: {
65
    name: "John Doe",
66
    email: "john@example.com"
67
  }
68
});
69

70
// Rendering with slots
71
const { getByRole } = render(UserProfile, {
72
  slots: {
73
    default: "<p>Custom content</p>",
74
    footer: "<button>Save</button>"
75
  }
76
});
77

78
// Rendering with global plugins
79
const { getByTestId } = render(UserProfile, {
80
  global: {
81
    plugins: [router, store],
82
    mocks: {
83
      $t: (key) => key // Mock i18n
84
    }
85
  }
86
});
87
```
88

89
### Cleanup Function
90

91
Unmounts all rendered components and cleans up the DOM. Automatically called after each test when using compatible test runners.
92

93
```typescript { .api }
94
/**
95
 * Unmount all rendered components and clean up DOM
96
 */
97
function cleanup(): void;
98
```
99

100
**Usage Example:**
101

102
```typescript
103
import { render, cleanup } from "@testing-library/vue";
104

105
// Manual cleanup (usually not needed)
106
afterEach(() => {
107
  cleanup();
108
});
109
```
110

111
### RenderResult Interface
112

113
Object returned by the render function containing utilities for interacting with the rendered component.
114

115
```typescript { .api }
116
interface RenderResult {
117
  /** Container element where component is mounted */
118
  container: Element;
119
  /** Base element (parent of container) */
120
  baseElement: Element;
121
  
122
  /** Debug function to print DOM structure */
123
  debug: (
124
    element?: Element | Element[],
125
    maxLength?: number,
126
    options?: PrettyFormatOptions
127
  ) => void;
128
  
129
  /** Unmount the component */
130
  unmount(): void;
131
  
132
  /** Get component HTML as string */
133
  html(): string;
134
  
135
  /** Get all emitted events */
136
  emitted<T = unknown>(): Record<string, T[]>;
137
  
138
  /** Get emitted events by name */
139
  emitted<T = unknown>(name?: string): T[];
140
  
141
  /** Update component props */
142
  rerender(props: object): Promise<void>;
143
  
144
  // All DOM Testing Library query functions
145
  getByRole(role: string, options?: ByRoleOptions): HTMLElement;
146
  queryByRole(role: string, options?: ByRoleOptions): HTMLElement | null;
147
  findByRole(role: string, options?: ByRoleOptions): Promise<HTMLElement>;
148
  getByText(text: string | RegExp, options?: ByTextOptions): HTMLElement;
149
  queryByText(text: string | RegExp, options?: ByTextOptions): HTMLElement | null;
150
  findByText(text: string | RegExp, options?: ByTextOptions): Promise<HTMLElement>;
151
  getByLabelText(text: string | RegExp, options?: ByLabelTextOptions): HTMLElement;
152
  queryByLabelText(text: string | RegExp, options?: ByLabelTextOptions): HTMLElement | null;
153
  findByLabelText(text: string | RegExp, options?: ByLabelTextOptions): Promise<HTMLElement>;
154
  getByPlaceholderText(text: string | RegExp, options?: ByPlaceholderTextOptions): HTMLElement;
155
  queryByPlaceholderText(text: string | RegExp, options?: ByPlaceholderTextOptions): HTMLElement | null;
156
  findByPlaceholderText(text: string | RegExp, options?: ByPlaceholderTextOptions): Promise<HTMLElement>;
157
  getByAltText(text: string | RegExp, options?: ByAltTextOptions): HTMLElement;
158
  queryByAltText(text: string | RegExp, options?: ByAltTextOptions): HTMLElement | null;
159
  findByAltText(text: string | RegExp, options?: ByAltTextOptions): Promise<HTMLElement>;
160
  getByTitle(text: string | RegExp, options?: ByTitleOptions): HTMLElement;
161
  queryByTitle(text: string | RegExp, options?: ByTitleOptions): HTMLElement | null;
162
  findByTitle(text: string | RegExp, options?: ByTitleOptions): Promise<HTMLElement>;
163
  getByDisplayValue(text: string | RegExp, options?: ByDisplayValueOptions): HTMLElement;
164
  queryByDisplayValue(text: string | RegExp, options?: ByDisplayValueOptions): HTMLElement | null;
165
  findByDisplayValue(text: string | RegExp, options?: ByDisplayValueOptions): Promise<HTMLElement>;
166
  getByTestId(testId: string, options?: ByTestIdOptions): HTMLElement;
167
  queryByTestId(testId: string, options?: ByTestIdOptions): HTMLElement | null;
168
  findByTestId(testId: string, options?: ByTestIdOptions): Promise<HTMLElement>;
169
  getAllByRole(role: string, options?: ByRoleOptions): HTMLElement[];
170
  queryAllByRole(role: string, options?: ByRoleOptions): HTMLElement[];
171
  findAllByRole(role: string, options?: ByRoleOptions): Promise<HTMLElement[]>;
172
  getAllByText(text: string | RegExp, options?: ByTextOptions): HTMLElement[];
173
  queryAllByText(text: string | RegExp, options?: ByTextOptions): HTMLElement[];
174
  findAllByText(text: string | RegExp, options?: ByTextOptions): Promise<HTMLElement[]>;
175
  getAllByLabelText(text: string | RegExp, options?: ByLabelTextOptions): HTMLElement[];
176
  queryAllByLabelText(text: string | RegExp, options?: ByLabelTextOptions): HTMLElement[];
177
  findAllByLabelText(text: string | RegExp, options?: ByLabelTextOptions): Promise<HTMLElement[]>;
178
  getAllByPlaceholderText(text: string | RegExp, options?: ByPlaceholderTextOptions): HTMLElement[];
179
  queryAllByPlaceholderText(text: string | RegExp, options?: ByPlaceholderTextOptions): HTMLElement[];
180
  findAllByPlaceholderText(text: string | RegExp, options?: ByPlaceholderTextOptions): Promise<HTMLElement[]>;
181
  getAllByAltText(text: string | RegExp, options?: ByAltTextOptions): HTMLElement[];
182
  queryAllByAltText(text: string | RegExp, options?: ByAltTextOptions): HTMLElement[];
183
  findAllByAltText(text: string | RegExp, options?: ByAltTextOptions): Promise<HTMLElement[]>;
184
  getAllByTitle(text: string | RegExp, options?: ByTitleOptions): HTMLElement[];
185
  queryAllByTitle(text: string | RegExp, options?: ByTitleOptions): HTMLElement[];
186
  findAllByTitle(text: string | RegExp, options?: ByTitleOptions): Promise<HTMLElement[]>;
187
  getAllByDisplayValue(text: string | RegExp, options?: ByDisplayValueOptions): HTMLElement[];
188
  queryAllByDisplayValue(text: string | RegExp, options?: ByDisplayValueOptions): HTMLElement[];
189
  findAllByDisplayValue(text: string | RegExp, options?: ByDisplayValueOptions): Promise<HTMLElement[]>;
190
  getAllByTestId(testId: string, options?: ByTestIdOptions): HTMLElement[];
191
  queryAllByTestId(testId: string, options?: ByTestIdOptions): HTMLElement[];
192
  findAllByTestId(testId: string, options?: ByTestIdOptions): Promise<HTMLElement[]>;
193
}
194
```
195

196
## Types
197

198
```typescript { .api }
199
type ComponentProps<C> = C extends new (...args: any) => any 
200
  ? InstanceType<C>['$props'] 
201
  : never;
202

203
type ExtractSlots<C> = {
204
  [K in keyof ComponentSlots<C>]?: ComponentSlots<C>[K] | VNodeChild
205
};
206

207
interface PrettyFormatOptions {
208
  callToJSON?: boolean;
209
  escapeRegex?: boolean;
210
  escapeString?: boolean;
211
  highlight?: boolean;
212
  indent?: number;
213
  maxDepth?: number;
214
  min?: boolean;
215
  plugins?: any[];
216
  printFunctionName?: boolean;
217
  theme?: any;
218
}
219
```