Running Tests Locally

Overlay Documentation

This page covers writing tests within rhdh-plugin-export-overlays. For using @red-hat-developer-hub/e2e-test-utils in external projects, see the Guide.

This tutorial covers the local development workflow for overlay E2E tests.

Prerequisites

Before running tests locally, ensure you have:

Node.js 22+ installed
Yarn 3+ installed
Access to an OpenShift cluster
CLI tools: oc, kubectl, helm
Logged into the cluster: oc login <cluster-url>

Setup

1. Navigate to Test Directory

bash

cd workspaces/<plugin>/e2e-tests

2. Install Dependencies

bash

yarn install

3. Install Playwright Browsers

bash

npx playwright install

Running Tests

Multi-Workspace Testing

To run tests across multiple workspaces simultaneously, use the run-e2e.sh unified test runner instead of individual workspace commands:

bash

# Run all workspaces
./run-e2e.sh

# Run specific workspaces
./run-e2e.sh -w tech-radar -w keycloak

# Use local e2e-test-utils build
E2E_TEST_UTILS_PATH=/path/to/rhdh-e2e-test-utils ./run-e2e.sh -w tech-radar

Run All Tests

bash

yarn test

Run in Headed Mode

See the browser while tests run:

bash

yarn test:headed

Run with Playwright UI

Interactive test runner:

bash

yarn test:ui

Run Specific Test File

bash

yarn test tests/specs/my-plugin.spec.ts

Run Specific Test

bash

yarn test -g "test name pattern"

Viewing Results

View HTML Report

After tests complete:

bash

yarn report

Report Location

Reports are saved to playwright-report/:

playwright-report/index.html - HTML report
Test artifacts (screenshots, videos, traces)

Development Workflow

1. Write Test

Create or modify tests/specs/<plugin>.spec.ts:

typescript

import { test, expect } from "@red-hat-developer-hub/e2e-test-utils/test";

test.describe("Test <plugin>", () => {
  test.beforeAll(async ({ rhdh }) => {
    await rhdh.configure({ auth: "keycloak" });
    await rhdh.deploy();
  });

  test.beforeEach(async ({ loginHelper }) => {
    await loginHelper.loginAsKeycloakUser();
  });

  test("new test case", async ({ uiHelper }) => {
    // Your test code
  });
});

2. Run Test

bash

yarn test:headed

3. Debug Failures

Use Playwright UI for debugging:

bash

yarn test:ui

4. View Trace

For failed tests, traces are automatically captured:

bash

npx playwright show-trace playwright-report/trace.zip

Test local changes to e2e-test-utils in Overlays

If you want to try your local changes to @red-hat-developer-hub/e2e-test-utils work for Overlays:

Build the utils package:

bash

cd /Your/Path/Projects/rhdh-e2e-test-utils
yarn build

Point the Overlays workspace e2e-test-utils dependency to your local checkout:

bash

cd /Your/Path/Projects/rhdh-plugin-export-overlays/workspaces/<plugin>/e2e-tests

Update package.json:

json

{
  "dependencies": {
    "@red-hat-developer-hub/e2e-test-utils": "file:/Your/Path/Projects/rhdh-e2e-test-utils"
  }
}

Reinstall dependencies and run tests:

bash

yarn install
yarn test:headed

When you change the utils package again, re-run yarn build in rhdh-e2e-test-utils, then run yarn install again in the overlay e2e-tests workspace.

Troubleshooting local linking

If you see odd module-resolution issues while testing a locally linked e2e-test-utils package, try running the Overlays tests with:

bash

NODE_PRESERVE_SYMLINKS=1 yarn test:headed

Secrets from Bitwarden

Local secret-backed tests use the standalone rhdh-e2e-secrets executable and an unlocked Bitwarden Password Manager CLI session. The wrapper runs outside Playwright, so secrets are available before configuration files and global setup are evaluated.

bash

# Unlock Bitwarden and export the session key in the current shell.
export BW_SESSION="<session-from-an-unlocked-bw-cli>"

# From a workspace
cd workspaces/argocd/e2e-tests
yarn test:secrets

# From the repository root
./run-e2e.sh --secrets -w argocd

The overlay profile requests global/* and the selected workspaces/<name>/* prefix. Workspace-specific values are optional, while the global prefix is required. Secret values are passed only to the child test process; no secret .env file is generated.

Prerequisites: Install the Bitwarden Password Manager CLI, unlock it, and make bw available on PATH.

Environment Variables

Using .env File

Create .env for non-secret local configuration:

bash

# .env
RHDH_VERSION=1.5
INSTALLATION_METHOD=helm
SKIP_KEYCLOAK_DEPLOYMENT=false

Values in this file override inherited environment values, including secrets selected by the Bitwarden wrapper. Keep .env out of version control if it contains secret overrides.

Common Variables

Variable	Description	Default
`RHDH_VERSION`	RHDH version to deploy	`next` (latest)
`INSTALLATION_METHOD`	`helm` or `operator`	`helm`
`SKIP_KEYCLOAK_DEPLOYMENT`	Skip Keycloak deployment entirely (for guest auth)	`false`

See Environment Variables Reference for all available variables.

Skipping Keycloak Deployment

Use this when running tests with guest authentication (no Keycloak needed):

bash

SKIP_KEYCLOAK_DEPLOYMENT=true yarn test

TIP

You don't need this flag if Keycloak already exists in the cluster. By default, the test framework will detect and reuse an existing Keycloak instance.

Running Against Existing Cluster

If RHDH is already deployed and you want to test against it:

typescript

test.beforeAll(async ({ rhdh }) => {
  // Skip deployment, just use existing instance
  // Set baseURL manually if needed
});

test.beforeEach(async ({ page }) => {
  await page.goto("https://existing-rhdh-url.com");
  // Login manually or use existing session
});

Code Quality Checks

Type Checking

bash

yarn tsc:check

Linting

bash

yarn lint:check
yarn lint:fix  # Auto-fix issues

Formatting

bash

yarn prettier:check
yarn prettier:fix  # Auto-format

All Checks

bash

yarn check

Debugging Tips

1. Use Headed Mode

bash

yarn test:headed

2. Slow Down Execution

Add slowMo to config:

typescript

// playwright.config.ts
export default defineConfig({
  use: {
    launchOptions: {
      slowMo: 500, // 500ms delay between actions
    },
  },
});

3. Take Screenshots

typescript

test("screenshot test", async ({ page }) => {
  await page.goto("/");
  await page.screenshot({ path: "debug.png" });
});

4. View Console Logs

typescript

test("console test", async ({ page }) => {
  page.on("console", (msg) => console.log(msg.text()));
  await page.goto("/");
});

Cleanup

Auto-Cleanup in CI

Automatic Namespace Cleanup

In CI environments (when CI=true), namespaces are automatically deleted after tests complete. This prevents resource accumulation on shared clusters.

For local development, namespaces are preserved for debugging. You must clean them up manually.

Delete Test Namespace

After testing locally, clean up the namespace:

bash

oc delete namespace <test-namespace>

The namespace name is derived from the project name in playwright.config.ts.

Clean Up Playwright Artifacts

bash

rm -rf playwright-report test-results

CI/CD Pipeline - Automated testing
Troubleshooting - Common issues
Directory Layout - File structure

Running Tests Locally ​

Prerequisites ​

Setup ​

1. Navigate to Test Directory ​

2. Install Dependencies ​

3. Install Playwright Browsers ​

Running Tests ​

Run All Tests ​

Run in Headed Mode ​

Run with Playwright UI ​

Run Specific Test File ​

Run Specific Test ​

Viewing Results ​

View HTML Report ​

Report Location ​

Development Workflow ​

1. Write Test ​

2. Run Test ​

3. Debug Failures ​

4. View Trace ​

Test local changes to e2e-test-utils in Overlays ​

Troubleshooting local linking ​

Secrets from Bitwarden ​

Environment Variables ​

Using .env File ​

Common Variables ​

Skipping Keycloak Deployment ​

Running Against Existing Cluster ​

Code Quality Checks ​

Type Checking ​

Linting ​

Formatting ​

All Checks ​

Debugging Tips ​

1. Use Headed Mode ​

2. Slow Down Execution ​

3. Take Screenshots ​

4. View Console Logs ​

Cleanup ​

Auto-Cleanup in CI ​

Delete Test Namespace ​

Clean Up Playwright Artifacts ​

Related Pages ​

Running Tests Locally

Prerequisites

Setup

1. Navigate to Test Directory

2. Install Dependencies

3. Install Playwright Browsers

Running Tests

Run All Tests

Run in Headed Mode

Run with Playwright UI

Run Specific Test File

Run Specific Test

Viewing Results

View HTML Report

Report Location

Development Workflow

1. Write Test

2. Run Test

3. Debug Failures

4. View Trace

Test local changes to e2e-test-utils in Overlays

Troubleshooting local linking

Secrets from Bitwarden

Environment Variables

Using .env File

Common Variables

Skipping Keycloak Deployment

Running Against Existing Cluster

Code Quality Checks

Type Checking

Linting

Formatting

All Checks

Debugging Tips

1. Use Headed Mode

2. Slow Down Execution

3. Take Screenshots

4. View Console Logs

Cleanup

Auto-Cleanup in CI

Delete Test Namespace

Clean Up Playwright Artifacts

Related Pages