Cypress folder structure - Framework Patterns

Framework Mode - Cypress folder structure

Folder Structure

  cypress/
  ├── e2e/                  # End-to-end test files
  │   ├── login.cy.js       # Example test for login
  │   └── dashboard.cy.js   # Example test for dashboard
  ├── fixtures/             # Test data files (JSON, etc.)
  │   └── users.json        # Sample user data
  ├── support/              # Support files and custom commands
  │   ├── commands.js       # Custom Cypress commands
  │   ├── e2e.js            # Global setup for tests
  │   └── index.js          # Entry point for support
  ├── videos/               # Automatically saved test run videos
  └── screenshots/          # Automatically saved screenshots on failure

cypress.config.js           # Main Cypress configuration file
package.json                # Project dependencies and scripts
  

Test Framework Layers

• Test Layer (cypress/e2e): Contains the actual test scripts that simulate user actions and verify app behavior.
• Support Layer (cypress/support): Holds reusable code like custom commands and global hooks to keep tests clean and DRY.
• Fixtures Layer (cypress/fixtures): Stores static test data files used to feed tests with consistent inputs.
• Configuration Layer (cypress.config.js): Defines environment settings, base URLs, browser options, and other global settings.
• Output Layer (videos/screenshots): Automatically generated test run artifacts for debugging and reporting.

Configuration Patterns

Use cypress.config.js to manage settings like base URL, test retries, and viewport size.

Define environment variables inside cypress.config.js or via CLI to handle different environments (dev, staging, prod).

Example snippet to set base URL and environment variables:

  export default defineConfig({
    e2e: {
      baseUrl: 'https://example.com',
      env: {
        username: 'testuser',
        password: 'securePass123'
      },
      retries: 2,
      viewportWidth: 1280,
      viewportHeight: 720
    }
  })
  

Use Cypress.env() in tests to access these variables securely.

Test Reporting and CI/CD Integration

Integrate Cypress with CI/CD pipelines (GitHub Actions, Jenkins, GitLab CI) to run tests automatically on code changes.

Use built-in reporters or plugins like mochawesome for detailed HTML and JSON reports.

Configure video and screenshot capture on test failures to help diagnose issues quickly.

Example GitHub Actions step to run Cypress tests:

  - name: Run Cypress Tests
    uses: cypress-io/github-action@v5
    with:
      browser: chrome
      headless: true
  

Best Practices

• Keep tests independent: Each test should run alone without relying on others.
• Use custom commands: Put repeated actions in cypress/support/commands.js to avoid duplication.
• Organize tests by feature: Group related tests in folders inside cypress/e2e for clarity.
• Use fixtures for test data: Load data from cypress/fixtures to keep tests clean and maintainable.
• Configure retries and timeouts: Handle flaky tests gracefully with retries and proper waits.

Self Check

Question: Where in this folder structure would you add a new custom command to log in users?

Answer: Add it inside cypress/support/commands.js to reuse it across all tests.

Key Result

Organize Cypress tests with clear folders for tests, support code, fixtures, and config for maintainability and scalability.