@scaffit/cypress

Cypress E2E testing setup with framework-specific configurations for Next.js, React, Vue, Angular, Svelte, Express, Fastify, Node.js projects.

Features

• Multi-framework support - Automatically detects your project framework
• E2E Testing - End-to-end testing capabilities
• Component Testing - Optional component testing support
• Browser options - Electron, Chrome, Firefox, Edge
• Coverage reporting - Optional code coverage with @cypress/code-coverage
• Visual testing - Optional visual regression testing
• Custom commands - Framework-specific custom commands
• CI/CD ready - Headless execution support

Installation

Option 1: Using Scaffit CLI (Recommended)

# Add Cypress scaffold (no installation needed!)
npx scaffit add cypress

Alternative: Global Installation

# Install CLI globally
npm install -g scaffit

# Add Cypress scaffold
scaffit add cypress

Option 2: Direct npm package usage

# Install scaffold directly
npm install @scaffit/cypress

# Use in your code
import { setupCypress, previewCypress } from '@scaffit/cypress';

// Setup Cypress with custom options
const result = await setupCypress({
  addTestScripts: true,
  addComponentTesting: false,
  addCoverage: false,
  addVisualTesting: false,
  browser: 'Chrome',
  projectRoot: './my-project'
});

// Preview changes before applying
const preview = await previewCypress({
  addTestScripts: true,
  addComponentTesting: false
});

Note: Both approaches require @scaffit/core to be installed (automatically handled).

Framework Support

Next.js

• Base URL: http://localhost:3000
• Custom commands for NextAuth.js
• API route testing support

React (Vite/CRA)

• Base URL: http://localhost:3000 or http://localhost:5173
• Component testing with React
• Custom login commands

Vue

• Base URL: http://localhost:3000 or http://localhost:5173
• Component testing with Vue
• Vue Test Utils integration

Angular

• Base URL: http://localhost:4200
• Angular-specific testing utilities

Svelte

• Base URL: http://localhost:5173
• Component testing with Svelte

Express/Fastify/Node.js

• Base URL: http://localhost:3000
• API testing support
• Request/Response validation

Configuration

The scaffold creates a cypress.config.ts file with framework-specific settings:

import { defineConfig } from 'cypress';

export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      // Add code coverage if enabled
      if (require('@cypress/code-coverage')) {
        require('@cypress/code-coverage/task')(on, config);
      }
      
      return config;
    },
    baseUrl: 'http://localhost:3000',
    specPattern: 'cypress/e2e/**/*.cy.{js,jsx,ts,tsx}',
    supportFile: 'cypress/support/e2e.ts',
    chromeWebSecurity: true,
    viewportWidth: 1280,
    viewportHeight: 720,
    video: true,
    screenshotOnRunFailure: true
  },
  component: {
    devServer: {
      framework: 'react',
      bundler: 'vite'
    },
    specPattern: 'cypress/component/**/*.cy.{js,jsx,ts,tsx}',
    supportFile: 'cypress/support/component.ts'
  }
});

Package.json Scripts

The scaffold adds these scripts to your package.json:

{
  "scripts": {
    "cypress:open": "cypress open",
    "cypress:run": "cypress run",
    "cypress:run:chrome": "cypress run --browser chrome",
    "cypress:run:firefox": "cypress run --browser firefox",
    "cypress:run:edge": "cypress run --browser edge",
    "cypress:open:component": "cypress open --component",
    "cypress:run:component": "cypress run --component"
  }
}

Directory Structure

cypress/
├── e2e/
│   └── example.cy.ts        # Example E2E test
├── fixtures/
│   └── example.json         # Test data fixtures
├── support/
│   ├── commands.ts          # Custom Cypress commands
│   ├── e2e.ts              # E2E support file
│   └── component.ts        # Component testing support (optional)
└── snapshots/
    ├── base/               # Visual test baselines (optional)
    └── diff/               # Visual test diffs (optional)

Browser Options

• Electron (default) - Built-in browser for fast testing
• Chrome - Popular choice, full dev tools support
• Firefox - Open source alternative
• Edge - Windows browser support

Optional Features

Component Testing

Enable component-level testing with framework-specific support:

npm run cypress:open:component

Coverage Reporting

Add code coverage with @cypress/code-coverage:

npm run cypress:run -- --coverage

Visual Testing

Add visual regression testing with @cypress/visual-regression:

npm run cypress:run -- --env visual=true

Usage

After installation:

1. Open Cypress Test Runner:

   npm run cypress:open

2. Run tests in headless mode:

   npm run cypress:run

3. Run tests in specific browser:

   npm run cypress:run:chrome
   npm run cypress:run:firefox
   npm run cypress:run:edge

4. Write your first E2E test:

   // cypress/e2e/homepage.cy.ts
   describe('Homepage', () => {
     it('should load successfully', () => {
       cy.visit('/');
       cy.contains('Welcome');
     });
   });

5. Use custom commands:

   // Login before testing
   cy.login('[email protected]', 'password');
      
   // Test authenticated routes
   cy.visit('/dashboard');
   cy.contains('Dashboard');
      
   // Logout
   cy.logout();

Custom Commands

The scaffold includes framework-specific custom commands:

• cy.login(email, password) - Login helper
• cy.logout() - Logout helper
• Framework-specific commands in cypress/support/commands.ts

CI/CD Integration

Run Cypress in CI/CD pipelines:

# GitHub Actions example
npm run cypress:run --headless --browser chrome

Best Practices

1. Organize tests by feature - Group related tests in folders
2. Use fixtures - Store test data in cypress/fixtures/
3. Page Object Model - Create reusable page objects
4. Custom commands - Add framework-specific helpers
5. Component testing - Test components in isolation
6. Visual regression - Catch UI regressions early
7. Coverage reports - Track test coverage over time

License

MIT