Best practices for selectors in Cypress - Framework Patterns

Framework Mode - Best practices for selectors

Folder Structure for Cypress Test Framework

cypress/
├── e2e/                  # Test files organized by feature or flow
│   ├── login.cy.js
│   ├── dashboard.cy.js
│   └── user-profile.cy.js
├── fixtures/             # Static test data files (JSON, etc.)
│   └── users.json
├── support/              # Custom commands and reusable utilities
│   ├── commands.js       # Custom Cypress commands
│   ├── selectors.js      # Central place for selectors
│   └── index.js          # Support file loaded before tests
cypress.config.js         # Cypress configuration file

Test Framework Layers

• Test Layer (cypress/e2e): Contains test scripts that use selectors to interact with the UI.
• Selectors Layer (cypress/support/selectors.js): Central file to store all selectors as variables or functions for reuse and maintainability.
• Commands Layer (cypress/support/commands.js): Custom commands that wrap common actions using selectors to simplify tests.
• Fixtures Layer (cypress/fixtures): Static data used in tests, separate from selectors.
• Configuration Layer (cypress.config.js): Defines environment settings, base URLs, and test options.

Configuration Patterns for Selectors

• Centralize selectors: Store selectors in cypress/support/selectors.js to avoid duplication and ease updates.
• Use data attributes: Prefer data-cy or data-test attributes in HTML for stable selectors unaffected by styling or layout changes.
• Environment-specific selectors: If selectors differ by environment, use environment variables in cypress.config.js to load correct selectors dynamically.
• Keep selectors simple and specific: Avoid overly complex CSS or XPath selectors to reduce flakiness.

Test Reporting and CI/CD Integration

• Use Cypress built-in reporter or integrate with mochawesome for detailed HTML reports showing passed/failed tests and screenshots.
• Configure CI pipelines (GitHub Actions, Jenkins, GitLab CI) to run Cypress tests on pull requests and merges.
• Fail fast on selector-related errors by adding explicit assertions on element existence before actions.
• Store screenshots and videos of test runs for debugging selector failures.

Best Practices for Selectors in Cypress

1. Use data attributes: Select elements by data-cy or data-test attributes to avoid brittle selectors tied to CSS or structure.
2. Centralize selectors: Keep all selectors in one file (selectors.js) to make maintenance easier.
3. Keep selectors simple and readable: Avoid long CSS chains or XPath; prefer unique, stable attributes.
4. Use custom commands: Wrap selector usage in commands to abstract complexity and improve test readability.
5. Validate selectors: Add assertions to check element presence before interacting to catch selector issues early.

Self Check

Where in this Cypress framework structure would you add a new selector for a "Submit" button on the login page?

Key Result

Centralize stable selectors using data attributes and organize them in a dedicated support file for maintainability and reliability.