Cypress Testing Framework

Table of Contents

- Quick Start
- Overview
- What Makes This Framework Unique?
- Features
- Running Tests
- Standard Test Run
- Parallel Test Execution
- Environment-Specific Test Run
- Debug Mode
- GitHub Actions Workflow
- Documentation
- Troubleshooting

Quick Start

Create a new project from this template in seconds! The CLI offers two setup modes to match your needs:

$3

- Node.js (latest LTS version)
- npm or yarn
- Git

$3

``bash


Using npx (no installation required)

npx cypress-start my-project

Or install globally first

npm install -g cypress-start
cypress-start my-project
`

The CLI guides you through two setup modes:

#### 🎯 Mode 1: Full Setup (Recommended)

Complete framework with all features, tests, and data. Git initialized, dependencies auto-installed.
Best for: New standalone projects.

#### 📦 Mode 2: Specific Files

Cherry-pick modules (ESLint, Docs, Copilot, Parallel Runner, GitHub Actions, Docker) for existing projects.
Package.json updated automatically. Manual npm install required.
Best for: Adding features to existing projects.

`bash
cd my-project
npm run test # Run all tests
npm run test:parallel # Run tests in parallel
npm run lint # Run ESLint checks
npx cypress open # Open Cypress UI
`

$3

GitHub Template:

1. Click "Use this template" → "Create a new repository"
2. Clone: git clone https://github.com/YOUR-USERNAME/your-repo-name.git

Direct Clone:

`bash
git clone https://github.com/IvanZdanovich/cypress-start.git my-project
cd my-project
`

Post-Setup:

`bash
npm install # Installs dependencies and sets up pre-commit hooks
`

Copy cypress/sensitive-data/env-users.example.json to cypress/sensitive-data/dev-users.json for test credentials.

---

$3

| Feature | Full Setup | Specific Files |
|------------------------|------------------------|-------------------------|
| Target Use Case | New standalone project | Add to existing project |
| Test Files | ✅ Included | ❌ Not included |
| Test Data | ✅ Included | ❌ Not included |
| Module Selection | All modules | Choose modules |
| Git Initialization | ✅ Yes | ❌ No |
| NPM Install | ✅ Automatic | ❌ Manual |
| Package.json | ✅ Complete | ✅ Created or merged |
| Ready to Use | ✅ Immediately | After npm install |

---

Overview

Unlock rapid and reliable testing with framework, developed using Cypress and JavaScript. Designed to scale
effortlessly, it is suitable for projects of any size.
This framework includes examples of tests:

- Integration and E2E UI tests for the Swag Labs Demo application.
- Integration API tests Restful Booker API playground

!Alt text

---

What Makes This Framework Unique?

- No Abstractions: No redundant abstraction layers such as Page Object Models or BDD frameworks. The framework
provides a defined structure and naming conventions, using Gherkin syntax to make tests self-descriptive, readable,
and
understandable for non-technical personnel.
- Comprehensive Use Case Documentation: All business use cases are described in detail, regardless of their
automation status. This approach provides accurate coverage metrics, eliminates test gaps, and serves as a solid
source of truth
for the entire team.
- Scalability: The simple yet efficient approach makes the framework easily extendable for future needs.
- Maintainability: Clear project structure and comprehensive documentation for easy onboarding,
effortless maintenance, and test writing.
- Robustness: Designed with Cypress to handle complex test scenarios with ease.
- Lightweight and Easy Startup: Quick setup with minimal configuration. The low number of third-party dependencies
helps avoid conflicts and ensures fast build times.

---

Features

- Interactive CLI Setup: Two setup modes - Full Setup (complete framework) or Specific Files (cherry-pick modules)
- Parallel Test Execution: Run tests in parallel with configurable stream count (docs)
- Custom ESLint Rules: Enforces test structure and naming conventions (docs)
- Localization Testing: Multi-language test support (docs)
- Color Theme Testing: Multiple theme support via environment variables (docs)
- Centralized Selector Management: All selectors in one location for easy maintenance
- Pre-commit Quality Checks: Automated linting before every commit (docs)
- Comprehensive Documentation: Test writing guidelines, naming conventions, FAQ (docs)
- AI-Assisted Development: GitHub Copilot integration with ready-to-use instructions
- CI/CD Integration: GitHub Actions workflow with dynamic test filtering and Docker support

---

Running Tests

$3

To run tests with default settings in headless mode:

`bash
npm run test
`

$3

To run tests in parallel for faster execution:

`bash
# Default (3 parallel streams)
npm run test:parallel

# Custom stream count
PARALLEL_STREAMS=6 npm run test:parallel
`

See Parallel Execution Guide for detailed documentation.

$3

Run tests with specific environment parameters in headless mode:

Environment Parameters:

- LANGUAGE: Language code (default: en)
- TARGET_ENV: Target environment (default: dev)
- COLOUR_THEME: Color theme (default: default)
- BROWSER: Browser for execution (default: chrome)

Windows (PowerShell):

`powershell
$env:LANGUAGE="en"; $env:COLOUR_THEME="default"; $env:TARGET_ENV="qa"; $env:BROWSER="chrome"; npm run test
`

Windows (CMD):

`cmd
set LANGUAGE=en&& set COLOUR_THEME=default&& set TARGET_ENV=qa&& set BROWSER=chrome&& npm run test
`

macOS/Linux:

`bash
LANGUAGE=en COLOUR_THEME=default TARGET_ENV=dev BROWSER=chrome npm run test
`

$3

For interactive debugging with the Cypress UI:

Windows (PowerShell):

`powershell
$env:LANGUAGE="en"; $env:TARGET_ENV="dev"; $env:COLOUR_THEME="default"; npm run pretest; npx cypress open
`

Windows (CMD):

`cmd
set LANGUAGE=en&& set TARGET_ENV=dev&& set COLOUR_THEME=default&& npm run pretest&& npx cypress open
`

macOS/Linux:

`bash
LANGUAGE=en COLOUR_THEME=default npm run pretest && TARGET_ENV=dev caffeinate -i npx cypress open
`

---

$3

Automated CI/CD workflow with weekly scheduled runs or manual triggers:

Quick Start:

1. Go to Actions tab → Select "Weekly Cypress Tests"
2. Click "Run workflow" → Configure parameters → Click "Run workflow"

Available Parameters:

| Parameter | Options | Default |
|--------------------|---------------------------------|---------|
| language | en | en |
| target_env | dev | dev |
| colour_theme | default | default |
| parallel_streams | 1-6 | 3 |
| browser | electron, chrome, firefox, edge | chrome |
| test_scope | all, integration, e2e | all |
| test_type | all, api, ui | all |

Test Filtering Examples:

| Scope | Type | What Runs |
|-----------------|---------|----------------------------------|
| all | all | All tests in the workspace |
| all | api | All API tests (integration only) |
| all | ui | All UI tests (integration + e2e) |
| integration | all | All integration tests (api + ui) |
| integration | api | Integration API tests only |
| integration | ui | Integration UI tests only |
| e2e | all | All E2E tests |
| e2e | ui | E2E UI tests only |

Viewing Results: Check Actions tab for run status. Download artifacts (reports, screenshots, videos) after
completion.

---

Documentation

Test Development:

- Test Writing Guideline
- Naming Conventions
- FAQ

Features & Tools:

- Parallel Execution Guide
- Localization Testing
- Color Theme Testing
- Bug Tracking

Quality & Standards:

- Custom ESLint Rules
- Pre-commit Check
- Tagging Strategy

Git & Collaboration:

- Git Strategy
- Copilot Prompts
- Copilot Instructions
- Integration API Tests Instructions
- Integration UI Tests Instructions
- E2E UI Tests Instructions

---

Troubleshooting

$3

- Pretest script fails: Ensure you have the correct language and theme files in the appropriate directories.
- Test isolation issues: Check that testIsolation: false is set on the relevant describe blocks.
- Localization errors: Verify that the language file contains all required keys.
- ESLint errors: Run npm run lint to identify specific issues.

$3

To update all dependencies to their latest versions:

`bash
npx npm-check-updates -u
`

Then, reinstall the dependencies:

`bash
npm install
``