Overlay Testing

Different from Package Documentation

This section documents how to write E2E tests within the rhdh-plugin-export-overlays repository.

If you want to learn how to use the @red-hat-developer-hub/e2e-test-utils package in your own project, see the Guide.

What is Overlay Testing?

Overlay testing refers to end-to-end tests written for plugins in the rhdh-plugin-export-overlays repository. These tests:

• Live within workspace e2e-tests/ directories
• Use @red-hat-developer-hub/e2e-test-utils as a dependency
• Run in CI pipelines against overlay builds
• Test overlay-specific plugin configurations

When to Use This Section

Use this documentation when you are:

• Adding E2E tests to a new plugin workspace in the overlay repository
• Modifying existing overlay E2E tests
• Understanding the overlay test structure and patterns
• Debugging CI pipeline issues for overlay tests

Package vs Overlay Documentation

Aspect	Package Docs (Guide)	Overlay Docs (This Section)
Purpose	How to use @red-hat-developer-hub/e2e-test-utils in any project	How to write tests within rhdh-plugin-export-overlays
Audience	External consumers of the package	Overlay repository contributors
Focus	API reference, fixtures, helpers	Repository structure, CI integration
Examples	Generic plugin testing	Tech Radar, other overlay plugins

Key Concepts

Automatic Plugin Configuration

The package automatically generates dynamic plugin configuration from metadata files in your workspace. This means:

• Don't create dynamic-plugins.yaml unless you have specific overrides
• All plugins in the workspace are enabled by default from metadata
• Plugin configurations come from metadata/*.yaml files (Package CRD format)

See Configuration Files for details.

PR OCI Image Builds

When testing PRs, the /publish command builds OCI images that RHDH uses automatically:

• Local plugin paths are replaced with OCI URLs in CI
• The GIT_PR_NUMBER environment variable triggers this behavior
• You don't need to handle different configs for local vs CI

See CI Pipeline for details.

Visual Flows

Metadata → Config → Deploy

metadata/*.yaml
  -> auto-generate plugin config
  -> merge with defaults + auth config (if exists)
  -> deploy RHDH

Local Secrets → Config

Bitwarden wrapper / .env
  -> rhdh-secrets.yaml
  -> app-config-rhdh.yaml
  -> deploy RHDH

Quick Start

1. Navigate to your plugin workspace in the overlay repository
2. Create an e2e-tests/ directory
3. Set up the standard test structure
4. Write your specs using @red-hat-developer-hub/e2e-test-utils
5. Run tests locally or via CI

See Getting Started for a step-by-step walkthrough.

Common Tasks

• Add tests to a new workspace
• Run tests locally
• Run in CI / OpenShift pipeline
• Trigger PR OCI build (/publish)

Documentation Structure

Test Structure

Learn about the standard directory layout and configuration files:

• Directory Layout - Standard folder structure
• Configuration Files - YAML configs for RHDH
• Spec Files - Writing test specifications

Tutorials

Step-by-step guides for common tasks:

• Adding Tests to New Workspace - Set up E2E tests from scratch
• Plugin Configuration - Configure plugin-specific settings
• Pre-requisite Services - Deploy dependencies before RHDH
• Running Tests Locally - Local development workflow
• CI/CD Pipeline - OpenShift CI integration

Examples

Complete working examples:

• Tech Radar Plugin - Full annotated walkthrough
• Basic Plugin Test - Minimal example

Reference

Quick reference materials:

• Plugin Metadata Resolution - How plugin packages are resolved in PR, nightly, and local modes
• Environment Variables - Configuration options
• Local OCI Testing - Testing with PR-built images locally
• Package.json Scripts - Available commands
• Common Patterns - Testing patterns
• Troubleshooting - Common issues and solutions

Related Pages

• Guide - Package documentation for external projects
• API Reference - Full API documentation
• Tutorials - Package usage tutorials