0
# DOM Element Wrapper
1

2
The DOMWrapper class provides methods for interacting with DOM elements, including form manipulation, attribute testing, CSS class verification, and event triggering.
3

4
## Capabilities
5

6
### Form Input Manipulation
7

8
Methods for setting values on various form input types with appropriate event triggering.
9

10
```typescript { .api }
11
/**
12
 * Set value on form inputs and emit appropriate events
13
 * Handles input, textarea, select, checkbox, and radio elements
14
 * Automatically calls appropriate internal methods based on element type
15
 * @param value - Value to set (string for text inputs, boolean for checkboxes)
16
 * @returns Promise that resolves after value is set and events are emitted
17
 */
18
setValue(value: any): Promise<void>;
19
```
20

21
**Usage Examples:**
22

23
```typescript
24
import { mount } from "@vue/test-utils";
25

26
const wrapper = mount(MyForm);
27

28
// Text input
29
await wrapper.find('input[type="text"]').setValue("Hello World");
30

31
// Email input
32
await wrapper.find('input[type="email"]').setValue("test@example.com");
33

34
// Textarea
35
await wrapper.find('textarea').setValue("Multi-line\ntext content");
36

37
// Checkbox - use setValue with boolean
38
await wrapper.find('input[type="checkbox"]').setValue(true);
39
await wrapper.find('input[type="checkbox"]').setValue(false);
40

41
// Radio button - use setValue with boolean  
42
await wrapper.find('input[type="radio"][value="option1"]').setValue(true);
43

44
// Select dropdown
45
await wrapper.find('select').setValue("option2");
46

47
// Note: setValue automatically handles different input types internally
48
```
49

50
### Element Querying
51

52
Methods for finding child elements and components within the DOM wrapper's scope.
53

54
```typescript { .api }
55
/**
56
 * Find all Vue components within this DOM element's scope
57
 * @param selector - Component selector (constructor, name, or ref)
58
 * @returns Array of VueWrapper instances for matched components
59
 */
60
findAllComponents(selector: FindAllComponentsSelector): VueWrapper<any>[];
61
```
62

63
**Usage Examples:**
64

65
```typescript
66
const wrapper = mount(MyComponent);
67
const containerDiv = wrapper.find('.container');
68

69
// Find components within the container
70
const childComponents = containerDiv.findAllComponents({ name: 'ChildComponent' });
71
expect(childComponents).toHaveLength(2);
72

73
// Find components by constructor
74
import SpecificComponent from "./SpecificComponent.vue";
75
const specificComponents = containerDiv.findAllComponents(SpecificComponent);
76
```
77

78
## Inherited Methods from BaseWrapper
79

80
DOMWrapper extends BaseWrapper and inherits all its methods for DOM querying and interaction:
81

82
### Element Selection
83

84
```typescript { .api }
85
/**
86
 * Find first matching element within this wrapper's scope
87
 * @param selector - CSS selector or component selector
88
 * @returns DOMWrapper for matched element
89
 */
90
find<T extends Node = Node>(selector: string): DOMWrapper<T>;
91

92
/**
93
 * Find all matching elements within this wrapper's scope
94
 * @param selector - CSS selector
95
 * @returns Array of DOMWrapper instances for matched elements
96
 */
97
findAll<T extends Node = Node>(selector: string): DOMWrapper<T>[];
98

99
/**
100
 * Find first matching Vue component within this wrapper's scope
101
 * @param selector - Component selector (ref, name, or constructor)
102
 * @returns VueWrapper for matched component
103
 */
104
findComponent(selector: FindComponentSelector): VueWrapper<any>;
105

106
/**
107
 * Find element or throw error if not found
108
 * @param selector - CSS selector
109
 * @returns DOMWrapper for matched element (guaranteed to exist)
110
 */
111
get<T extends Node = Node>(selector: string): DOMWrapper<T>;
112

113
/**
114
 * Find component or throw error if not found
115
 * @param selector - Component selector
116
 * @returns VueWrapper for matched component (guaranteed to exist)
117
 */
118
getComponent(selector: FindComponentSelector): VueWrapper<any>;
119
```
120

121
### Content Inspection
122

123
```typescript { .api }
124
/**
125
 * Get HTML content of the element including children
126
 * @returns HTML string with optional beautification
127
 */
128
html(): string;
129

130
/**
131
 * Get text content of the element and its children
132
 * @returns Plain text content
133
 */
134
text(): string;
135

136
/**
137
 * Get CSS classes of the element
138
 * @param className - Optional specific class to check
139
 * @returns Array of class names or boolean if className specified
140
 */
141
classes(): string[];
142
classes(className: string): boolean;
143

144
/**
145
 * Get HTML attributes of the element
146
 * @param key - Optional specific attribute to check
147
 * @returns Attributes object or specific attribute value
148
 */
149
attributes(): Record<string, string>;
150
attributes(key: string): string;
151
```
152

153
### Element State
154

155
```typescript { .api }
156
/**
157
 * Check if the element exists in the DOM
158
 * @returns true if element exists, false otherwise
159
 */
160
exists(): boolean;
161

162
/**
163
 * Check if the element is visible
164
 * Considers CSS display, visibility, and opacity properties
165
 * @returns true if element is visible, false otherwise
166
 */
167
isVisible(): boolean;
168
```
169

170
### Event Triggering
171

172
```typescript { .api }
173
/**
174
 * Trigger DOM events on the element
175
 * @param eventString - Event type (e.g., 'click', 'keydown', 'focus')
176
 * @param options - Event options and properties
177
 * @returns Promise that resolves after event is triggered and processed
178
 */
179
trigger(eventString: string, options?: TriggerOptions): Promise<void>;
180

181
interface TriggerOptions {
182
  /** Key code for keyboard events */
183
  keyCode?: number;
184
  /** Which key for keyboard events */
185
  which?: number;
186
  /** Key name for keyboard events */
187
  key?: string;
188
  /** Mouse button for mouse events */
189
  button?: number;
190
  /** Additional event properties */
191
  [key: string]: any;
192
}
193
```
194

195
**Usage Examples:**
196

197
```typescript
198
const wrapper = mount(MyComponent);
199

200
// Element querying
201
const button = wrapper.find('button');
202
const inputs = wrapper.findAll('input');
203
const childComponent = wrapper.findComponent({ name: 'ChildComponent' });
204

205
// Content inspection
206
expect(button.text()).toBe('Click me');
207
expect(button.html()).toContain('<span>');
208
expect(button.classes()).toContain('btn-primary');
209
expect(button.attributes('disabled')).toBe('true');
210

211
// Element state
212
expect(button.exists()).toBe(true);
213
expect(button.isVisible()).toBe(true);
214

215
// Event triggering
216
await button.trigger('click');
217
await wrapper.find('input').trigger('keydown', { key: 'Enter', keyCode: 13 });
218
await wrapper.find('form').trigger('submit');
219
```
220

221
## Type Safety Features
222

223
DOMWrapper provides TypeScript support for HTML and SVG elements:
224

225
```typescript { .api }
226
// HTML element specific typing
227
const input = wrapper.find<HTMLInputElement>('input');
228
input.element.value; // Typed as HTMLInputElement
229

230
const button = wrapper.find<HTMLButtonElement>('button');
231
button.element.disabled; // Typed as HTMLButtonElement
232

233
// SVG element typing
234
const circle = wrapper.find<SVGCircleElement>('circle');
235
circle.element.r; // Typed as SVGCircleElement
236
```
237

238
## Form Input Types Support
239

240
DOMWrapper's `setValue()` method supports various form input types:
241

242
```typescript
243
// Text inputs
244
await wrapper.find('input[type="text"]').setValue("text value");
245
await wrapper.find('input[type="email"]').setValue("user@example.com");
246
await wrapper.find('input[type="password"]').setValue("secret");
247
await wrapper.find('input[type="number"]').setValue("42");
248
await wrapper.find('input[type="url"]').setValue("https://example.com");
249

250
// Textarea
251
await wrapper.find('textarea').setValue("Multi-line content");
252

253
// Checkboxes and radio buttons
254
await wrapper.find('input[type="checkbox"]').setValue(true);
255
await wrapper.find('input[type="radio"]').setValue(true);
256

257
// Select elements
258
await wrapper.find('select').setValue("option-value");
259

260
// File inputs (limited support)
261
const fileInput = wrapper.find('input[type="file"]');
262
// File input setValue has limitations due to browser security
263
```
264

265
## Error Handling
266

267
DOMWrapper methods may throw errors in these scenarios:
268

269
- **Element Not Found**: When using `get()` with non-existent selector
270
- **Invalid Input Type**: When calling form methods on non-form elements
271
- **Event Trigger Failure**: When triggering events on elements that don't support them
272

273
```typescript
274
const wrapper = mount(MyComponent);
275

276
try {
277
  const element = wrapper.get('[data-test="required-element"]');
278
  await element.setValue("value");
279
} catch (error) {
280
  console.error("Element interaction failed:", error.message);
281
}
282
```