Cursor rule

1---
2description: Advanced Cypress testing patterns and best practices — custom commands, page objects, and network testing
3globs: **/*.cy.js,**/*.cy.ts,**/cypress/**/*.js,**/cypress/**/*.ts
4alwaysApply: false
5---
6# Cypress Testing Excellence
7 
8## Modern Framework Architecture
9- **TypeScript Integration**: Full TypeScript support with intelligent intellisense
10- **Component Testing**: Isolated component testing alongside E2E scenarios
11- **Advanced Page Objects**: Modular page object patterns with inheritance
12- **Smart Fixture Management**: Dynamic test data with environment-aware loading
13 
14## Element Selection Revolution
15```javascript
16// Modern approach: Reliable, maintainable selectors
17cy.get('[data-cy=user-dashboard]')         // Preferred: Test-specific attributes
18  .find('[data-cy=profile-section]')       // Hierarchical selection
19  .within(() => {                          // Scoped interactions
20    cy.get('[data-cy=edit-button]').click()
21  })
22 
23// Avoid: Brittle selectors that break with UI changes
24// cy.get('.btn.btn-primary.user-btn')     // CSS classes
25// cy.get('#user-123-edit')                // Dynamic IDs
26```
27 
28## Advanced Custom Commands
29```javascript
30// Example: Intelligent login command with session management
31Cypress.Commands.add('loginAs', (userType, options = {}) => {
32  const { persist = true, skipWelcome = true } = options
33  
34  cy.session(userType, () => {
35    cy.visit('/login')
36    cy.fixture(`users/${userType}`).then(user => {
37      cy.get('[data-cy=email-input]').type(user.email)
38      cy.get('[data-cy=password-input]').type(user.password)
39      cy.get('[data-cy=login-button]').click()
40      
41      // Wait for successful authentication
42      cy.url().should('include', '/dashboard')
43      cy.get('[data-cy=user-avatar]').should('be.visible')
44    })
45  }, {
46    validate: () => {
47      // Verify session is still valid
48      cy.getCookie('auth-token').should('exist')
49    },
50    cacheAcrossSpecs: persist
51  })
52  
53  if (skipWelcome) {
54    cy.dismissWelcomeModal()
55  }
56})
57```
58 
59## Network Testing Mastery
60```javascript
61// Example: Comprehensive API testing with validation
62it('should handle user creation workflow', () => {
63  // Set up network intercepts
64  cy.intercept('POST', '/api/users', {
65    statusCode: 201,
66    body: { id: 'user-123', status: 'created' }
67  }).as('createUser')
68  
69  cy.intercept('GET', '/api/users/user-123', {
70    fixture: 'user-profile.json'
71  }).as('getUserProfile')
72  
73  // Perform user actions
74  cy.visit('/users/new')
75  cy.fillUserForm({
76    name: 'John Doe',
77    email: 'john@example.com',
78    role: 'admin'
79  })
80  cy.get('[data-cy=submit-button]').click()
81  
82  // Validate network interactions
83  cy.wait('@createUser').then(interception => {
84    expect(interception.request.body).to.deep.include({
85      name: 'John Doe',
86      email: 'john@example.com'
87    })
88  })
89  
90  cy.wait('@getUserProfile')
91  cy.get('[data-cy=success-message]').should('contain', 'User created successfully')
92})
93```
94 
95## Modern Test Organization
96```javascript
97// Example: Feature-based test organization with proper setup
98describe('User Management Feature', () => {
99  beforeEach(() => {
100    // Environment-aware setup
101    cy.setupTestEnvironment()
102    cy.loginAs('admin')
103    cy.navigateToUserManagement()
104  })
105  
106  context('User Creation', () => {
107    it('should create user with valid data', { tags: ['@smoke', '@user-management'] }, () => {
108      cy.createUser({
109        name: 'Test User',
110        email: 'test@example.com',
111        permissions: ['read', 'write']
112      })
113      
114      cy.verifyUserExists('test@example.com')
115      cy.verifyUserPermissions('test@example.com', ['read', 'write'])
116    })
117    
118    it('should validate required fields', { tags: ['@validation'] }, () => {
119      cy.get('[data-cy=create-user-button]').click()
120      cy.get('[data-cy=submit-button]').click()
121      
122      cy.get('[data-cy=name-error]').should('contain', 'Name is required')
123      cy.get('[data-cy=email-error]').should('contain', 'Email is required')
124    })
125  })
126  
127  context('User Permissions', () => {
128    beforeEach(() => {
129      cy.createTestUser('permissions-test-user')
130    })
131    
132    it('should update user permissions', { tags: ['@permissions'] }, () => {
133      cy.editUserPermissions('permissions-test-user', {
134        add: ['admin'],
135        remove: ['read']
136      })
137      
138      cy.verifyUserPermissions('permissions-test-user', ['write', 'admin'])
139    })
140  })
141})
142```
143 
144## Performance & Reliability Optimization
145```javascript
146// Example: Optimized waiting strategies
147Cypress.Commands.add('waitForStableDOM', (selector, options = {}) => {
148  const { timeout = 10000, interval = 100 } = options
149  
150  cy.get(selector, { timeout }).should('be.visible').then($el => {
151    const initialRect = $el[0].getBoundingClientRect()
152    
153    cy.wait(interval).then(() => {
154      cy.get(selector).then($newEl => {
155        const newRect = $newEl[0].getBoundingClientRect()
156        
157        if (initialRect.x !== newRect.x || initialRect.y !== newRect.y) {
158          cy.waitForStableDOM(selector, options) // Recursive wait
159        }
160      })
161    })
162  })
163})
164 
165// Usage in tests
166cy.waitForStableDOM('[data-cy=dynamic-content]')
167  .click() // Safe to interact after DOM is stable
168```
169 
170## Visual & Accessibility Testing
171```javascript
172// Example: Comprehensive visual regression testing
173it('should maintain visual consistency', () => {
174  cy.visit('/dashboard')
175  cy.loginAs('standard-user')
176  
177  // Wait for all content to load
178  cy.get('[data-cy=dashboard-content]').should('be.visible')
179  cy.waitForSkeletonLoading()
180  
181  // Visual regression test
182  cy.compareSnapshot('dashboard-layout', {
183    threshold: 0.02,
184    thresholdType: 'percent'
185  })
186  
187  // Accessibility validation
188  cy.checkA11y('[data-cy=main-content]', {
189    runOnly: {
190      type: 'tag',
191      values: ['wcag2a', 'wcag2aa']
192    }
193  })
194})
195```
196 
197## CI/CD Integration Excellence
198```javascript
199// cypress.config.js - Environment-aware configuration
200module.exports = defineConfig({
201  e2e: {
202    baseUrl: process.env.CYPRESS_BASE_URL || 'http://localhost:3000',
203    supportFile: 'cypress/support/e2e.js',
204    specPattern: 'cypress/e2e/**/*.cy.{js,ts}',
205    
206    // Advanced configuration
207    viewportWidth: 1280,
208    viewportHeight: 720,
209    video: process.env.CI,
210    screenshotOnRunFailure: true,
211    
212    // Performance optimizations
213    numTestsKeptInMemory: 0,
214    experimentalMemoryManagement: true,
215    
216    setupNodeEvents(on, config) {
217      // Plugin configuration
218      require('cypress-terminal-report/src/installLogsPrinter')(on)
219      require('@cypress/code-coverage/task')(on, config)
220      
221      // Environment-specific setup
222      config.env = {
223        ...config.env,
224        ...process.env
225      }
226      
227      return config
228    }
229  },
230  
231  component: {
232    devServer: {
233      framework: 'react',
234      bundler: 'webpack'
235    },
236    specPattern: 'src/**/*.cy.{js,ts,jsx,tsx}'
237  }
238})
239```
240 
241## Advanced Debugging & Maintenance
242- **Comprehensive Logging**: Detailed command logging with context
243- **Failure Analysis**: Automatic screenshot and video capture with timeline
244- **Performance Monitoring**: Test execution metrics and optimization recommendations
245- **Parallel Execution**: Intelligent test distribution across CI/CD pipeline stages
246