haven-cypress-integration

Seamless Cypress integration with HAVEN test case management. Advanced test execution with real-time monitoring and flexible configuration options.

Key Features

• Automatic report generation (Mochawesome HTML + JSON)
• Tag-based filtering using @TC-AUTO-XXXX and custom tags via @cypress/grep
• Environment support - Test against QA/DEV/CTE/PROD environments
• Custom tags support - Filter by @smoke, @regression, @p1, etc.
• Real-time log streaming to S3 during test execution
• Flexible test execution via custom E2E_COMMAND environment variable
• Enhanced automation ID detection (supports dots, dashes)
• S3 artifact upload to artifacts/{PRODUCT}/{PLAN_ID}/automation/{RUN_ID}
• HAVEN API integration with environment information
• ECR push with product+version tagging (version from consumer package.json)
• Podman compatible - Works with both Docker and Podman

Install

npm install haven-cypress-integration cypress

Usage

Build Types

Thin Image (Default)

Lightweight image that clones your code at runtime from Azure DevOps. Best for CI/CD pipelines:

# Build thin image (default)
npx haven-cypress build --product=BE --push

# Explicit thin image build
npx haven-cypress build --product=BE --type=thin --push

# With custom tag
npx haven-cypress build --product=BE --type=thin --tag=thin-1.0.0 --push

Full Image

Includes your app code baked into the image. Best for simple deployments:

# Build full image
npx haven-cypress build --product=BE --type=full --push

Thin Image Runtime Requirements:

• ADO_REPO - Full ADO repo path (e.g., dev.azure.com/org/project/_git/repo)
• ADO_PAT - Personal Access Token for authentication
• ADO_BRANCH - Branch to clone (optional, default: main)

Build and Deploy Examples

# Build locally (thin image - default)
npx haven-cypress build --product=BE

# Build and push thin image to ECR (default)
npx haven-cypress build --product=BE --push

# Build and push full image to ECR
npx haven-cypress build --product=BE --type=full --push

# Build with custom version (thin by default)
npx haven-cypress build --product=BE --tag=v2.1.0 --push

Running Tests

# Run specific automation IDs
npx haven-cypress run --automationIds=TC-AUTO-123,TC-AUTO-124

# Run tests with custom tags
npx haven-cypress run --customTags=smoke,p1

# Combine automation IDs and custom tags
npx haven-cypress run --automationIds=TC-AUTO-123 --customTags=smoke

HAVEN Deployment

HAVEN will run your containerized tests with environment variables:

docker run \
  -e TEST_ENVIRONMENT=PROD \
  -e PLAN_ID=123 \
  -e RUN_ID=456 \
  -e E2E_COMMAND="npm run test:e2e" \
  066726995253.dkr.ecr.us-east-1.amazonaws.com/haven-test-images:BE-1.1.0 \
  --customTags=smoke,p1

Test Tagging Examples

Basic Test Tagging

describe('Login Tests', () => {
  it('should login successfully @TC-AUTO-123 @smoke @p0', () => {
    const env = Cypress.env('TEST_ENVIRONMENT'); // QA, DEV, CTE, PROD
    cy.visit(`https://${env.toLowerCase()}.myapp.com/login`);
    // your test code
  });

  it('should register new user @TC-AUTO-456 @regression @p1', () => {
    // your test code
  });
});

Environment-Specific Testing

it('environment-specific test @TC-AUTO-789', () => {
  const env = Cypress.env('TEST_ENVIRONMENT');
  
  switch(env) {
    case 'PROD':
      cy.visit('https://app.mycompany.com');
      break;
    case 'CTE':
      cy.visit('https://cte.mycompany.com');
      break;
    default:
      cy.visit(`https://${env.toLowerCase()}.mycompany.com`);
  }
});

Using Custom E2E Commands

For projects with custom test runners, set the E2E_COMMAND environment variable:

# In your Dockerfile or container environment
ENV E2E_COMMAND="npm run test:e2e:prod"

The integration will export HAVEN_GREP_INCLUDE and HAVEN_GREP_EXCLUDE for use in your cypress.config.js:

// cypress.config.js
const { defineConfig } = require('cypress');

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      // Use HAVEN's grep patterns if available
      if (process.env.HAVEN_GREP_INCLUDE) {
        config.env.grepTags = process.env.HAVEN_GREP_INCLUDE;
      }
      if (process.env.HAVEN_GREP_EXCLUDE) {
        config.env.grepInvert = process.env.HAVEN_GREP_EXCLUDE;
      }
      return config;
    },
  },
});

Artifacts and Monitoring

S3 Artifacts

• Live Output: s3://{BUCKET}/artifacts/{PRODUCT}/{PLAN_ID}/automation/{RUN_ID}/live-output.log (updated every 30s)
• Final Output: s3://{BUCKET}/artifacts/{PRODUCT}/{PLAN_ID}/automation/{RUN_ID}/test-output.log
• Report ZIP: s3://{BUCKET}/artifacts/{PRODUCT}/{PLAN_ID}/automation/{RUN_ID}/{PRODUCT}_{TIMESTAMP}.zip

Shared Volume (for HAVEN)

• ZIP: /shared/test-logs/{PRODUCT}_{TIMESTAMP}.zip
• HTML: /shared/test-logs/report.html

Environment Variables

Required (provided by HAVEN)

• PLAN_ID - Test plan identifier
• RUN_ID - Test run identifier
• PRODUCT_NAME - Product name for artifact organization
• BUCKET_NAME - S3 bucket for artifact uploads

Optional

• TEST_ENVIRONMENT - Target environment (QA/DEV/CTE/PROD, default: QA)
• E2E_COMMAND - Custom test execution command (default: npx cypress run ...)
• HAVEN_GREP_PATTERN - Grep pattern from Haven (parsed into include/exclude)

Available to Tests

• TEST_ENVIRONMENT - Accessible in your test code via Cypress.env('TEST_ENVIRONMENT')
• HAVEN_GREP_INCLUDE - Exported grep pattern for custom configs
• HAVEN_GREP_EXCLUDE - Exported grep pattern for excluding tests (NOT: prefix)

ECR Image Management

Images are automatically tagged and organized by product and build type:

Tag Format

• Full Image: {PRODUCT}-{VERSION} (e.g., BE-1.1.0)
• Thin Image: {PRODUCT}-thin-{VERSION} (e.g., BE-thin-1.1.0)

Repository

• Repository: haven-test-images
• Examples:
  • BE-1.1.0 (full image from package.json version)
  • BE-thin-1.1.0 (thin image for ADO cloning)
  • payments-2.1.0 (custom full image)
  • payments-thin-2.1.0 (custom thin image)

Usage in HAVEN

# Use full image (app code included)
image: haven-test-images:BE-1.1.0

# Use thin image (requires ADO_REPO, ADO_PAT env vars)
image: haven-test-images:BE-thin-1.1.0
environment:
  ADO_REPO: "dev.azure.com/myorg/myproject/_git/myrepo"
  ADO_PAT: "${ADO_PAT_SECRET}"
  ADO_BRANCH: "main"

Requirements

• Node.js 16+
• Podman or Docker
• AWS CLI configured (for ECR push)
• HAVEN access credentials (provided when container runs)
• @cypress/grep plugin configured in your Cypress project

Cypress Project Setup

Ensure your Cypress project has the @cypress/grep plugin configured:

npm install @cypress/grep --save-dev

// cypress/support/e2e.js
import registerCypressGrep from '@cypress/grep';
registerCypressGrep();

// cypress.config.js
const { defineConfig } = require('cypress');

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      require('@cypress/grep/src/plugin')(config);
      return config;
    },
  },
});

Latest Updates

v2.0.0

• Added thin/full image support (matching Playwright integration)
• Added ADO clone mode for thin images
• Added HAVEN_GREP_PATTERN support with include/exclude patterns
• Added NOT: prefix support for excluding tests
• Added real-time log streaming to S3
• Added custom E2E command support via E2E_COMMAND
• Added --platform linux/amd64 for ARM/M1 compatibility
• Added --force-compression for ECR push reliability
• Added stale ECR credential clearing
• Removed all emojis from console output
• Removed axios/glob dependencies (using native Node.js modules)
• Haven scripts now in /haven/ directory (isolated from app code)

Notes

• Works with existing HAVEN runner; no changes required
• Container base image: cypress/included:14.3.1
• Supports both default Cypress execution and custom E2E commands
• Real-time monitoring via S3 log streaming during test execution