Skip to content

README.md

Latest commit

 

History

History
471 lines (334 loc) · 14.1 KB

README.md

File metadata and controls

471 lines (334 loc) · 14.1 KB

Cypress Setup & Configuration Guide

Technical setup and environment configuration for Monitoring Plugin Cypress tests

For testing workflows, test architecture, and creating tests, see CYPRESS_TESTING_GUIDE.md

Quick Start

cd web/cypress
npm install                 # Install dependencies
source ./configure-env.sh   # Interactive configuration
npm run cypress:open           # Start Cypress GUI

Prerequisites

  • Node.js: >= 18

Installation

Install Cypress and all dependencies:

npm install

Dependencies are defined in package.json and will be installed in node_modules/.

Environment Configuration

Interactive Setup (Recommended)

The configure-env.sh script provides an interactive way to set up all required environment variables:

source ./configure-env.sh

Features:

  • Automatic prompting for all CYPRESS_ variables
  • Automatic discovery and numbered selection of *kubeconfig* files in $HOME/Downloads
  • Validates required variables

Alternative - Generate Export File:

./configure-env.sh

Creates export-env.sh that you can source later: source export-env.sh

Environment Variables Reference

Required Variables

Variable Description Example
CYPRESS_BASE_URL OpenShift Console URL https://console-openshift-console.apps...
CYPRESS_LOGIN_IDP Identity provider name flexy-htpasswd-provider or kube:admin
CYPRESS_LOGIN_IDP_DEV_USER Identity provider name for devuser flexy-htpasswd-provider or my_htpasswd_provider
CYPRESS_LOGIN_USERS Login credentials username:password or kubeadmin:password or kubeadmin:password,user1:password,user2:password
CYPRESS_KUBECONFIG_PATH Path to kubeconfig file ~/Downloads/kubeconfig

Plugin Image Configuration

Variable Description Use Case
CYPRESS_MP_IMAGE Custom Monitoring Plugin image Testing custom MP builds
CYPRESS_MCP_CONSOLE_IMAGE Custom Monitoring Console Plugin image Testing custom MCP builds
CYPRESS_CHA_IMAGE Custom cluster-health-analyzer image Testing custom CHA builds

Operator Installation Control

Variable Default Description
CYPRESS_SKIP_COO_INSTALL false Skip Cluster Observability Operator installation
CYPRESS_SKIP_KBV_INSTALL false Skip OpenShift Virtualization installation
CYPRESS_SKIP_ALL_INSTALL false Skip all operator installations (for pre-provisioned clusters)
CYPRESS_COO_UI_INSTALL false Install COO from redhat-operators catalog
CYPRESS_KBV_UI_INSTALL false Install Virtualization from redhat-operators catalog

Bundle Images

Variable Description
CYPRESS_KONFLUX_COO_BUNDLE_IMAGE COO bundle image from Konflux
CYPRESS_CUSTOM_COO_BUNDLE_IMAGE Custom COO bundle image
CYPRESS_KONFLUX_KBV_BUNDLE_IMAGE Virtualization bundle image from Konflux
CYPRESS_CUSTOM_KBV_BUNDLE_IMAGE Custom Virtualization bundle image

FBC images

Variable Description
CYPRESS_FBC_STAGE_COO_IMAGE Cluster Observability Operator FBC image
CYPRESS_FBC_STAGE_KBV_IMAGE Virtualization FBC image

Testing Configuration

Variable Default Description
CYPRESS_SESSION false Enable session management for faster execution
CYPRESS_DEBUG false Enable debug mode logging in headless mode

Incidents Testing Configuration

Used primarily for Incidents feature testing:

Variable Default Description
CYPRESS_TIMEZONE UTC Cluster timezone for incident timeline calculations
CYPRESS_MOCK_NEW_METRICS false Transform old metric names to new format in mocks (temporary workaround for testing against locally built instances)

Example:

export CYPRESS_TIMEZONE="America/New_York"
export CYPRESS_MOCK_NEW_METRICS=true

Configuration Examples

Example 1: Testing with Non-Admin User

export CYPRESS_BASE_URL=https://console-openshift-console.apps.cluster.example.com
export CYPRESS_LOGIN_IDP=flexy-htpasswd-provider
export CYPRESS_LOGIN_USERS=testuser:testpassword
export CYPRESS_KUBECONFIG_PATH=~/Downloads/kubeconfig

Example 2: Testing with Kubeadmin

export CYPRESS_BASE_URL=https://console-openshift-console.apps.cluster.example.com
export CYPRESS_LOGIN_IDP=kube:admin
export CYPRESS_LOGIN_USERS=kubeadmin:admin-password
export CYPRESS_KUBECONFIG_PATH=~/Downloads/kubeconfig

Example 3: Testing Custom Plugin Build

# Required variables
export CYPRESS_BASE_URL=https://...
export CYPRESS_LOGIN_IDP=flexy-htpasswd-provider
export CYPRESS_LOGIN_USERS=username:password
export CYPRESS_KUBECONFIG_PATH=~/Downloads/kubeconfig

# Custom image
export CYPRESS_MP_IMAGE=quay.io/myorg/monitoring-plugin:my-branch
export CYPRESS_MCP_CONSOLE_IMAGE=quay.io/myorg/monitoring-console-plugin:my-branch

Example 4: Testing Custom cluster-health-analyzer Build

For CI jobs testing PRs to cluster-health-analyzer:

# Required variables
export CYPRESS_BASE_URL=https://...
export CYPRESS_LOGIN_IDP=flexy-htpasswd-provider
export CYPRESS_LOGIN_USERS=username:password
export CYPRESS_KUBECONFIG_PATH=~/Downloads/kubeconfig

# Custom cluster-health-analyzer image built from PR
export CYPRESS_CHA_IMAGE=quay.io/myorg/cluster-health-analyzer:pr-123

# Use COO bundle (required for incidents feature testing)
export CYPRESS_KONFLUX_COO_BUNDLE_IMAGE=quay.io/rhobs/observability-operator-bundle:latest

Example 5: Pre-Provisioned Cluster (Skip Installations)

# Required variables
export CYPRESS_BASE_URL=https://...
export CYPRESS_LOGIN_IDP=flexy-htpasswd-provider
export CYPRESS_LOGIN_USERS=username:password
export CYPRESS_KUBECONFIG_PATH=~/Downloads/kubeconfig

# Skip installations (cluster already configured)
export CYPRESS_SKIP_ALL_INSTALL=true

Example 6: Configurable COO Namespace

Set the following var to specify the Cluster Observability Operator namespace. Defaults to openshift-cluster-observability-operator if not set. This is useful when testing with different namespace configurations (e.g., using coo instead of the default).

export CYPRESS_COO_NAMESPACE=openshift-cluster-observability-operator

Example 7: Debug Mode

# Required variables + debug
export CYPRESS_DEBUG=true
export CYPRESS_SESSION=true  # Faster test execution

Running Cypress

Interactive Mode (GUI)

Best for test development and debugging:

npm run cypress:open

Headless Mode (CI-style)

For automated testing:

npm run cypress:run

Running Specific Tests

# COO BVT tests
npm run cypress:run -- --spec "cypress/e2e/coo/01.coo_bvt.cy.ts"

# ACM Alerting tests
npm run cypress:run -- --spec "cypress/e2e/coo/02.acm_alerting_ui.cy.ts"

# Monitoring BVT tests
npm run cypress:run -- --spec "cypress/e2e/monitoring/00.bvt_admin.cy.ts"

# All Monitoring Regression tests
npm run cypress:run -- --spec "cypress/e2e/monitoring/regression/**"

# All Virtualization IVT tests
npm run cypress:run -- --spec "cypress/e2e/virtualization/**"

# Incidents tests (requires CYPRESS_TIMEZONE and optionally CYPRESS_MOCK_NEW_METRICS)
npm run cypress:run -- --spec "cypress/e2e/**/incidents*.cy.ts"

Note: Incidents tests require CYPRESS_TIMEZONE to be set to match your cluster's timezone configuration. See Incidents Testing Configuration for details.

For comprehensive test commands and regression testing strategies, see CYPRESS_TESTING_GUIDE.md

Running tests by tags

Tests are organized using tags for selective execution using @cypress/grep.

Tag Categories

1. Basic Tags:

  • @smoke - Fast BVT tests
  • @demo - Interactive demo tests (no assertions, skipped in CI)
  • @flaky - Tests that don't pass reliably
  • @xfail - Tests for known bugs expected to fail
  • @slow - Long-running e2e tests (15+ minutes)

2. High-Level Component Tags:

  • @monitoring - Monitoring plugin tests
  • @incidents - Incidents feature tests
  • @coo - Cluster Observability Operator functionality tests (operator installation, ACM integration)
  • @virtualization - Virtualization integration tests
  • @alerts - Alert-related tests
  • @metrics - Metrics-related tests
  • @dashboards - Dashboard-related tests (includes Perses)

3. Specific Feature Tags (format: @{component}-{label}):

  • Example: @incidents-redux
  • Add specific feature tags as needed

4. JIRA Tags (format: @JIRA-{ID}):

  • Example: @JIRA-OU-1033
  • Link tests to specific JIRA issues

Running Tests by Tags

Run smoke tests (BVT):

npx cypress run --env grepTags=@smoke
# or
npm run test-cypress-smoke

Run regression tests (all non-smoke tests):

npx cypress run --env grepTags="--@smoke --@flaky --@demo"

Run component-specific tests:

npm run test-cypress-monitoring       # All monitoring tests
npm run test-cypress-incidents        # All incidents tests
npm run test-cypress-coo              # COO operator functionality tests
npm run test-cypress-virtualization   # All virtualization integration tests
npm run test-cypress-alerts           # All alerts tests
npm run test-cypress-metrics          # All metrics tests
npm run test-cypress-dashboards       # All dashboards tests (includes Perses)

Run smoke tests for specific component:

npm run test-cypress-monitoring-bvt  # Monitoring smoke tests
npm run test-cypress-coo-bvt         # COO smoke tests

Run regression for specific component:

npm run test-cypress-monitoring-regression  # All monitoring except smoke

Run tests with multiple tags (OR logic):

npx cypress run --env grepTags="@smoke @slow"

Run tests with BOTH tags (AND logic):

npx cypress run --env grepTags="@smoke+@incidents"

Complex filtering:

npx cypress run --env grepTags="@incidents --@slow --@flaky"

Test Results

Videos

Test recordings are saved automatically:

  • Location: web/cypress/videos/
  • Format: .mp4
  • Generated: For all test runs (pass or fail)

Screenshots

Screenshots captured on test failures:

  • Location: web/cypress/screenshots/
  • Format: .png
  • Generated: Only on failures

Troubleshooting Setup Issues

Issue: Cypress Cannot Find Chrome/Browser

Solution: Install Chrome or specify browser

npm run cypress:open --browser firefox

Issue: Environment Variables Not Set

Symptoms: Tests fail with "BASE_URL is not defined"

Solution:

  1. Verify variables are exported: echo $CYPRESS_BASE_URL
  2. Re-run configuration: source ./configure-env.sh
  3. Ensure you're in the correct shell session

Issue: Kubeconfig Not Found

Symptoms: "ENOENT: no such file or directory"

Solution:

# Check file exists
ls -la $CYPRESS_KUBECONFIG_PATH

# Update path if needed
export CYPRESS_KUBECONFIG_PATH=/correct/path/to/kubeconfig

Issue: Login Fails

Symptoms: "User authentication failed"

Solution:

  1. Verify IDP name: Check OpenShift OAuth configuration
  2. Verify credentials are correct
  3. For kubeadmin, use kube:admin as IDP

Issue: Tests Are Slow

Solution: Enable session management

export CYPRESS_SESSION=true

Component Testing

Cypress component tests mount individual React components in isolation, without a running cluster. They provide fast feedback for testing rendering logic, props handling, and user interactions. See CYPRESS_TESTING_GUIDE.md for more guidance on how to write and run the tests.

Configuration

Component testing is configured in the component section of web/cypress.config.ts. It uses a standalone webpack config with swc-loader and a custom mount command (compatible with React 17) defined in cypress/support/component.ts.

Test Organization

Directory Structure

cypress/
├── component/              # Component test files (.cy.tsx)
├── e2e/                    # E2E test files by perspective
│   ├── monitoring/         # Core monitoring (Administrator)
│   ├── coo/               # COO-specific tests
│   └── virtualization/    # Virtualization integration
├── support/               # Reusable test scenarios
│   ├── monitoring/        # Test scenario modules
│   ├── perses/           # Perses scenarios
│   ├── commands/         # Custom Cypress commands
│   ├── component.ts      # Component test support
│   └── component-index.html # Component test HTML template
├── views/                # Page object models
├── fixtures/             # Test data and mocks
└── E2E_TEST_SCENARIOS.md # Complete test catalog

For test architecture and creating new tests, see CYPRESS_TESTING_GUIDE.md

Documentation

Additional Resources

  • Configure Script: ./configure-env.sh - Interactive setup
  • Export Script: ./export-env.sh - Generated environment file
  • Fixtures: ./fixtures/ - Test data and mocks
  • Support: ./support/ - Custom commands and utilities

Incident Detection Test Documentation

Test documentation for the Incidents feature is available at docs/incident_detection/tests/ in the repository root.

For questions about test architecture, creating tests, or testing workflows, refer to CYPRESS_TESTING_GUIDE.md