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

cd workspaces/<plugin>/e2e-tests

2. Install Dependencies

yarn install

3. Install Playwright Browsers

npx playwright install

Running Tests

Run All Tests

yarn test

Run in Headed Mode

See the browser while tests run:

yarn test:headed

Run with Playwright UI

Interactive test runner:

yarn test:ui

Run Specific Test File

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

Run Specific Test

yarn test -g "test name pattern"

Viewing Results

View HTML Report

After tests complete:

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:

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

yarn test:headed

3. Debug Failures

Use Playwright UI for debugging:

yarn test:ui

4. View Trace

For failed tests, traces are automatically captured:

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:

1. Build the utils package:

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

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

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

Update package.json:

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

1. Reinstall dependencies and run tests:

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:

NODE_PRESERVE_SYMLINKS=1 yarn test:headed

Environment Variables

Using .env File

Create .env for local configuration:

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

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):

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:

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

yarn tsc:check

Linting

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

Formatting

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

All Checks

yarn check

Debugging Tips

1. Use Headed Mode

yarn test:headed

2. Slow Down Execution

Add slowMo to config:

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

3. Take Screenshots

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

4. View Console Logs

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:

oc delete namespace <test-namespace>

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

Clean Up Playwright Artifacts

rm -rf playwright-report test-results

Related Pages

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