0
# Configuration
1
2
Configure global library behavior including test ID attributes, async timeouts, and error handling.
3
4
## configure
5
6
Set global configuration options.
7
8
```typescript
9
function configure(configDelta: ConfigFn | Partial<Config>): void;
10
11
type ConfigFn = (existingConfig: Config) => Partial<Config>;
12
13
interface Config {
14
testIdAttribute: string; // Default: 'data-testid'
15
asyncUtilTimeout: number; // Default: 1000ms
16
computedStyleSupportsPseudoElements: boolean;
17
defaultHidden: boolean; // Default: false
18
defaultIgnore: string;
19
showOriginalStackTrace: boolean; // Default: false
20
throwSuggestions: boolean; // Default: false
21
asyncWrapper(cb: (...args: any[]) => any): Promise<any>;
22
eventWrapper(cb: (...args: any[]) => any): void;
23
getElementError: (message: string | null, container: Element) => Error;
24
unstable_advanceTimersWrapper(cb: (...args: unknown[]) => unknown): unknown;
25
}
26
```
27
28
Usage:
29
```javascript
30
import {configure} from '@testing-library/dom';
31
32
// Change test ID attribute
33
configure({testIdAttribute: 'data-test-id'});
34
35
// Increase async timeout
36
configure({asyncUtilTimeout: 5000});
37
38
// Multiple options
39
configure({
40
testIdAttribute: 'data-cy',
41
asyncUtilTimeout: 3000,
42
showOriginalStackTrace: true
43
});
44
45
// Function form
46
configure((existingConfig) => ({
47
asyncUtilTimeout: existingConfig.asyncUtilTimeout * 2
48
}));
49
```
50
51
## getConfig
52
53
Get current configuration.
54
55
```typescript
56
function getConfig(): Config;
57
```
58
59
Usage:
60
```javascript
61
import {getConfig, configure} from '@testing-library/dom';
62
63
// Get current config
64
const config = getConfig();
65
console.log('Test ID:', config.testIdAttribute);
66
console.log('Timeout:', config.asyncUtilTimeout);
67
68
// Use current config for changes
69
const currentTimeout = getConfig().asyncUtilTimeout;
70
configure({asyncUtilTimeout: currentTimeout * 2});
71
```
72
73
## Configuration Options
74
75
### testIdAttribute
76
77
Change the attribute used for test ID queries.
78
79
```javascript
80
configure({testIdAttribute: 'data-test-id'});
81
const button = screen.getByTestId('submit'); // Looks for data-test-id
82
```
83
84
### asyncUtilTimeout
85
86
Set default timeout for async utilities.
87
88
```javascript
89
configure({asyncUtilTimeout: 5000});
90
const element = await screen.findByText('Content'); // Waits up to 5s
91
```
92
93
### defaultHidden
94
95
Include hidden elements by default in role queries.
96
97
```javascript
98
configure({defaultHidden: true});
99
const element = screen.getByRole('button'); // Includes hidden buttons
100
101
// Override per query
102
const visible = screen.getByRole('button', {hidden: false});
103
```
104
105
### defaultIgnore
106
107
Elements to ignore by default in text queries.
108
109
```javascript
110
configure({
111
defaultIgnore: 'script, style, [aria-hidden="true"]'
112
});
113
```
114
115
### showOriginalStackTrace
116
117
Include full stack traces in errors.
118
119
```javascript
120
configure({showOriginalStackTrace: true});
121
```
122
123
### throwSuggestions
124
125
Enable query suggestions in error messages.
126
127
```javascript
128
configure({throwSuggestions: true});
129
try {
130
screen.getByTestId('button');
131
} catch (error) {
132
// Error includes suggestion to use getByRole
133
}
134
```
135
136
## Common Patterns
137
138
### Global Setup
139
140
```javascript
141
// test-utils.js
142
import {configure} from '@testing-library/dom';
143
144
configure({
145
testIdAttribute: 'data-testid',
146
asyncUtilTimeout: 3000,
147
showOriginalStackTrace: true,
148
throwSuggestions: true
149
});
150
```
151
152
### Environment-Specific
153
154
```javascript
155
const isCI = process.env.CI === 'true';
156
157
configure({
158
asyncUtilTimeout: isCI ? 5000 : 1000,
159
showOriginalStackTrace: !isCI,
160
throwSuggestions: !isCI
161
});
162
```
163
164
### Per-Test Configuration
165
166
```javascript
167
test('slow test', async () => {
168
const originalTimeout = getConfig().asyncUtilTimeout;
169
170
configure({asyncUtilTimeout: 10000});
171
172
// ... test code
173
174
configure({asyncUtilTimeout: originalTimeout});
175
});
176
```
177
178