0
# Query Helpers
1
2
Low-level utilities for building custom queries. Primarily for library authors.
3
4
## buildQueries
5
6
Generate all query variants (get/query/find + plural forms) from a single `queryAll` function.
7
8
```typescript
9
function buildQueries<Arguments extends any[]>(
10
queryAllBy: GetAllBy<Arguments>,
11
getMultipleError: GetErrorFunction<Arguments>,
12
getMissingError: GetErrorFunction<Arguments>
13
): BuiltQueryMethods<Arguments>;
14
15
type BuiltQueryMethods<Arguments extends any[]> = [
16
QueryBy<Arguments>, // queryBy variant
17
GetAllBy<Arguments>, // getAllBy variant
18
GetBy<Arguments>, // getBy variant
19
FindAllBy<Arguments>, // findAllBy variant
20
FindBy<Arguments> // findBy variant
21
];
22
```
23
24
Usage:
25
```javascript
26
import {buildQueries, queryAllByAttribute} from '@testing-library/dom';
27
28
// Create custom query for data-cy
29
const queryAllByDataCy = (container, id) =>
30
queryAllByAttribute('data-cy', container, id);
31
32
const getMultipleError = (c, id) => `Found multiple with data-cy="${id}"`;
33
const getMissingError = (c, id) => `Unable to find with data-cy="${id}"`;
34
35
const [
36
queryByDataCy,
37
getAllByDataCy,
38
getByDataCy,
39
findAllByDataCy,
40
findByDataCy,
41
] = buildQueries(queryAllByDataCy, getMultipleError, getMissingError);
42
43
// Use the queries
44
const element = getByDataCy(container, 'submit-button');
45
const maybe = queryByDataCy(container, 'optional');
46
const asyncEl = await findByDataCy(container, 'async-element');
47
```
48
49
## queryByAttribute
50
51
Query single element by any attribute.
52
53
```typescript
54
function queryByAttribute(
55
attribute: string,
56
container: HTMLElement,
57
id: Matcher,
58
options?: MatcherOptions
59
): HTMLElement | null;
60
```
61
62
Usage:
63
```javascript
64
const element = queryByAttribute('data-id', container, '123');
65
const link = queryByAttribute('href', container, '/about');
66
const element = queryByAttribute('data-name', container, 'test', {
67
exact: true
68
});
69
```
70
71
## queryAllByAttribute
72
73
Query all elements by any attribute.
74
75
```typescript
76
function queryAllByAttribute(
77
attribute: string,
78
container: HTMLElement,
79
id: Matcher,
80
options?: MatcherOptions
81
): HTMLElement[];
82
```
83
84
Usage:
85
```javascript
86
const elements = queryAllByAttribute('data-category', container, 'featured');
87
const links = queryAllByAttribute('href', container, /\/products\//);
88
```
89
90
## getElementError
91
92
Create standardized error for element queries.
93
94
```typescript
95
function getElementError(
96
message: string | null,
97
container: HTMLElement
98
): Error;
99
```
100
101
Usage:
102
```javascript
103
function customQuery(container, id) {
104
const elements = container.querySelectorAll(`[data-custom="${id}"]`);
105
106
if (elements.length === 0) {
107
throw getElementError(`Unable to find with data-custom="${id}"`, container);
108
}
109
110
if (elements.length > 1) {
111
throw getElementError(`Found multiple with data-custom="${id}"`, container);
112
}
113
114
return elements[0];
115
}
116
```
117
118
## Complete Custom Query Example
119
120
```javascript
121
import {buildQueries, queryAllByAttribute, within} from '@testing-library/dom';
122
123
// Step 1: Create queryAll function
124
const queryAllByDataTestAttr = (container, value, options) => {
125
return queryAllByAttribute('data-test', container, value, options);
126
};
127
128
// Step 2: Define error messages
129
const getMultipleError = (container, value) =>
130
`Found multiple with data-test="${value}"`;
131
const getMissingError = (container, value) =>
132
`Unable to find with data-test="${value}"`;
133
134
// Step 3: Build all variants
135
const [
136
queryByDataTest,
137
getAllByDataTest,
138
getByDataTest,
139
findAllByDataTest,
140
findByDataTest,
141
] = buildQueries(queryAllByDataTestAttr, getMultipleError, getMissingError);
142
143
// Step 4: Export
144
export {queryByDataTest, getAllByDataTest, getByDataTest,
145
findAllByDataTest, findByDataTest};
146
147
// Step 5: Use
148
const element = getByDataTest(document.body, 'submit-btn');
149
150
// Or with within
151
const customQueries = {
152
queryByDataTest, getAllByDataTest, getByDataTest,
153
findAllByDataTest, findByDataTest
154
};
155
const container = document.getElementById('app');
156
const {getByDataTest} = within(container, customQueries);
157
```
158
159
## Advanced: Complex Logic Queries
160
161
```javascript
162
import {buildQueries} from '@testing-library/dom';
163
164
// Query by computed style
165
const queryAllByColor = (container, color) => {
166
return Array.from(container.querySelectorAll('*')).filter(element => {
167
const style = window.getComputedStyle(element);
168
return style.color === color;
169
});
170
};
171
172
const [queryByColor, getAllByColor, getByColor, findAllByColor, findByColor] =
173
buildQueries(
174
queryAllByColor,
175
(c, color) => `Found multiple with color "${color}"`,
176
(c, color) => `Unable to find with color "${color}"`
177
);
178
179
// Use
180
const redElement = getByColor(container, 'rgb(255, 0, 0)');
181
```
182
183