فریم‌ورک تست Cypress

Cypress یک فریم‌ورک تست end-to-end (E2E) مدرن و منبع‌باز (open-source) برای برنامه‌های وب است که بر پایه JavaScript/TypeScript کار می‌کند. این ابزار به‌طور خاص برای تست رابط کاربری (UI) و رفتار واقعی برنامه‌های وب در مرورگر طراحی شده و جایگزین محبوب Selenium در بسیاری از پروژه‌ها شده است.

Cypress چیه؟

Cypress مستقیماً درون مرورگر (مثل Chrome،Engine) اجرا می‌شود و به جای استفاده از WebDriver (مثل Selenium)، کنترل کامل روی مرورگر و کد برنامه را دارد. این ویژگی باعث می‌شود:

• تست‌ها سریع‌تر باشند.
• دیباگ آسان‌تر باشد (با اسکرین‌شات، ویدیو و لاگ‌های دقیق).
• از Flake-y tests (تست‌های ناپایدار) کمتری داشته باشیم.

چه موقع از Cypress استفاده می‌شه؟

مزایای کلیدی Cypress

مثال ساده (تست ورود به سیستم)

describe('تست ورود', () => {
  it('ورود موفق با اطلاعات صحیح', () => {
    cy.visit('https://example.com/login')
    cy.get('#username').type('user@test.com')
    cy.get('#password').type('123456')
    cy.get('button[type="submit"]').click()
    cy.url().should('include', '/dashboard')
    cy.contains('خوش آمدید').should('be.visible')
  })
})

چه موقع نباید از Cypress استفاده کرد؟

خلاصه

Cypress = ابزار قدرتمند، سریع و کاربرپسند برای تست خودکار رابط کاربری وب
استفاده اصلی: تست E2E و Component در برنامه‌های مدرن وب (React, Vue, Angular و…)

اگر پروژه وب داری و می‌خوای تست‌های قابل اعتماد، سریع و قابل نگهداری داشته باشی — Cypress انتخاب عالیه.

در پروژه‌های Next.js و Angular می‌تونی به راحتی از Cypress برای تست End-to-End (E2E) و Component Testing استفاده کنی. در ادامه راهنمای کامل و عملی برای هر دو فریم‌ورک رو می‌بینی (با دستورات نصب، تنظیمات و مثال واقعی).

Cypress در پروژه Next.js

مرحله ۱: نصب Cypress

npm install cypress --save-dev
# یا با yarn
yarn add cypress --dev

مرحله ۲: راه‌اندازی اولیه

npx cypress open

این دستور:

• پوشه cypress/ رو ایجاد می‌کنه
• فایل‌های تنظیمات (cypress.config.ts) رو می‌سازه
• مرورگر Cypress رو باز می‌کنه

مرحله ۳: تنظیمات برای Next.js (مهم!)

در cypress.config.ts این تنظیمات رو اضافه کن:

import { defineConfig } from 'cypress'

export default defineConfig({
  e2e: {
    baseUrl: 'http://localhost:3000', // آدرس dev server Next.js
    setupNodeEvents(on, config) {
      // اختیاری: task برای کار با Node.js
    },
  },

  component: {
    devServer: {
      framework: 'next',
      bundler: 'webpack',
    },
  },
})

این تنظیمات به Cypress می‌گه که چطور Next.js رو اجرا کنه.

مرحله ۴: اجرای تست E2E

# در ترمینال جداگانه
npm run dev   # اجرای Next.js

# در ترمینال دیگر
npx cypress open   # یا npx cypress run

مثال: تست صفحه اصلی (pages/index.tsx)

// cypress/e2e/home.cy.ts
describe('صفحه اصلی', () => {
  it('باید عنوان درست نمایش دهد', () => {
    cy.visit('/')
    cy.contains('Welcome to Next.js').should('be.visible')
  })

  it('باید به صفحه درباره برود', () => {
    cy.visit('/')
    cy.get('a[href="/about"]').click()
    cy.url().should('include', '/about')
    cy.contains('About Page').should('be.visible')
  })
})

تست کامپوننت (Component Testing) در Next.js

1. یک فایل تست بساز: components/Button.cy.tsx

// components/Button.cy.tsx
import { Button } from '@/components/Button'

describe('Button Component', () => {
  it('باید کلیک شود و متن تغییر کند', () => {
    const onClick = cy.stub().as('clickHandler')
    cy.mount(<Button onClick={onClick}>کلیک کن</Button>)
    cy.contains('کلیک کن').click()
    cy.get('@clickHandler').should('have.been.called')
  })
})

2. در cypress.config.ts مطمئن شو که component فعال باشه.
3. اجرا:

npx cypress open --component

Cypress در پروژه Angular

مرحله ۱: نصب Cypress

ng add @cypress/schematic

این دستور به‌صورت خودکار:

• Cypress رو نصب می‌کنه
• تنظیمات رو به angular.json و cypress.config.ts اضافه می‌کنه
• فایل‌های نمونه می‌سازه

مرحله ۲: تنظیمات خودکار (اگر دستی می‌خوای)

در cypress.config.ts:

import { defineConfig } from 'cypress'

export default defineConfig({
  e2e: {
    baseUrl: 'http://localhost:4200', // آدرس Angular dev server
    supportFile: 'cypress/support/e2e.ts',
  },

  component: {
    devServer: {
      framework: 'angular',
      bundler: 'webpack',
    },
  },
})

مرحله ۳: اجرای تست

# ترمینال ۱
ng serve

# ترمینال ۲
npx cypress open
# یا
npx cypress run

مثال: تست صفحه لاگین

// cypress/e2e/login.cy.ts
describe('صفحه ورود', () => {
  beforeEach(() => {
    cy.visit('/login')
  })

  it('باید با اطلاعات صحیح وارد شود', () => {
    cy.get('[data-cy=username]').type('admin@test.com')
    cy.get('[data-cy=password]').type('123456')
    cy.get('[data-cy=submit]').click()

    cy.url().should('include', '/dashboard')
    cy.get('[data-cy=welcome]').should('contain', 'خوش آمدید')
  })
})

نکته: از data-cy به جای کلاس یا آیدی استفاده کن تا تست‌ها پایدار بمونن.

تست کامپوننت در Angular

// src/app/button/button.component.cy.ts
import { ButtonComponent } from './button.component'

describe('ButtonComponent', () => {
  it('باید کلیک شود', () => {
    const clickSpy = cy.spy().as('clickSpy')
    cy.mount(ButtonComponent, {
      componentProperties: {
        clicked: clickSpy
      }
    })

    cy.get('button').click()
    cy.get('@clickSpy').should('have.been.called')
  })
})

مقایسه سریع

اجرای در CI/CD (مثال GitHub Actions)

# .github/workflows/cypress.yml
name: Cypress Tests
on: [push]
jobs:
  cypress:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install dependencies
        run: npm ci
      - name: Run Next.js/Angular + Cypress
        run: |
          npm run dev & npx wait-on http://localhost:3000
          npx cypress run

نکات طلایی

منابع رسمی

• Next.js + Cypress: https://nextjs.org/docs/testing#cypress
• Angular + Cypress: https://cypress.io/angular