Skip to content

getting-started.md

Latest commit

 

History

History
159 lines (112 loc) · 4.53 KB

getting-started.md

File metadata and controls

159 lines (112 loc) · 4.53 KB

Getting Started

New to HyperFleet E2E? This guide will help you run your first test in 10 minutes.

Prerequisites

  • Go 1.25+ - Required for building the framework
  • HyperFleet deployment - Running HyperFleet API and Maestro instance
  • 10 minutes - Time to complete this guide

Need to set up a HyperFleet environment first? See the Setup Guide for complete instructions using Kind (local) or GCP.

Installation

Clone and Build

git clone https://github.com/openshift-hyperfleet/hyperfleet-e2e.git
cd hyperfleet-e2e
make build

Verify Installation

./bin/hyperfleet-e2e --help

You should see the command help output.

Your First Test

Step 1: Set required environment variables

export HYPERFLEET_API_URL=<your-hyperfleet-api-url>
export MAESTRO_URL=<your-maestro-url>
export NAMESPACE=<your-deployment-namespace>

Step 2: Run tier0 tests

./bin/hyperfleet-e2e test --label-filter=tier0

What happens:

  1. Framework creates a new cluster via API
  2. Waits for cluster to reach Reconciled state
  3. Validates adapter conditions
  4. Deletes cluster after test completes

What Just Happened?

The framework:

  1. Loaded configuration - Merged config file, environment variables, and CLI flags
  2. Executed tests - Ran all tests matching your filter
  3. Managed resources - Created and deleted temporary test clusters
  4. Generated results - Displayed test outcomes

Running Specific Tests

# Run critical tests only
./bin/hyperfleet-e2e test --label-filter=tier0

# Run important features
./bin/hyperfleet-e2e test --label-filter=tier1

# Run edge cases (requires sourcing env/env.local first)
source env/env.local && ./bin/hyperfleet-e2e test --label-filter=tier2

# Run all cluster suite tests
./bin/hyperfleet-e2e test --focus "\[Suite: cluster\]"

# Run cluster tier0 tests only
./bin/hyperfleet-e2e test --label-filter="tier0" --focus "\[Suite: cluster\]"

# Deep debug mode (add API calls and framework internals)
./bin/hyperfleet-e2e test --log-level=debug

Listing Tests Without Execution

Use --dry-run to discover which specs match your filters without connecting to the API or creating resources. No --api-url is required in dry-run mode.

# List all tier0 tests
./bin/hyperfleet-e2e test --dry-run --label-filter=tier0

# List tier1 cluster tests
./bin/hyperfleet-e2e test --dry-run --label-filter=tier1 --focus "\[Suite: cluster\]"

# List tests for each tier via Makefile
make list-tests

Note: The default output already shows detailed test execution steps. If a test fails, you can usually diagnose the issue from the logs without re-running in debug mode. Use --log-level=debug when you need to see API calls and framework internals. See Debugging Guide for more debugging techniques.

Common Commands

make build       # Build binary
make test        # Run unit tests
make e2e         # Run E2E tests
make list-tests  # List tests by tier (dry-run, no API required)
make lint        # Run linter
make generate    # Regenerate OpenAPI client

Troubleshooting

Common Issues

API connection errors:

# Verify API URLs are set
echo $HYPERFLEET_API_URL
echo $MAESTRO_URL
echo $NAMESPACE

# Test connectivity
curl -f -X GET ${HYPERFLEET_API_URL}/api/hyperfleet/v1/clusters/

Test timeouts: Increase timeouts via environment variables:

HYPERFLEET_TIMEOUTS_CLUSTER_RECONCILED=45m make e2e

Namespace mismatch: Ensure NAMESPACE matches your deployment namespace. Some tests deploy adapters dynamically and must target the same namespace where HyperFleet components are running.

Configuration not taking effect:

Priority order (highest to lowest):

  1. CLI flags (--api-url)
  2. Environment variables (HYPERFLEET_API_URL, MAESTRO_URL, NAMESPACE)
  3. Config file (configs/config.yaml)
  4. Built-in defaults

Need detailed logs:

# Default (info) shows test execution steps
./bin/hyperfleet-e2e test

# Debug mode shows API calls and framework internals
./bin/hyperfleet-e2e test --log-level=debug

For more troubleshooting help and environment issues, see the Runbook or Setup Guide.

Next Steps

  • Runbook - Running tests and troubleshooting guide
  • Architecture - Understand how the framework works
  • Development - Write your own tests
  • CLI Reference - Run ./bin/hyperfleet-e2e --help
  • Configuration - See detailed comments in configs/config.yaml