0
# Cypress Testing Library
1
2
Cypress Testing Library extends Cypress with DOM Testing Library query methods, providing simple and complete custom commands that encourage good testing practices. It enables developers to write tests that mirror how users interact with applications, focusing on accessibility and semantic HTML elements rather than implementation details.
3
4
## Package Information
5
6
- **Package Name**: @testing-library/cypress
7
- **Package Type**: npm
8
- **Language**: JavaScript with TypeScript definitions
9
- **Installation**: `npm install --save-dev @testing-library/cypress`
10
11
## Core Imports
12
13
To register all commands with Cypress:
14
15
```javascript
16
import '@testing-library/cypress/add-commands';
17
```
18
19
For configuration:
20
21
```javascript
22
import { configure } from '@testing-library/cypress';
23
```
24
25
CommonJS:
26
27
```javascript
28
require('@testing-library/cypress/add-commands');
29
```
30
31
## Basic Usage
32
33
```javascript
34
// Add to cypress/support/commands.js or cypress/support/e2e.js
35
import '@testing-library/cypress/add-commands';
36
37
// Use in tests
38
cy.findByText('Submit').click();
39
cy.findByLabelText('Email').type('user@example.com');
40
cy.findByRole('button', { name: 'Save' }).should('be.visible');
41
cy.findAllByTestId('product-card').should('have.length', 3);
42
43
// Configure DOM Testing Library options
44
cy.configureCypressTestingLibrary({
45
testIdAttribute: 'data-test-id'
46
});
47
```
48
49
## Architecture
50
51
Cypress Testing Library is built around several key concepts:
52
53
- **Automatic Command Generation**: All `find*` queries from @testing-library/dom are dynamically converted to Cypress commands
54
- **Semantic Queries**: Commands encourage testing based on how users interact with the UI (text, labels, roles) rather than implementation details
55
- **Cypress Integration**: Full integration with Cypress chaining, subjects, timeouts, and within() contexts
56
- **Error Preservation**: Meaningful error messages from DOM Testing Library are forwarded to Cypress
57
- **jQuery Compatibility**: Seamlessly handles both jQuery objects and DOM elements
58
59
## Capabilities
60
61
### Element Query Commands
62
63
All query commands support the same patterns: `findBy*` (single element) and `findAllBy*` (multiple elements). These commands automatically retry until elements are found or timeout occurs.
64
65
```javascript { .api }
66
// Text-based queries
67
findByText(id: Matcher, options?: SelectorMatcherOptions): Chainable<JQuery>;
68
findAllByText(id: Matcher, options?: SelectorMatcherOptions): Chainable<JQuery>;
69
70
// Label-based queries
71
findByLabelText(id: Matcher, options?: SelectorMatcherOptions): Chainable<JQuery>;
72
findAllByLabelText(id: Matcher, options?: SelectorMatcherOptions): Chainable<JQuery>;
73
74
// Placeholder queries
75
findByPlaceholderText(id: Matcher, options?: MatcherOptions): Chainable<JQuery>;
76
findAllByPlaceholderText(id: Matcher, options?: MatcherOptions): Chainable<JQuery>;
77
78
// Display value queries
79
findByDisplayValue(id: Matcher, options?: MatcherOptions): Chainable<JQuery>;
80
findAllByDisplayValue(id: Matcher, options?: MatcherOptions): Chainable<JQuery>;
81
82
// Alt text queries
83
findByAltText(id: Matcher, options?: MatcherOptions): Chainable<JQuery>;
84
findAllByAltText(id: Matcher, options?: MatcherOptions): Chainable<JQuery>;
85
86
// Title attribute queries
87
findByTitle(id: Matcher, options?: MatcherOptions): Chainable<JQuery>;
88
findAllByTitle(id: Matcher, options?: MatcherOptions): Chainable<JQuery>;
89
90
// Role-based queries
91
findByRole(id: ByRoleMatcher, options?: ByRoleOptions): Chainable<JQuery>;
92
findAllByRole(id: ByRoleMatcher, options?: ByRoleOptions): Chainable<JQuery>;
93
94
// Test ID queries
95
findByTestId(id: Matcher, options?: MatcherOptions): Chainable<JQuery>;
96
findAllByTestId(id: Matcher, options?: MatcherOptions): Chainable<JQuery>;
97
```
98
99
**Usage Examples:**
100
101
```javascript
102
// Text queries - find by visible text content
103
cy.findByText('Submit Form').click();
104
cy.findByText(/^Click here/i).should('be.visible');
105
cy.findAllByText('Delete').should('have.length', 3);
106
107
// Label queries - find form elements by their labels
108
cy.findByLabelText('Email Address').type('user@example.com');
109
cy.findByLabelText(/password/i).type('secret123');
110
cy.findAllByLabelText(/required/i).should('not.be.empty');
111
112
// Role queries - find by ARIA roles
113
cy.findByRole('button').click();
114
cy.findByRole('textbox', { name: /search/i }).type('query');
115
cy.findAllByRole('listitem').should('have.length.greaterThan', 0);
116
117
// Test ID queries - find by data-testid attributes
118
cy.findByTestId('login-form').should('be.visible');
119
cy.findAllByTestId(/^product-/i).should('have.length', 5);
120
121
// With options
122
cy.findByText('Loading...', { timeout: 10000 }).should('not.exist');
123
cy.findByText('Button', { container: cy.get('.modal') }).click();
124
```
125
126
### Configuration
127
128
Configure DOM Testing Library options through Cypress:
129
130
```javascript { .api }
131
/**
132
* Configure DOM Testing Library through Cypress
133
* @param config - Configuration options for DOM Testing Library
134
*/
135
configureCypressTestingLibrary(config: DTLConfiguration): Chainable<void>;
136
```
137
138
**Usage Examples:**
139
140
```javascript
141
// Change default test ID attribute
142
cy.configureCypressTestingLibrary({
143
testIdAttribute: 'data-test-id'
144
});
145
146
// Configure text normalization
147
cy.configureCypressTestingLibrary({
148
normalizer: getDefaultNormalizer({
149
trim: true,
150
collapseWhitespace: true
151
})
152
});
153
154
// Configure default hidden behavior
155
cy.configureCypressTestingLibrary({
156
defaultHidden: true
157
});
158
```
159
160
### Programmatic Configuration
161
162
Configure DOM Testing Library outside of tests:
163
164
```javascript { .api }
165
/**
166
* Configure DOM Testing Library options
167
* @param config - Configuration options
168
* @returns Configuration object
169
*/
170
function configure(config: DTLConfiguration): DTLConfiguration;
171
```
172
173
**Usage Examples:**
174
175
```javascript
176
import { configure } from '@testing-library/cypress';
177
178
// In cypress/support/e2e.js
179
configure({
180
testIdAttribute: 'data-test-id',
181
asyncUtilTimeout: 5000
182
});
183
```
184
185
### Advanced Usage Patterns
186
187
**Chaining with Previous Subjects:**
188
189
```javascript
190
// Find within a specific container
191
cy.get('.sidebar').findByText('Settings').click();
192
193
// Use within() for scoping
194
cy.get('.modal').within(() => {
195
cy.findByLabelText('Name').type('John Doe');
196
cy.findByRole('button', { name: 'Save' }).click();
197
});
198
199
// Container option
200
cy.get('.product-list').then($container => {
201
cy.findByText('Add to Cart', { container: $container }).click();
202
});
203
```
204
205
**Error Handling:**
206
207
```javascript
208
// Check for non-existence
209
cy.findByText('Error Message').should('not.exist');
210
211
// Handle multiple matches (findBy* commands will fail)
212
cy.findAllByText('Delete').should('have.length', 1);
213
214
// Timeout configuration
215
cy.findByText('Loading Complete', { timeout: 30000 }).should('exist');
216
```
217
218
## Types
219
220
```javascript { .api }
221
// Matcher types (from @testing-library/dom)
222
type Matcher = string | RegExp | ((content: string, element?: Element) => boolean);
223
type ByRoleMatcher = string;
224
225
// Cypress Testing Library specific options
226
interface CTLMatcherOptions extends Partial<Cypress.Timeoutable>, Partial<Cypress.Loggable> {
227
/** Container element to search within */
228
container?: Element | JQuery<Element>;
229
}
230
231
// Combined option types
232
type MatcherOptions = DTLMatcherOptions | CTLMatcherOptions;
233
type SelectorMatcherOptions = DTLSelectorMatcherOptions | CTLMatcherOptions;
234
type ByRoleOptions = DTLByRoleOptions | CTLMatcherOptions;
235
236
// DOM Testing Library configuration
237
interface DTLConfiguration {
238
/** Attribute used for test IDs (default: 'data-testid') */
239
testIdAttribute?: string;
240
/** Default timeout for async utilities */
241
asyncUtilTimeout?: number;
242
/** Text normalizer function */
243
normalizer?: (text: string) => string;
244
/** Default hidden element behavior */
245
defaultHidden?: boolean;
246
/** Custom get error message function */
247
getElementError?: (message: string | null, container: HTMLElement) => Error;
248
}
249
250
// Cypress command return type
251
type Chainable<T> = Cypress.Chainable<T>;
252
```
253
254
## Key Differences from DOM Testing Library
255
256
1. **No `query*` or `get*` commands**: Only `find*` and `findAllBy*` commands are available
257
2. **Cypress retry logic**: Commands automatically retry using Cypress' built-in retryability
258
3. **jQuery compatibility**: Handles both jQuery objects and DOM elements seamlessly
259
4. **Multiple element handling**: `findAllBy*` commands can return multiple elements (unlike DOM Testing Library's `getBy*`)
260
5. **Error forwarding**: DOM Testing Library error messages are preserved and forwarded to Cypress
261
6. **Container support**: All commands support a `container` option for scoping queries
262
7. **Timeout support**: All commands respect Cypress timeout options
263
264
## Best Practices
265
266
- Use `findBy*` when expecting exactly one element (will fail if multiple found)
267
- Use `findAllBy*` when expecting one or more elements
268
- Prefer semantic queries (`findByRole`, `findByLabelText`) over test IDs when possible
269
- Use `should('not.exist')` instead of `query*` commands to check for element absence
270
- Configure `testIdAttribute` consistently across your application
271
- Use `container` option or `within()` to scope queries to specific sections
272
- Leverage meaningful error messages by using descriptive matcher patterns