Cypress Automation Framework

🚀 Overview

This Cypress automation framework is built for production-grade UI and API validation. It is designed to address common automation challenges such as flaky tests, brittle selectors, and hard-to-maintain flows by using a clear page object model, centralized locators, reusable commands, and environment-driven configuration.

🧠 Why This Framework

This framework is purpose-built for real-world engineering teams:

• Cypress is chosen for its fast feedback loop, native browser automation, and strong ecosystem.
• Modular structure keeps UI and API automation separated while still allowing reusable integration scenarios.
• Real-world scenarios (login, cart, checkout) show end-to-end coverage while supporting negative and stability cases.
• CI-friendly design supports both push and pull-request validation with artifact collection.

🏗️ Architecture

The repository is organized for clarity and scalability:

/config
  dev.json
  staging.json
  prod.json
/cypress
  /e2e
    /ui
    /api
  /pages
  /locators
  /fixtures
  /support
    apiCommands.js
    commands.js
    e2e.js
/reports
/utils
package.json
cypress.config.js
.github/workflows/test.yml

Folder purpose

• cypress/e2e/ui: End-to-end UI scenarios built with page objects.
• cypress/e2e/api: API validation suites and integration checks.
• cypress/pages: Page object model implementation for UI flows.
• cypress/locators: Centralized selectors and locator strategy.
• cypress/fixtures: Static test data for reusable scenarios.
• cypress/support: Custom commands, shared utilities, and global Cypress setup.
• config: Environment-specific values for dev, staging, and prod.
• reports: Generated Mochawesome reports, screenshots, and test artifacts.

⚙️ Key Features

• Page Object Model (POM) for clean UI tests
• UI + API automation in one framework
• Multi-environment support with --env config=dev|staging|prod
• CI/CD ready with GitHub Actions
• Reusable custom commands and API helpers
• Mochawesome HTML reporting and failure screenshots
• Retry support and no hard-coded waits

🎯 Locator Strategy

This framework uses a sustainable locator strategy:

• Prefer data-test or data-testid attributes wherever possible
• Avoid brittle structure-based selectors like deep CSS paths
• Keep selectors centralized in cypress/locators
• Let page objects expose actions, not raw selectors

Example locator file:

module.exports = {
  usernameInput: '[data-test="username"]',
  passwordInput: '[data-test="password"]',
  loginButton: '[data-test="login-button"]',
  errorMessage: '[data-test="error"]'
};

🔁 Test Strategy

The framework supports a balanced coverage strategy:

• E2E flow coverage: login, cart, checkout, navigation, search
• API validation: schema, CRUD, and backend health checks
• Negative scenarios: invalid checkout, login failure, missing input
• Stability focus: reusable commands, centralized state reset, and robust wait logic

⚡ CI/CD

GitHub Actions run the test suite on both pushes and pull requests. The workflow:

• installs dependencies with npm ci
• runs Cypress with the selected environment
• preserves generated artifacts, reports, and failure screenshots

▶️ How to Run

Install dependencies:

npm ci

Open Cypress locally:

npm run cypress:open

Run all tests in dev mode:

npm run cypress:run

Run staging tests:

npm run cypress:run:staging

Run a single spec:

npx cypress run --env config=dev --spec "cypress/e2e/ui/checkout.spec.js"

✅ Reporting

After execution:

• HTML report: reports/mochawesome/index.html
• artifacts: reports/mochawesome and cypress/screenshots

Proof of Successful Run

All specs passing (15/15) in Chrome run:

✨ Developer Experience

This framework is designed for fast onboarding:

• reusable page object methods
• centralized locators
• shared command library
• environment configuration
• consistent reporting and logging

🧾 Logging Strategy

• Step-level logs via cy.step(...) for scenario traceability.
• API request and response logs via cy.apiRequest(...) with method, URL, status, and duration.
• Structured logs are routed through Cypress task('log', ...) for readable CI output.

📌 Notes

• Keep UI selectors in cypress/locators.
• Keep test logic in cypress/e2e and UI interaction in cypress/pages.
• Use cy.clearAppState() in test setup for consistent UI isolation.
• Prefer data-test / data-testid over structural selectors.