haven-cypress-integration/README.md

Seamless Cypress integration with HAVEN test case management

# Haven-Cypress Integration

Seamless integration between Cypress test frameworks and HAVEN test case management system.

## Quick Start

### 1. Install
```bash
npm install haven-cypress-integration
```

### 2. Add Tags to Tests
Add `@TC-AUTO-XXXX` tags to your test descriptions:

```javascript
it("Login test @TC-AUTO-123, @p2", () => {
  cy.visit('/login');
  cy.get('[data-cy=username]').type('user');
  cy.get('[data-cy=password]').type('pass');
  cy.get('[data-cy=submit]').click();
});

it("User registration @TC-AUTO-124, @p1", () => {
  cy.visit('/register');
  // your test code
});
```

### 3. Cypress Configuration (Optional Simplification)
The library automatically configures mochawesome reporting. You can use a simplified `cypress.config.js`:

```javascript
const { defineConfig } = require("cypress");

module.exports = defineConfig({
  video: false,
  e2e: {
    supportFile: "cypress/support/e2e.js",
    setupNodeEvents(on, config) {
      // Haven-cypress automatically handles:
      // - mochawesome reporter configuration  
      // - grep functionality for tag filtering
      // - proper environment variables
      return config;
    },
  },
});
```

**Note**: If you prefer to keep your existing cypress.config.js with manual mochawesome configuration, that's fine too! The library will respect your settings.

### 4. Build Docker Image
```bash
npx haven-cypress build --product=BE
```

### 5. Push to ECR and Deploy to Haven
```bash
npx haven-cypress build --product=BE --push
```
Your Docker image is now pushed to ECR and ready to be deployed and run by HAVEN!

## Commands

### Build Image
```bash
# Basic build with product organization
npx haven-cypress build --product=BE

# Custom tag with product
npx haven-cypress build --product=BE --tag=v1.0

# Build and push to ECR haven-test-images repository
npx haven-cypress build --product=BE --push

# Build and push with custom tag
npx haven-cypress build --product=BE --tag=v1.0 --push
```

### Run Tests
```bash
# Run all tests
npx haven-cypress run

# Run specific test cases
npx haven-cypress run --automationIds=TC-AUTO-123,TC-AUTO-124
```

### ECR Image Organization
Images are organized in the `haven-test-images` ECR repository with product-based versioning:
```
Repository: haven-test-images
├── BE-1.0.123456     (latest with build number)
├── BE-2.1.0          (semantic version)  
├── payments-1.0.789012
└── auth-3.0.0
```

**Tag Format**: `{PRODUCT}-{VERSION}`
- **Product**: Organizes images by product/team
- **Version**: Semantic versioning (e.g., `2.1.0`) or build numbers (e.g., `1.0.123456`)

### Versioning Examples

**Using package.json version (Recommended):**
```json
// package.json
{
  "version": "2.1.0"
}
```
```bash
# Automatically uses package.json version
npx haven-cypress build --product=BE --push
→ ECR tag: BE-2.1.0
```

**Manual version override:**
```bash
# Override with custom semantic version
npx haven-cypress build --product=BE --tag=v3.0.0 --push
→ ECR tag: BE-3.0.0

npx haven-cypress build --product=BE --tag=3.0.0 --push
→ ECR tag: BE-3.0.0
```

**Fallback for missing package.json:**
```bash
# Falls back to build number if no package.json version found
BUILD_NUMBER=456 npx haven-cypress build --product=BE --push
→ ECR tag: BE-1.0.456
```

## What's Included

- ✅ **Tag-based test filtering** (`@TC-AUTO-XXXX`)
- ✅ **Product-based organization** (ECR repository management)
- ✅ **Automatic mochawesome configuration** (no manual setup required)
- ✅ **Mochawesome reporting** with screenshots
- ✅ **S3 artifact upload** (reports, logs, screenshots)
- ✅ **HAVEN API integration** (result synchronization)
- ✅ **ECR integration** (automatic push to haven-test-images repository)
- ✅ **Docker containerization** ready for HAVEN deployment

## How It Works

1. **Haven runs your container** with mounted configuration and environment variables
2. **Your tests run** with tag filtering based on automation IDs
3. **Results are generated** using Mochawesome reporting
4. **Artifacts are uploaded** to S3 for review
5. **Results sync back** to HAVEN via API integration

## Requirements

- Node.js 14+
- Docker or Podman
- Existing Cypress project
- AWS credentials configured (for ECR push)
- HAVEN access credentials (provided by Haven when container runs)

## Support

For issues or questions, contact your HAVEN administrator.