Cursor rule

1---
2description: Core Cypress testing principles — selector strategy, smart waiting, and spec organization. Apply when writing or reviewing Cypress E2E tests.
3globs:
4alwaysApply: false
5---
6# Cypress Testing Fundamentals
7 
8## Core Testing Principles
9- **Reliable Selectors**: Use data attributes for stable element identification
10- **Smart Waits**: Leverage Cypress's automatic waiting capabilities
11- **Test Isolation**: Each test should be independent and repeatable
12- **Clear Assertions**: Write descriptive assertions that explain expected behavior
13 
14## Element Selection Excellence
15```javascript
16// ✅ Best Practice - Use data-cy attributes
17cy.get('[data-cy=login-button]').click()
18cy.get('[data-cy=username-input]').type('user@example.com')
19cy.get('[data-cy=password-input]').type('password123')
20 
21// ✅ Alternative - Use data-testid
22cy.get('[data-testid=submit-form]').click()
23 
24// ✅ Accessible selectors
25cy.get('[aria-label="Close dialog"]').click()
26cy.get('button').contains('Save Changes').click()
27 
28// ❌ Avoid - Brittle CSS selectors
29cy.get('.btn-primary.large-button:nth-child(2)').click() // Fragile
30cy.get('#dynamic-id-12345').type('text') // IDs may change
31```
32 
33## Smart Waiting Strategies
34```javascript
35// ✅ Wait for element to be visible and interactable
36cy.get('[data-cy=submit-button]')
37  .should('be.visible')
38  .and('not.be.disabled')
39  .click()
40 
41// ✅ Wait for specific content
42cy.get('[data-cy=user-name]')
43  .should('contain.text', 'John Doe')
44 
45// ✅ Wait for element to disappear (loading states)
46cy.get('[data-cy=loading-spinner]').should('not.exist')
47 
48// ✅ Wait for API calls to complete
49cy.intercept('POST', '/api/users').as('createUser')
50cy.get('[data-cy=create-user-form]').submit()
51cy.wait('@createUser').then((interception) => {
52  expect(interception.response.statusCode).to.equal(201)
53})
54 
55// ✅ Custom wait conditions
56cy.get('[data-cy=dynamic-content]').should(($el) => {
57  expect($el).to.have.length.at.least(1)
58  expect($el.text()).to.match(/Expected Pattern/)
59})
60```
61 
62## Test Structure and Organization
63```javascript
64describe('User Authentication Flow', () => {
65  beforeEach(() => {
66    // Set up consistent test state
67    cy.visit('/login')
68    cy.clearLocalStorage()
69    cy.clearCookies()
70  })
71 
72  context('Valid Login Scenarios', () => {
73    it('should successfully log in with valid credentials', () => {
74      // Arrange
75      const userData = {
76        email: 'test@example.com',
77        password: 'validPassword123'
78      }
79 
80      // Act
81      cy.get('[data-cy=email-input]').type(userData.email)
82      cy.get('[data-cy=password-input]').type(userData.password)
83      cy.get('[data-cy=login-button]').click()
84 
85      // Assert
86      cy.url().should('include', '/dashboard')
87      cy.get('[data-cy=welcome-message]')
88        .should('be.visible')
89        .and('contain.text', 'Welcome back!')
90      
91      // Verify user data is loaded
92      cy.get('[data-cy=user-profile]')
93        .should('contain.text', userData.email)
94    })
95 
96    it('should remember user when "Remember me" is checked', () => {
97      cy.get('[data-cy=email-input]').type('test@example.com')
98      cy.get('[data-cy=password-input]').type('password123')
99      cy.get('[data-cy=remember-me-checkbox]').check()
100      cy.get('[data-cy=login-button]').click()
101 
102      // Verify login success
103      cy.url().should('include', '/dashboard')
104 
105      // Simulate browser restart by clearing session
106      cy.clearCookies({ domain: null })
107      cy.visit('/login')
108 
109      // Verify user is still remembered
110      cy.get('[data-cy=email-input]')
111        .should('have.value', 'test@example.com')
112    })
113  })
114 
115  context('Invalid Login Scenarios', () => {
116    it('should display error for invalid credentials', () => {
117      cy.get('[data-cy=email-input]').type('invalid@example.com')
118      cy.get('[data-cy=password-input]').type('wrongPassword')
119      cy.get('[data-cy=login-button]').click()
120 
121      // Verify error handling
122      cy.get('[data-cy=error-message]')
123        .should('be.visible')
124        .and('contain.text', 'Invalid credentials')
125      
126      // Verify user stays on login page
127      cy.url().should('include', '/login')
128      
129      // Verify form state
130      cy.get('[data-cy=password-input]').should('have.value', '')
131      cy.get('[data-cy=email-input]').should('have.value', 'invalid@example.com')
132    })
133 
134    it('should validate required fields', () => {
135      // Test empty form submission
136      cy.get('[data-cy=login-button]').click()
137 
138      cy.get('[data-cy=email-error]')
139        .should('be.visible')
140        .and('contain.text', 'Email is required')
141 
142      cy.get('[data-cy=password-error]')
143        .should('be.visible')
144        .and('contain.text', 'Password is required')
145    })
146  })
147})
148```
149 
150## Advanced Assertions
151```javascript
152// ✅ Multiple assertions in sequence
153cy.get('[data-cy=product-card]')
154  .should('be.visible')
155  .and('contain.text', 'Product Name')
156  .and('have.class', 'available')
157  .find('[data-cy=price]')
158  .should('contain.text', '$29.99')
159 
160// ✅ Custom assertion functions
161cy.get('[data-cy=user-list]').should(($list) => {
162  expect($list).to.have.length.at.least(1)
163  expect($list.find('[data-cy=user-item]')).to.have.length.at.least(5)
164  
165  // Verify each user item has required elements
166  $list.find('[data-cy=user-item]').each((index, item) => {
167    expect(Cypress.$(item).find('[data-cy=user-name]')).to.exist
168    expect(Cypress.$(item).find('[data-cy=user-email]')).to.exist
169  })
170})
171 
172// ✅ Conditional assertions
173cy.get('body').then(($body) => {
174  if ($body.find('[data-cy=modal]').length > 0) {
175    cy.get('[data-cy=modal-close]').click()
176  }
177  
178  cy.get('[data-cy=main-content]').should('be.visible')
179})
180 
181// ✅ Retry assertions with custom timeout
182cy.get('[data-cy=dynamic-content]', { timeout: 15000 })
183  .should('exist')
184  .and('not.be.empty')
185```
186 
187## Test Data Management
188```javascript
189// ✅ Fixtures for test data
190cy.fixture('users.json').then((users) => {
191  const testUser = users.validUser
192  
193  cy.get('[data-cy=email-input]').type(testUser.email)
194  cy.get('[data-cy=password-input]').type(testUser.password)
195})
196 
197// ✅ Dynamic test data generation
198const generateTestUser = () => ({
199  email: `test+${Date.now()}@example.com`,
200  password: `testPass${Math.random().toString(36).substring(7)}`,
201  firstName: 'Test',
202  lastName: 'User'
203})
204 
205// ✅ Environment-specific data
206const getApiUrl = () => {
207  const env = Cypress.env('environment') || 'dev'
208  const urls = {
209    dev: 'https://api-dev.example.com',
210    staging: 'https://api-staging.example.com',
211    prod: 'https://api.example.com'
212  }
213  return urls[env]
214}
215```
216 
217## Performance Considerations
218```javascript
219// ✅ Efficient element queries
220cy.get('[data-cy=main-container]').within(() => {
221  // Scope queries to container for better performance
222  cy.get('[data-cy=search-input]').type('test query')
223  cy.get('[data-cy=search-button]').click()
224  cy.get('[data-cy=results-list]').should('exist')
225})
226 
227// ✅ Minimize unnecessary operations
228cy.visit('/dashboard', {
229  onBeforeLoad: (win) => {
230    // Disable analytics to speed up tests
231    win.analytics = { track: () => {} }
232  }
233})
234 
235// ✅ Use aliases to avoid re-querying
236cy.get('[data-cy=complex-form]').as('mainForm')
237cy.get('@mainForm').find('[data-cy=input-field]').type('value')
238cy.get('@mainForm').find('[data-cy=submit-button]').click()
239```
240