haven-cypress-integration 1.6.2 → 2.0.1

package/README.md

@@ -1,164 +1,268 @@
-# Haven-Cypress Integration
-
-Seamless integration between Cypress test frameworks and HAVEN test case management system.
-
-## Quick Start
-
-### 1. Install
+# 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
 ```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
-});
+npm install haven-cypress-integration cypress
 ```
 
-### 3. Cypress Configuration (Optional Simplification)
-The library automatically configures mochawesome reporting. You can use a simplified `cypress.config.js`:
+## Usage
 
-```javascript
-const { defineConfig } = require("cypress");
+### Build Types
 
-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;
-    },
-  },
-});
-```
+#### Thin Image (Default)
+Lightweight image that clones your code at runtime from Azure DevOps. Best for CI/CD pipelines:
+```bash
+# Build thin image (default)
+npx haven-cypress build --product=BE --push
 
-**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.
+# Explicit thin image build
+npx haven-cypress build --product=BE --type=thin --push
 
-### 4. Build Docker Image
-```bash
-npx haven-cypress build --product=BE
+# With custom tag
+npx haven-cypress build --product=BE --type=thin --tag=thin-1.0.0 --push
 ```
 
-### 5. Push to ECR and Deploy to Haven
+#### Full Image
+Includes your app code baked into the image. Best for simple deployments:
 ```bash
-npx haven-cypress build --product=BE --push
+# Build full image
+npx haven-cypress build --product=BE --type=full --push
 ```
-Your Docker image is now pushed to ECR and ready to be deployed and run by HAVEN!
 
-## Commands
+**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 Image
+### Build and Deploy Examples
 ```bash
-# Basic build with product organization
+# Build locally (thin image - default)
 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
+# Build and push thin image to ECR (default)
 npx haven-cypress build --product=BE --push
 
-# Build and push with custom tag
-npx haven-cypress build --product=BE --tag=v1.0 --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
 ```
 
-### Run Tests
+### Running Tests
 ```bash
-# Run all tests
-npx haven-cypress run
-
-# Run specific test cases
+# Run specific automation IDs
 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:
+# 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
 ```
-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
+
+### HAVEN Deployment
+HAVEN will run your containerized tests with environment variables:
+```bash
+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
 ```
 
-**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`)
+## Test Tagging Examples
 
-### Versioning Examples
+### Basic Test Tagging
+```javascript
+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
+  });
+});
+```
 
-**Using package.json version (Recommended):**
-```json
-// package.json
-{
-  "version": "2.1.0"
-}
+### Environment-Specific Testing
+```javascript
+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:
 ```bash
-# Automatically uses package.json version
-npx haven-cypress build --product=BE --push
-→ ECR tag: BE-2.1.0
+# In your Dockerfile or container environment
+ENV E2E_COMMAND="npm run test:e2e:prod"
 ```
 
-**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
+The integration will export `HAVEN_GREP_INCLUDE` and `HAVEN_GREP_EXCLUDE` for use in your `cypress.config.js`:
+```javascript
+// cypress.config.js
+const { defineConfig } = require('cypress');
 
-npx haven-cypress build --product=BE --tag=3.0.0 --push
-→ ECR tag: BE-3.0.0
+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;
+    },
+  },
+});
 ```
 
-**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
+## 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
+```yaml
+# 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"
 ```
 
-## What's Included
+## Requirements
 
-- ✅ **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
+- 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
 
-## How It Works
+## Cypress Project Setup
 
-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
+Ensure your Cypress project has the `@cypress/grep` plugin configured:
 
-## Requirements
+```bash
+npm install @cypress/grep --save-dev
+```
 
-- Node.js 14+
-- Docker or Podman
-- Existing Cypress project
-- AWS credentials configured (for ECR push)
-- HAVEN access credentials (provided by Haven when container runs)
+```javascript
+// cypress/support/e2e.js
+import registerCypressGrep from '@cypress/grep';
+registerCypressGrep();
+```
+
+```javascript
+// cypress.config.js
+const { defineConfig } = require('cypress');
 
-## Support
+module.exports = defineConfig({
+  e2e: {
+    setupNodeEvents(on, config) {
+      require('@cypress/grep/src/plugin')(config);
+      return config;
+    },
+  },
+});
+```
 
-For issues or questions, contact your HAVEN administrator.
+## 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

package/bin/haven-cypress.js

@@ -1,77 +1,64 @@
 #!/usr/bin/env node
+const path = require('path');
+const fs = require('fs');
+const { spawnSync } = require('child_process');
+const lib = require('..');
 
-const HavenCypressIntegration = require('../index.js');
-
-const args = process.argv.slice(2);
-const command = args[0];
+function parseArgs() {
+    const args = process.argv.slice(2);
+    const cmd = args[0] || 'build';
+    const opts = { tag: 'haven-cypress-tests:latest', push: false, product: null, automationIds: '', customTags: '', type: 'thin' };
+    for (const a of args.slice(1)) {
+        if (a.startsWith('--tag=')) opts.tag = a.split('=')[1];
+        if (a === '--push') opts.push = true;
+        if (a.startsWith('--product=')) opts.product = a.split('=')[1];
+        if (a.startsWith('--automationIds=')) opts.automationIds = a.split('=')[1];
+        if (a.startsWith('--customTags=')) opts.customTags = a.split('=')[1];
+        if (a.startsWith('--type=')) opts.type = a.split('=')[1];
+    }
+    return { cmd, opts };
+}
 
-if (!command) {
-  console.log(`
-Haven-Cypress Integration
+function printHelp() {
+    console.log(`HAVEN Cypress Integration
 
-Usage: npx haven-cypress <command> [options]
+Usage:
+  npx haven-cypress build [--product=BE] [--tag=1.2.3] [--type=full|thin] [--push]
+  npx haven-cypress run --automationIds=TC-AUTO-1,TC-AUTO-2
+  npx haven-cypress run --customTags=smoke,p1
 
-Commands:
-  build [options]    Build Docker image with Haven integration
-  run [options]      Run tests with Haven integration
+Build Types:
+  --type=thin           Thin image for runtime ADO cloning (default)
+  --type=full           Full image with app code baked in
 
 Options:
-  --tag=name:version    Docker image tag (default: haven-cypress-tests:latest)
-  --product=name        Product name for ECR organization (required for --push)
-  --push                Push image to ECR haven-test-images repository
+  --tag=name:version or just version  Docker image tag (default: haven-cypress-tests:latest)
+  --product=name        Product name for ECR tagging (recommended)
+  --push                Push image to ECR after building
   --automationIds=ID1,ID2  Run specific test cases by automation ID
   --customTags=tag1,tag2   Run tests with custom tags (smoke, regression, p1, etc.)
 
 Examples:
-  npx haven-cypress build --product=BE
+  # Build thin image (default - for ADO runtime cloning)
   npx haven-cypress build --product=BE --push
-  npx haven-cypress build --product=BE --tag=v2.1.0 --push
-  npx haven-cypress run --automationIds=TC-AUTO-123,TC-AUTO-124
-  npx haven-cypress run --customTags=smoke,p1
-  npx haven-cypress run --automationIds=TC-AUTO-123 --customTags=smoke
 
-Versioning:
-  --tag=latest        → ECR tag: BE-{package.json.version} or BE-1.0.{BUILD_NUMBER}
-  --tag=v2.1.0        → ECR tag: BE-2.1.0
-  --tag=2.1.0         → ECR tag: BE-2.1.0
-  
-  Version Priority:
-  1. Custom --tag (if provided)
-  2. package.json version (for --tag=latest)
-  3. BUILD_NUMBER fallback (if package.json not found)
+  # Build full image (app code included)
+  npx haven-cypress build --product=BE --type=full --push
 `);
-  process.exit(1);
 }
 
-const integration = new HavenCypressIntegration();
+(async () => {
+    const { cmd, opts } = parseArgs();
+    if (!['build', 'run', 'help', '-h', '--help'].includes(cmd)) return printHelp();
+    if (cmd === 'help' || cmd === '-h' || cmd === '--help') return printHelp();
 
-// Parse options
-const options = {};
-args.slice(1).forEach(arg => {
-  if (arg.startsWith('--')) {
-    const [key, value] = arg.substring(2).split('=');
-    options[key] = value || true;
-  }
-});
+    if (cmd === 'build') {
+        await lib.buildImage(opts.tag, { product: opts.product, push: opts.push, type: opts.type });
+        return;
+    }
 
-try {
-  switch (command) {
-    case 'build':
-      const tag = options.tag || 'haven-cypress-tests:latest';
-      integration.buildImage(tag, options);
-      break;
-
-    case 'run':
-      const automationIds = options.automationIds || '';
-      const customTags = options.customTags || '';
-      integration.runTests(automationIds, customTags);
-      break;
-
-    default:
-      console.error(`❌ Unknown command: ${command}`);
-      process.exit(1);
-  }
-} catch (error) {
-  console.error(`❌ Error: ${error.message}`);
-  process.exit(1);
-}
+    if (cmd === 'run') {
+        await lib.runTests(opts.automationIds, opts.customTags);
+        return;
+    }
+})();