DecTestFramework — Cypress CRUD Test Framework

This repository provides a reusable Cypress-based end-to-end testing framework focused on CRUD flows.

🎯 Purpose

This test framework aims to:

• Standardize CRUD test implementations through reusable contracts
• Reduce test code duplication via meta-driven approach
• Simplify adding new entity tests through clear patterns
• Maintain consistent test structure across the codebase

🧰 Technology Stack

• Cypress: Modern web testing framework
• TypeScript: Type-safe implementation
• Yarn: Package management for e2e tests
• Node.js: Runtime (>= 18 recommended)

📦 Prerequisites

• Node.js >= 18.x
• Yarn (latest stable)
• Cypress 13.x

📁 Framework Structure

e2e/
├── constants/                             # Shared constants and configuration
│   └── main.constants.ts
├── helpers/                              # Utility functions and helpers
│   ├── db.helper.ts                      # Database interaction helpers
│   └── example/
│       ├── dataToArray.helper.ts         # Data conversion utilities
│       ├── delete.db.helper.ts           # DB deletion helpers
│       └── insert.db.helper.ts           # DB insertion helpers
├── metaElements/                         # Reusable element definitions
│   └── read.metaelements.ts
├── metaModels/                          # Abstract CRUD model contracts
│   ├── create.metamodel.ts              # Base create operation contract
│   ├── delete.metamodel.ts              # Base delete operation contract
│   ├── read.metamodel.ts                # Base read operation contract
│   └── update.metamodel.ts              # Base update operation contract
├── metaPages/                           # Abstract page interaction contracts
│   ├── create.metaPage.ts              # Base create page workflow
│   ├── delete.metaPage.ts              # Base delete page workflow
│   ├── read.metaPage.ts                # Base read page workflow
│   └── update.metaPage.ts              # Base update page workflow
├── models/                             # Concrete model implementations
│   └── example/
│       ├── create.example.model.ts     # Example entity create model
│       ├── delete.example.model.ts     # Example entity delete model
│       ├── read.example.model.ts       # Example entity read model
│       └── update.example.model.ts     # Example entity update model
├── pageObjects/                        # Element selectors and mappings
│   ├── 00-main.elements.ts            # Common page elements
│   └── example/
│       └── example.elements.ts         # Example entity elements
├── pages/                             # Page interaction implementations
│   └── example/
│       ├── create.example.page.ts     # Example create page flows
│       ├── delete.example.page.ts     # Example delete page flows
│       ├── read.example.page.ts       # Example read page flows
│       └── update.example.page.ts     # Example update page flows
├── plugins/                           # Cypress plugins configuration
│   └── index.ts
├── seeders/                          # Database seeding scripts
│   ├── 01-basic.seeder.ts           # Base seeder setup
│   └── example/
│       └── example.seeder.ts         # Example entity seeder
├── support/                          # Test support and setup
│   ├── commands.ts                   # Custom Cypress commands
│   └── e2e.ts                       # Global test configuration
└── tests/                           # Test specifications
    └── example/
        ├── createExample.spec.ts     # Example create tests
        ├── deleteExample.spec.ts     # Example delete tests
        ├── readExample.spec.ts       # Example read tests
        └── updateExample.spec.ts     # Example update tests

🚀 Getting Started

Installation

1. Install root dependencies:

cd .\DecTestFramework
npm install

2. Install e2e dependencies:

cd e2e
yarn install

Running Tests

From repository root:

npm run run:full    # Run full test suite
npm run run:smoke   # Run smoke tests
npm run open        # Open Cypress UI

From e2e/ directory:

yarn run:full       # Run full suite
yarn run:smoke      # Run smoke tests
yarn open          # Open Cypress UI

Single spec run:

cd e2e
npx cypress run --spec "./tests/example/readExample.spec.ts"

Notes: CI scripts use --record with project key. For local debugging, prefer yarn open or cypress run without --record.

Creating CRUD Automated Tests

🔄 Layer Interaction

Contract flow:

• Pages: User actions ➡️ UI state

  • Input: field values, user actions
  • Output: UI state changes, navigation results

• Models: Data objects ➡️ Persistence state

  • Input: domain objects, entity IDs
  • Output: persisted state, DTOs

• Tests: Orchestration and verification

  • Setup: Use Models/Seeders for data prerequisites
  • Action: Execute UI flows via Pages
  • Verify: Assert results through UI and Models

Success criteria: Tests should follow given/when/then style and use models only for setup/verification that can't be done through UI.

📝 Creating New Tests

Follow these steps using example/ as template:

1. Copy meta patterns from e2e/models/example and e2e/pages/example
2. Create selectors in pageObjects/<entity>
3. Implement pages in pages/<entity>/*.page.ts
4. Add models in models/<entity>/*.model.ts
5. Write tests in tests/<entity>/*.spec.ts
6. Add seeders if needed in seeders/<entity>

Example references:

• Models: e2e/models/example/read.example.model.ts
• Pages: e2e/pages/example/create.example.page.ts
• Tests: e2e/tests/example/readExample.spec.ts

Quick Start Checklist

1. 🎯 Add selectors to pageObjects/<entity>/<entity>.elements.ts
2. 📄 Create page flows in pages/<entity>/*.page.ts
3. 🔧 Implement models in models/<entity>/*.model.ts
4. ✅ Write tests in tests/<entity>/*.spec.ts
5. 🚀 Run spec: npx cypress run --spec "./tests/<entity>/*.spec.ts"

🛠️ Development Tips

• Start with example specs (e2e/tests/example/*.spec.ts)
• Keep selectors in dedicated pageObjects
• Use models for data setup/teardown
• Run individual specs during development

🌱 Seeders & Helpers

Use the example seeder pattern:

• Base: e2e/helpers/db.helper.ts
• Example: e2e/seeders/example/example.seeder.ts

Configure via .env.e2e with your DB credentials.

🔌 Plugin System

Core extensions:

• plugins/index.ts: Plugin registration
• commands.ts: Custom Cypress commands
• e2e.ts: Global test setup

🤝 Contributing

• Follow example patterns
• Update e2e/package.json for dependencies
• Run yarn install after dependency changes
• Maintain folder structure

New Entity Files

For a new entity widget:

• 🎯 pageObjects/widget/widget.elements.ts
• 📄 pages/widget/create.widget.page.ts
• 🔧 models/widget/create.widget.model.ts
• ✅ tests/widget/createWidget.spec.ts
• 🌱 seeders/widget.widget.seeder.ts

❓ FAQ

• Q: Where are example tests?

  • A: See e2e/tests/example/*.spec.ts

• Q: How to run custom scripts?

  • A: Use yarn in e2e/ or npm run in root

🔍 Need More?

Available extensions:

• Checklist generator for new entities
• File scaffolding templates

Choose which you'd like added!