0
# Debugging Utilities
1
2
Inspect and debug DOM state during tests with formatted output and Testing Playground integration.
3
4
## prettyDOM
5
6
Get formatted string representation of the DOM.
7
8
```typescript
9
function prettyDOM(
10
dom?: Element | HTMLDocument,
11
maxLength?: number,
12
options?: PrettyDOMOptions
13
): string | false;
14
15
interface PrettyDOMOptions {
16
filterNode?: (node: Node) => boolean;
17
// Also includes all pretty-format options
18
}
19
```
20
21
Usage:
22
```javascript
23
import {prettyDOM, screen} from '@testing-library/dom';
24
25
// Pretty print entire body
26
console.log(prettyDOM());
27
28
// Specific element
29
const form = screen.getByRole('form');
30
console.log(prettyDOM(form));
31
32
// With custom filter
33
const output = prettyDOM(document.body, 10000, {
34
filterNode: (node) => node.nodeType === 1 // Only elements
35
});
36
37
// In test assertions
38
const button = screen.queryByRole('button');
39
if (!button) {
40
console.log('Current DOM:', prettyDOM());
41
throw new Error('Button not found');
42
}
43
```
44
45
## logDOM
46
47
Log formatted DOM directly to console.
48
49
```typescript
50
function logDOM(
51
dom?: Element | HTMLDocument,
52
maxLength?: number,
53
options?: PrettyDOMOptions
54
): void;
55
```
56
57
Usage:
58
```javascript
59
import {logDOM} from '@testing-library/dom';
60
61
// Log entire body
62
logDOM();
63
64
// Specific element
65
const modal = screen.getByRole('dialog');
66
logDOM(modal);
67
68
// With filter
69
logDOM(document.body, 10000, {
70
filterNode: (node) => node.nodeType === 1
71
});
72
```
73
74
## screen.debug
75
76
Screen object includes debug method.
77
78
```typescript
79
interface Screen {
80
debug(
81
element?: Element | HTMLDocument | Array<Element | HTMLDocument>,
82
maxLength?: number,
83
options?: PrettyDOMOptions
84
): void;
85
}
86
```
87
88
Usage:
89
```javascript
90
import {screen} from '@testing-library/dom';
91
92
// Debug entire document
93
screen.debug();
94
95
// Debug specific element
96
const form = screen.getByRole('form');
97
screen.debug(form);
98
99
// Debug multiple elements
100
const buttons = screen.getAllByRole('button');
101
screen.debug(buttons);
102
103
// In test
104
test('form validation', () => {
105
screen.debug(); // See initial state
106
fireEvent.submit(form);
107
screen.debug(); // See state after submit
108
});
109
```
110
111
## logTestingPlaygroundURL
112
113
Get URL to Testing Playground for query suggestions.
114
115
```typescript
116
interface Screen {
117
logTestingPlaygroundURL(element?: Element | HTMLDocument): string;
118
}
119
```
120
121
Usage:
122
```javascript
123
// Get URL for entire document
124
const url = screen.logTestingPlaygroundURL();
125
console.log('Open in browser:', url);
126
127
// For specific element
128
const container = screen.getByTestId('app');
129
const url = screen.logTestingPlaygroundURL(container);
130
```
131
132
## Common Patterns
133
134
### Debugging Query Failures
135
136
```javascript
137
test('finds button', () => {
138
try {
139
screen.getByRole('button', {name: /submit/i});
140
} catch (error) {
141
screen.debug(); // Log current DOM
142
throw error;
143
}
144
});
145
```
146
147
### Debugging Element State
148
149
```javascript
150
const input = screen.getByLabelText('Email');
151
152
console.log('Initial state:');
153
screen.debug(input);
154
155
fireEvent.change(input, {target: {value: 'test@example.com'}});
156
157
console.log('After change:');
158
screen.debug(input);
159
```
160
161
### Debugging Async Updates
162
163
```javascript
164
fireEvent.click(screen.getByRole('button', {name: /load/i}));
165
166
console.log('After click:');
167
screen.debug();
168
169
await waitFor(() => {
170
expect(screen.getByText('Loaded')).toBeInTheDocument();
171
});
172
173
console.log('After load:');
174
screen.debug();
175
```
176
177
### Custom Debug Output
178
179
```javascript
180
function debugWithTime(element) {
181
console.log(`[${new Date().toISOString()}]`);
182
console.log(prettyDOM(element));
183
}
184
```
185
186