npm package: @scaffit/cypress
Description: Cypress E2E testing setup with framework-specific configurations for Next.js, React, Vue, Angular, Svelte, Express, Fastify, Node.js projects
Author: Santosh Hanumaiah Ranganatha
Latest version: 1.0.0

# @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)
```bash
# Add Cypress scaffold (no installation needed!)
npx scaffit add cypress
```

### Alternative: Global Installation
```bash
# Install CLI globally
npm install -g scaffit

# Add Cypress scaffold
scaffit add cypress
```

### Option 2: Direct npm package usage
```bash
# 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:

```typescript
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`:

```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:

```bash
npm run cypress:open:component
```

### Coverage Reporting
Add code coverage with `@cypress/code-coverage`:

```bash
npm run cypress:run -- --coverage
```

### Visual Testing
Add visual regression testing with `@cypress/visual-regression`:

```bash
npm run cypress:run -- --env visual=true
```

## Usage

After installation:

1. Open Cypress Test Runner:
   ```bash
   npm run cypress:open
   ```

2. Run tests in headless mode:
   ```bash
   npm run cypress:run
   ```

3. Run tests in specific browser:
   ```bash
   npm run cypress:run:chrome
   npm run cypress:run:firefox
   npm run cypress:run:edge
   ```

4. Write your first E2E test:
   ```typescript
   // cypress/e2e/homepage.cy.ts
   describe('Homepage', () => {
     it('should load successfully', () => {
       cy.visit('/');
       cy.contains('Welcome');
     });
   });
   ```

5. Use custom commands:
   ```typescript
   // Login before testing
   cy.login('user@example.com', '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:

```bash
# 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