GitHub - pkorolyshyn/cypress-ultimate-architecture: A complete, scalable Cypress testing framework showcasing best practices with Page Object Model, reusable element wrappers, step definitions, Allure reporting, ESLint + Prettier integration, Husky pre-commit hooks, environment configs, and clean CI-ready structure.

Cypress Ultimate Architecture is a ready-to-use, production-level Cypress test automation framework designed to kick-start your next QA automation project. It provides a clean, scalable structure that you can easily customize and extend according to your project’s needs.

🚀 Quick Start

git clone https://github.com/pkorolyshyn/cypress-ultimate-architecture.git
cd cypress-ultimate-architecture
npm install
npx cypress open

Happy Testing! 😊

Why Use This Framework?

This framework gives you a head-start by providing a scalable and flexible testing foundation, built on widely used best practices. It's designed for real projects—whether you're running small personal apps or scaling enterprise applications with thousands of tests.

Instead of struggling to figure out "the best way," you’ll immediately benefit from a proven, maintainable Cypress setup.

✨ Features Included:

🧩 Page Object Model (POM)
Clearly structured, maintainable tests—no messy selectors or repetitive logic.
Explore Pages →
🎯 Reusable Cypress Wrappers
Smart element wrappers help keep your tests clean and readable.
Explore Wrappers →
🐾 Steps Approach
Write high-level, reusable test steps, clearly separating logic from implementation details.
Explore Steps →
📊 Allure Test Reporting
Professional, interactive reports that make debugging easy (and your reports beautiful).
Explore Allure Report →
🌍 Flexible Environment Handling
Easily switch between testing environments—local, staging, production.
Explore Environment Handling →
🏷️ Cypress Grep Support
Run only the tests you need with flexible tagging.
Explore Grep Tags Usage Example →
🧹 Modern JavaScript Quality (ESLint + Prettier)
Maintain clean code standards automatically.
Explore ESLint Configuration →
Explore Prettier Configuration →
🐶 Git Hooks (Husky)
Automatically catch formatting and linting issues before they enter your repo.
Explore Husky pre-commit Hooks →
🐳 Dockerized CI (GitHub Actions)
A ready-to-go CI pipeline, generating reliable and consistent results for every commit.
Explore Dockerfile →

🧱Short Project Architecture Overview

This section explains how the framework is structured, what each folder or file is responsible for, and how it all connects. You can use this as a reference when modifying or extending the project.

ARCHITECTURE
│
├── .github/                 → GitHub Actions workflows (CI, Allure, Pages)
├── .husky/                  → Git hooks for linting/formatting before commits
│
├── cypress/
│   ├── components/          → Reusable UI parts (e.g., dialogs, header)
│   ├── core/                → Base classes for POM structure
│   │   ├── BaseObject.js          → Wrapper selector helpers
│   │   ├── BaseComponent.js       → Shared base for components
│   │   └── BasePage.js            → Abstract class for page objects
│   ├── downloads/           → Auto-generated downloaded files (e.g. CSV, PDF)
│   ├── e2e/                 → Actual Cypress test files
│   ├── fixtures/            → Static test data and style constants
│   ├── pages/               → Page objects (LoginPage, CalendarPage, etc.)
│   ├── steps/               → Reusable high-level test steps
│   └── support/
│       ├── elements/        → Reusable element wrappers
│       │   ├── SingleElement.js
│       │   ├── InputElement.js
│       │   └── MultiElement.js
│       ├── utils/           → Test utilities
│       │   ├── DateUtils.js
│       │   └── AllureMetaUtils.js
│       └── e2e.js           → Global setup (Allure, grep, log cleanup)
│
├── cypress.env1.js          → Environment-specific config (baseUrl, creds)
├── cypress.env2.js
├── .env                     → Example local secrets (⚠️ Do not commit real data)
├── Dockerfile               → Run Cypress + Allure in a container
├── eslint.config.js         → Code quality rules (Flat config)
├── .prettierrc              → Code formatting rules
├── package.json             → Project scripts, dependencies, metadata
└── README.md                → Project overview and documentation

`.github/`

Contains GitHub-specific configurations, including CI workflows like running Cypress tests, generating Allure reports, and publishing them to GitHub Pages.

This is where CI/CD magic happens.

`.husky/`

Git hook configurations using Husky. Runs automatic checks (like linting and formatting) before commits to keep the codebase clean.

`cypress/components/`

This folder contains reusable UI components used inside pages — like dialogs, modals, or headers. They’re composed inside pages/ to represent smaller parts of a full page.

`cypress/core/`

Core base classes shared across the framework.

BaseObject.js – Provides .select() and .selectInput() helpers to return wrapped Cypress elements.
BaseComponent.js – A minimal extension of BaseObject used for common logic component classes.
BasePage.js – The abstract class that all page objects inherit from. All common pages logic should be here.

`cypress/e2e/`

Your actual test files live here. Each test file corresponds to a feature or page and imports both:

Page objects (from pages/)
Step definitions (from steps/)

`cypress/fixtures/`

Static or shared test data. Can be used to store expected results, constants, styles, or mock API responses.

`cypress/pages/`

Contains Page Object classes. Each file represents a specific screen or route in the app, exposing elements and composed components for test use.

Examples:

LoginPage.js
CalendarPage.js
SmartTablePage.js

Each page extends BasePage and defines selectors + UI composition.

`cypress/steps/`

Reusable test steps organized by page or feature. They keep your test logic clean by hiding repetitive Cypress calls behind readable actions.

`cypress/support/`

Shared utilities and wrappers that enhance Cypress behavior.

`elements/`

Custom wrappers that add helpful assertion and action methods to elements.

SingleElement.js – Used for single DOM elements. Wraps Cypress methods.
InputElement.js – Extends SingleElement and adds input-specific helpers like .type() and .shouldHavePlaceholder().
MultiElement.js – Used for collections of elements (e.g., table rows). Wraps Cypress methods for working with multiple elements.

`utils/`

Project-wide helpers.

DateUtils.js – Formats or returns the current date.
AllureMetaUtils.js – A helper to inject Allure metadata like tags, severity, and ticket links for each test.

`.env`

✅ This file is committed only as an example. You should not commit real passwords or secrets.

It's used to demonstrate how you can manage environment-specific variables (like login credentials) locally via dotenv.

`cypress.env1.js / cypress.env2.js`

Configuration files for switching between environments (env1, env2, etc). Define your baseUrl, test user credentials, and any custom env values for Cypress.

You can run a specific config with:

npx cypress run --env envName=env2

`Dockerfile`

Defines a complete containerized environment for running Cypress and generating Allure reports in CI. Includes:

Cypress with browsers
Java (for Allure)
All dependencies and commands to run tests + generate reports

`eslint.config.js`

Configures ESLint with:

Prettier integration
Best practice rules
Cypress-specific linting
CI-friendly restrictions (e.g., no it.only)

It helps maintain consistent, high-quality code across the framework.

📊 Allure Reporting

This project uses Allure to generate clean, interactive, and shareable test reports after every Cypress run.

After each CI test run, the framework generates an Allure HTML report.
The report is attached as a downloadable artifact inside the GitHub Actions pipeline.
The same report is also published to the gh-pages branch so it’s viewable online.

🌐 Allure Live Demo:

⚙️ How Allure is Configured

Configuration (in `cypress.config.js`):

import { allureCypress } from 'allure-cypress/reporter';
import os from 'node:os';

export default {
  e2e: {
    setupNodeEvents(on, config) {
      allureCypress(on, config, {
        resultsDir: 'allure-results',
        environmentInfo: {
          os_platform: os.platform(),
          os_release: os.release(),
          os_version: os.version(),
          node_version: process.version,
          env: envName,
        },
      });

      return config;
    },
  },
};

Enabling Allure in Cypress (in `e2e.js`):

import 'allure-cypress';

📈 Making Reports Meaningful with Metadata

Instead of plain test names, each test can include rich metadata like feature name, story, ticket, tags, and severity using the helper utility:

AllureMetaUtils.js →

This utility simplifies adding metadata to tests. You just pass an object and call .apply():

import AllureMeta from '../support/utils/AllureMetaUtils';

it('calendar should display the current date as selected', () => {
  new AllureMeta({
    feature: 'Calendar',
    story: 'Default selected date should be today',
    ticket: 'CAL-101',
    tags: ['calendar', 'ui', 'smoke'],
    severity: 'critical',
  }).apply();

  // Test steps...
});

🖥️ Generating Report Locally

After running Cypress tests locally, you can manually generate the Allure report with:

npx allure generate --single-file --clean -o allure-report allure-results

This command will create a single HTML file inside the allure-report directory.

⚠️ Note: You need to have Java version 8 or above installed on your system to generate the report.

📚 Allure Installation Guide for Windows:

Allure CLI Installation (Official Docs)
For Windows-specific setup, ensure Java is installed and added to the PATH, then install Allure via:
```
scoop install allure
```

📁 Adding a New Environment

This framework supports running tests across multiple environments (e.g. dev, staging, production) using dynamic configuration files.

How to Add a New Environment

Create a new environment config file in the project root.

Example: cypress.myEnv.js
Populate it with environment-specific values:

// cypress.myEnv.js
import dotenv from 'dotenv';
dotenv.config();

export default {
  baseUrl: 'https://your-environment-url.com',
  env: {
    email: '[email protected]',
    password: process.env.MY_ENV_PASSWORD, // pulled from .env or GitHub Secret
    envName: 'myEnv',
    // Add any other custom environment variables here
  },
};

Store sensitive credentials like passwords in the .env file locally (do not commit them), use GitHub Secrets CI:

# .env
MY_ENV_PASSWORD=yourStrongPasswordHere!

Access these values anywhere in your test project using Cypress.env():

cy.get('input[type="email"]').type(Cypress.env('email'));

▶️ Run Tests on the New Environment

To execute tests using your new config:

npx cypress open --env envName=myEnv

Or run headlessly in CI:

npx cypress run --env envName=myEnv

The system will automatically load the correct baseUrl and env values from your cypress.myEnv.js file.

🔍 Running Tests with Cypress Grep

This project uses @cypress/grep plugin to filter and run only the tests you care about — based on tags defined in your specs.

Each test (or suite) can be tagged using the tags object in the test declaration:

describe('Calendar behavior', { tags: '@calendar' }, () => {
  it('should display the current date as selected', { tags: '@smoke' }, () => {
    // ...
  });
});

✅ Running Tagged Tests Locally

Use --env grepTags= to specify which tags you want to run.

Require Both Tags:

npx cypress run --env grepTags=@smoke+@calendar

Runs only tests that are tagged with both @smoke and @calendar.

OR Between Tags:

npx cypress run --env grepTags='@smoke @calendar'

Runs tests tagged with either @smoke or @calendar.

⚠️ Don’t forget quotes when using OR (space between tags).

Exclude Tags (Invert):

npx cypress run --env grepTags=-@calendar

Skips all tests tagged with @calendar.

Include and Exclude Tags:

npx cypress run --env grepTags=@smoke+-@calendar

Runs all @smoke tests excluding those also tagged with @calendar.

🚀 Running Tagged Tests in CI (GitHub Actions)

When triggering Cypress via GitHub Actions:

Go to the project’s Actions tab.
Choose the Cypress E2E Tests workflow.
Click "Run workflow".
In the "Cypress tags to run" input field, enter your desired grep tag(s) only.

✅ Example:

@smoke+@calendar

No need to include --env or any other flags — just the grep string itself.

🛠️ Additional Features

🔕 Optional: Hide XHR Logs in Cypress Command Log

Cypress logs every XHR, fetch, and new URL request in the command log, which can sometimes make it hard to focus on what actually matters during debugging.

💡 To reduce noise, this framework provides an easy toggle to hide XHR and request logs from the Cypress UI.

✅ How It Works

In e2e.js, this block dynamically injects CSS to hide specific log entries:

if (Cypress.config('hideXHRInCommandLog')) {
  const app = window.top;
  const doc = app?.document;

  if (doc && !doc.head.querySelector('[data-hide-command-log-request]')) {
    const style = doc.createElement('style');
    style.setAttribute('data-hide-command-log-request', '');
    style.textContent = `
      .command-name-request,
      .command-name-xhr,
      .command-name-new-url {
        display: none !important;
      }
    `;
    doc.head.appendChild(style);
  }
}

🧪 This injection only runs if the config flag is explicitly set.

⚙️ How to Enable

In your cypress.config.js, set the flag:

hideXHRInCommandLog: true;

🔁 By default, this option is set to false so you'll see everything.

🧼 Set it to true if you want cleaner logs — especially useful for visual debugging.

📁 Related Projects

🛠️ External Tools and Plugins

💛 Contributing

Contributions are welcome! If you’d like to improve this framework, feel free to fork it, create a branch, and open a pull request.

Some ideas you could help with:

Implement Allure history
Any advanced documentation
Add more extensive tests for Dialog, Calendar, Echarts, Smart Table, or Auth
Add MS Teams chat reporting integration
Add more data-testid selectors to the E-commerce page: https://github.com/pkorolyshyn/testing-env1
Or anything you think will be suitable and useful

Note: Please avoid writing tests for the E-commerce section — it is meant as a playground for users to try the framework and write their own tests.

If you’re unsure how to start, feel free to open an issue or discussion.

Check the full contribution guidelines here: CONTRIBUTING.md

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
.github		.github
.husky		.husky
cypress		cypress
.env		.env
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
cypress.config.js		cypress.config.js
cypress.env1.js		cypress.env1.js
cypress.env2.js		cypress.env2.js
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json

License

pkorolyshyn/cypress-ultimate-architecture

Folders and files

Latest commit

History

Repository files navigation

🚀 Quick Start

Why Use This Framework?

✨ Features Included:

🧱Short Project Architecture Overview

.github/

.husky/

cypress/components/

cypress/core/

cypress/e2e/

cypress/fixtures/

cypress/pages/

cypress/steps/

cypress/support/

elements/

utils/

.env

cypress.env1.js / cypress.env2.js

Dockerfile

eslint.config.js